Skip to content
Console(opens in a new tab)

Gov Archive records

Get government records about a business, a person, or an address from the GraphQL API and the Python SDK.

This guide shows you how to search government records about a business using Gov Archive. You can query permits, violations, filings, licenses, and other regulatory records from 7,000+ federal, state, and municipal datasets, through the Python SDK or directly with the GraphQL API.

Get records from a question with the Python SDK

Section titled “Get records from a question with the Python SDK”

The Enigma Python SDK, enigma-api-client, turns a question in plain English into a GraphQL query and runs it. When your question names a business, location, person, or address and asks for its government records, the query selects them in two places:

  • On each entity: the number of records Enigma links to that entity and, for some questions, a page of them.
  • In archive searches: searches of Gov Archive by the same name, person, or street address, under keys that start with archiveRecords or archiveBrandRecords. Each returns up to 50 of the records that name what it searched for, whether or not Enigma links them to an entity.

The SDK needs Python 3.11 or later and your Enigma API key.

Terminal window
pip install enigma-api-client
export ENIGMA_API_KEY="your-api-key"
import asyncio
import os
from enigma_api_client import Client, ClientConfig
async def main():
config = ClientConfig(enigma_api_key=os.environ["ENIGMA_API_KEY"])
async with Client(config) as client:
response = await client.search(prompt="Show business licenses held by Walgreens")
if not response.is_success():
raise RuntimeError(f"HTTP {response.status_code}: {response.errors}")
for entity in response.data["search"]:
print(entity["__typename"], "linked records:", entity.get("recordCount"))
for key, items in response.data.items():
if key.startswith(("archiveRecords", "archiveBrandRecords")):
for item in items or []:
if item["__typename"] == "Record":
print(key, item["sourceTitle"], item["data"])
asyncio.run(main())

A question asks for records when it names a record type the SDK reads, such as UCC and lien filings, licenses, permits, inspections, violations, government contracts, PPP loans, SAM.gov registrations, Form 5500 benefit plans, or EPA records. The archive searches then keep only the records that carry a tag of the types the question names. A dataset can carry a record type’s tag without belonging to that type, so check sourceTitle. A question that asks for public or government records in general gets records of every type, unless it also names a type the SDK reads. Records aren’t sorted by date.

Each record has sourceTitle, sourceUrl, tags, firstObservedDate, lastObservedDate, and data, the original row as key-value pairs. sourceUrl links to the dataset, not to the row, and can be null. The observed dates tell you when Enigma first and last saw the row; the record’s own dates, such as a filing date, are in data. See Record for every field.

Get government records in the Python SDK guide lists every record type a question can ask for, the fields each entity gets, which archive searches a query gets, and how to read more of an entity’s records. Each archive search is an UNGROUNDED search; for every record a search finds, page by page, use a RECORD search.

The GraphQL API returns Gov Archive records alongside Enigma’s business data. Send each query as the query field of a JSON body in a POST request to https://api.enigma.com/graphql, with your API key in the x-api-key header. Each record is one row of a government dataset.

You can get records in three ways:

  • Linked records: records that Enigma has matched to a business, person, or address. You reach them through the records field of an entity such as a legal entity, brand, operating location, person, or address, and you can count, filter, and page through them.
  • UNGROUNDED search results: records whose stated business name, person name, or address matches your search. Set dataLayer: UNGROUNDED in a search to get them as Record results.
  • A RECORD search: every linked record a search finds and, with dataLayer: UNGROUNDED, the records matched by name or address, with paging and totals. Set entityType: RECORD.
query {
search(searchInput: {name: "Starbucks Corporation", entityType: LEGAL_ENTITY, conditions: {limit: 1}}) {
... on LegalEntity {
id
recordTotal: count(field: "records")
records(first: 10) {
pageInfo { hasNextPage endCursor }
edges {
node {
sourceTitle
sourceUrl
tags
firstObservedDate
data
}
}
}
}
}
}
Field Description
sourceTitle The dataset’s title as published by its source
sourceDescription The dataset’s description as published by its source
sourceUrl A link to the source dataset, not to the individual record; often null
tags Keywords describing the record’s dataset (subject, record type, and jurisdiction), such as business_license, ucc_lien, federal, or tx
data The original row as key-value pairs
firstObservedDate, lastObservedDate When Enigma first and last observed the record, usually not the record’s own dates; use the dates in data, such as a filing date

count(field: "records") returns the number of linked records without fetching them. To get the next page, pass the endCursor value as after, for example records(first: 10, after: "<endCursor>").

Filter linked records by tag or dataset title

Section titled “Filter linked records by tag or dataset title”

Pass a filter in conditions on records or count:

  • By tag: {CONTAINS: ["tags", ["business_license"]]} matches records whose dataset carries every listed tag. To match any of several tags, combine clauses with OR: {OR: [{CONTAINS: ["tags", ["business_license"]]}, {CONTAINS: ["tags", ["ucc_lien"]]}]}.
  • By dataset title: {IN: ["sourceTitle", ["Business Licenses", "UCC Liens"]]} matches those exact titles. Titles are not unique across sources, so use ILIKE for a pattern, or a tag for a subject. EQ also works on sourceTitle.
  • Large entities: on an entity with many linked records, a filtered count or page can take longer than the request allows. Count without a filter, or search the archive by name with UNGROUNDED, which filters by tag.
query {
search(searchInput: {name: "Starbucks Corporation", entityType: LEGAL_ENTITY, conditions: {limit: 1}}) {
... on LegalEntity {
licenseTotal: count(field: "records", conditions: {filter: {CONTAINS: ["tags", ["business_license"]]}})
records(first: 5, conditions: {filter: {CONTAINS: ["tags", ["business_license"]]}}) {
edges { node { sourceTitle tags data } }
}
}
}
}

Registered entities (a business as recorded across its state registrations) and addresses also have summary fields:

  • recordCount: the number of linked records, returned as a string
  • recordSourceCounts: the number of records per dataset title
  • recordTagCounts: the number of records per tag
query {
search(searchInput: {name: "Starbucks Corporation", entityType: LEGAL_ENTITY, conditions: {limit: 1}}) {
... on LegalEntity {
registeredEntities(first: 5) {
edges { node { recordCount recordSourceCounts recordTagCounts } }
}
}
}
}

Set dataLayer: UNGROUNDED in searchInput. The search returns the matching businesses as usual, plus Record results. Select the records with an inline fragment on Record; __typename tells businesses and records apart:

query {
search(searchInput: {
name: "Chipotle Mexican Grill",
entityType: LEGAL_ENTITY,
dataLayer: UNGROUNDED,
address: {state: "TX"},
conditions: {limit: 20, filter: {CONTAINS: ["tags", ["liquor_license"]]}}
}) {
__typename
... on LegalEntity { id }
... on Record { sourceTitle tags data }
}
}
  • Address: street1, city, postalCode, and state in address narrow the Record results.
  • Brands: with entityType: BRAND, the Record results match the name against brand names, such as DBAs, instead of registered business names, which any other entityType, or none, matches. A RECORD search matches both.
  • Filtering: conditions.filter narrows the Record results only. It accepts tags with EQ, IN, or CONTAINS, combined with AND; use IN to match any of several tags. Any other filter, including OR or sourceTitle, returns the businesses and an error, with no records.
  • Limits: by default a search returns up to 10 businesses and 50 records. conditions.limit sets both caps, and records stop at 1,000. A search can return fewer records than exist, and its Record results have no total or paging, so treat them as a sample. For a complete list with totals, use a RECORD search.
  • Counts per entity: on the legal entities, people, or addresses any search returns, count(field: "records", dataLayer: UNGROUNDED) counts the records whose stated name or address is exactly one of that entity’s names, or its address, ignoring case, spacing, and punctuation. Select it on the search’s own results; on an entity nested under them it is an error. It takes no conditions. It is null when an entity has more than 20 names, a name too short to look up, or the count takes longer than 5 seconds.
  • Duplicates: the search leaves out any record that the same response returns in a business’s records, so the Record results change with your selection.
  • Timeouts: if the record lookup takes longer than 20 seconds, the response keeps the businesses and adds an error, with no records. Retrying can succeed.
  • Scope: aggregate queries do not support dataLayer: UNGROUNDED, and searches that set output return no Record results.

Set entityType: RECORD to list every record a search finds, page by page, with totals. The search returns one Record that stands for the whole search: its records field pages through the records, count(field: "records") returns the totals, and its id identifies the search. Its other fields are null.

query ($after: String) {
search(searchInput: {name: "Sunrise Dental", entityType: RECORD, dataLayer: UNGROUNDED}) {
... on Record {
total: count(field: "records")
linkedTotal: count(field: "records", dataLayer: GROUNDED)
matchedTotal: count(field: "records", dataLayer: UNGROUNDED)
records(first: 100, after: $after) {
pageInfo { hasNextPage endCursor }
edges { node { sourceTitle tags data } }
}
}
}
}
  • Which records: search by a name, a person, or an address with street1. By default, the search lists the records linked to the businesses, people, or addresses it matches: up to 250 legal entities for a name, up to 100 people for person, or up to 100 addresses for an address alone. With dataLayer: UNGROUNDED, the records whose stated name or address matches follow, each record listed once; there a name matches registered business names and brand names, such as DBAs. Add address fields to narrow the search; a state with no other address field narrows legal entities and matched records, not people.
  • Totals: count(field: "records") counts every record the search lists. With dataLayer: GROUNDED it counts the linked records, and with dataLayer: UNGROUNDED the records matched by stated name or address, linked or not. Once counted, a total is the same on every page. A total that takes longer than 5 seconds is null with an error on that page and every later one; start again without a cursor to count it again. Large searches often have no UNGROUNDED total, so the default total of an UNGROUNDED search is null too, and paging works without either.
  • Paging: first and after page forward; last and before page backward, and last alone starts from the end. Mixing the two directions is an error. A page holds 100 records by default and at most 1,000. Pass endCursor as after until hasNextPage is false. A page stops reading 20 seconds after the request starts, so it can hold fewer records than you asked for, even none, while hasNextPage is true: keep paging. If its first read does not finish in time, the page returns an error instead; retry the same page in a request of its own, or with a smaller first or last. An edge’s cursor resumes right after its record.
  • Cursors: a cursor works only with the search that returned it. If you change searchInput (other than conditions.limit), or Enigma’s data is refreshed, the cursor is rejected; start again without one.
  • Errors: prompt, id, tin, output, more than one fields group, conditions.filter, conditions.orderBy, and conditions.pageToken return an error. conditions.limit has no effect.
Category Examples
Business registrations Secretary of State filings, DBA registrations
Permits and licenses Liquor, cannabis, professional licenses, business permits
Health and safety Food safety inspections, health code violations, building code violations
Court filings and liens UCC liens, bankruptcy filings, active litigation
Environmental compliance EPA records, Clean Air Tracking System, brownfield/site remediation
Workplace safety OSHA violations, citations, worker fatality records
Government contracts USA Spending data, vendor payment records
Financial incentives State economic incentive programs, tax credits

Gov Archive queries are GraphQL queries, including the ones the Python SDK sends, so they follow the GraphQL API rate limits.