- Docs
- Guides
- Build with Enigma
- Python SDK
Look up addresses and government records
Find what is at a street address and get the government records of a business, person, or address.
Look up an address
Section titled “Look up an address”A question about a street address with a house number and no business name searches addresses:
import asyncioimport 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="What is at 1600 Pennsylvania Ave NW, Washington DC?") if not response.is_success(): raise RuntimeError(f"HTTP {response.status_code}: {response.errors}") for address in response.data["search"]: locations = address["operatingLocations"]["edges"] print(f'{address["fullAddress"]}: {len(locations)} operating locations listed')
asyncio.run(main())The query is an entityType: ADDRESS search that returns up to 10 addresses: the building and units in it. When the question names a unit, that unit usually comes first. Each address carries:
- Its address fields, such as
fullAddress,city,state, andzip. - The first page of the operating locations (with brand names), legal entities, and registrations at the address.
No strategy selects the Address counts brandViaLegalEntityCount, brandViaPersonLegalEntityCount, and legalEntityViaRegistrationCount, because they take too long to compute. Leave them out of your own queries too.
An address question that asks how many, other than a headcount, gets an unavailable_data entry with field set to address counts and reason set to out_of_scope, because the query doesn’t count what is at the address. When the question also asks for government records and the SDK adds record fields, each address gets recordCount (see Records on each entity), and the response has no address counts entry.
How questions are read:
- A business name with an address (“the Starbucks at 123 Main St”) is looked up as that business’s location instead.
- A ZIP code alone, a street with no house number, or a business type on a street (“the barbershop on Elm Street”) is refused.
- Before a local strategy returns the query, the SDK cleans the address the LLM extracted:
- It moves a suite, floor, or apartment into
street2in US Postal Service (USPS) short form (STE 1A,FL 8). - It drops a unit designator with no number.
- It removes surrounding prose and a trailing country.
- It converts state names to postal codes.
- It moves a suite, floor, or apartment into
Turn address lookups on or off
Section titled “Turn address lookups on or off”Local strategies take an address_search= argument: True, False, or "auto".
- Without the argument, a strategy reads the
ENIGMA_ADDRESS_SEARCHenvironment variable (on,off, orauto). - When neither is set, it uses
auto. autoturns address lookups on when the API schema for your tier supports them. Each strategy instance decides at its first question for each access tier and keeps that answer. If the schema can’t be fetched at that moment, address lookups stay off for that instance and tier.- With address lookups off, a local strategy handles a question that gives only an address in one of two ways:
- Usually, it refuses the question, raising
UNSUPPORTED_DATA_REQUESTEDorINVALID_QUERY. - Sometimes its LLM takes the address as a business name, and the strategy can return a query that searches for that name.
GenerativeStrategyandAgentStrategyrefuse such a query only when the question uses wording such as “tenants” or “registered at” (see GenerativeStrategy).
- Usually, it refuses the question, raising
- While the API schema the SDK has cached for your tier shows no support for address lookups, a local strategy refuses an address search, whatever
address_searchsays. It raisesUNSUPPORTED_DATA_REQUESTED, and the message ends(bare address lookup). Other address refusals, such as those with address lookups off, can end the same way, so the ending alone doesn’t tell you why the question was refused. - While no schema for your tier is cached yet,
TemplateStrategyandGenerativeStrategywith address lookups turned on (address_search=TrueorENIGMA_ADDRESS_SEARCH=on) still write address lookups.
Get government records
Section titled “Get government records”To get an entity’s government records, name the entity and ask for its records, as in “Show business licenses held by Walgreens”.
The records come from Enigma’s Gov Archive, which holds rows of government and public datasets, such as state Uniform Commercial Code (UCC) filings, business licenses, and city food inspections:
- Each row is a record.
- Enigma links most records to the businesses, locations, people, and addresses they name.
- Each dataset carries tags, such as
ucc_lien, that name the types of records it holds.
You can ask for these record types:
- UCC and lien filings
- Business and occupational licenses, including liquor, contractor, tobacco and cannabis, insurance, money transmitter, firearms, and childcare licenses
- Permits and sales tax permits
- Inspections and health grades
- Violations and enforcement actions
- Government contracts, Paycheck Protection Program (PPP) loans, and SAM.gov registrations, including Unique Entity IDs (UEI) and CAGE codes
- Form 5500 benefit plans, H-1B and labor certifications, workers’ compensation, and Worker Adjustment and Retraining Notification (WARN) layoff notices
- Securities and Exchange Commission (SEC) filings, 13F holdings, and Form 990 filings
- Property records, Environmental Protection Agency (EPA) records, and US Department of Transportation (USDOT) motor carrier records
- Campaign finance and lobbying
- Medicare and Medicaid providers, and minority-, women-, and veteran-owned business certifications
How a question is read:
- A question that asks for “public records”, “government records”, or the “gov archive” in general gets records of every type, unless it also names one of the preceding types.
- Words in the names a question searches by don’t count, so a question about a business named “Permit Pros” asks for no permits.
The response holds records in two places:
- On each entity
searchreturns (see Records on each entity). - In archive searches: searches of the Gov Archive that the SDK adds to the query next to
search, answered under keys that start witharchiveRecordsorarchiveBrandRecords(see Records from archive searches).
This example prints both:
import asyncioimport 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())Records on each entity
Section titled “Records on each entity”Each entity the search returns gains recordCount. Whether it also gets a records page depends on the question and on the API:
- For a question that names record types, the SDK adds the page and
matchingRecordCountonly when the API can filter an entity’s linked records quickly, which the SDK tells from the API schema. Otherwise, the entities get neither, and those records come from the archive searches alone. - A question asking for records in general gets the
recordspage either way.
Read the page with entity.get("records").
| Field | Where | Holds |
|---|---|---|
recordCount |
Every returned entity | The number of records linked to the entity, over every dataset |
recordSourceCounts, recordTagCounts |
A returned address | The record count per dataset title and per tag |
recordSources |
A returned legal entity | The first three of its registeredEntities, with page info. Each carries recordSourceCounts and recordTagCounts. |
matchingRecordCount |
An entity that gets a records page, for a question that names record types |
The number of its linked records of those types |
records |
An entity that gets a records page |
The linked records, with pageInfo { hasNextPage endCursor }: the first ten when the search is limited to one entity (conditions: { limit: 1 }), otherwise the first three. For a question that names record types, only records of those types. |
Legal entities the query selects under a returned brand or location also get:
recordCount.- Their first three
records, when the returned entities get arecordspage.
Records from archive searches
Section titled “Records from archive searches”An archive search searches the Gov Archive by the same name or person (first and last name) as the search it sits beside, and by that search’s address when the address has a street line. It takes the whole address: street line, unit, city, state, and ZIP code.
Which archive searches a query gets:
- A search by name, by a person’s first and last name, or by a street address gets
archiveRecords, with two exceptions:- A street address alone, with no name or person’s first and last name, gets one only in an
entityType: ADDRESSsearch. - In a
PERSONsearch,namedoesn’t count; only the person’s first and last name do.
- A street address alone, with no name or person’s first and last name, gets one only in an
- A name search with
entityType: BRAND,entityType: OPERATING_LOCATION, or noentityTypegets two archive searches:archiveRecordssearches legal entities.archiveBrandRecordssearches brands, which finds records that name a brand or trade name.- Neither one searches by a person’s first and last name, even when the
searchhas them. - The two can return the same record.
- A search with no name, person, or street address, such as one by website alone, gets no archive search.
- When several searches in the query get archive searches, the keys of the second and later ones end in a number, as in
archiveRecords2. The number counts only the searches that get archive searches, so it need not match the number of thesearchkey beside it. - An archive search identical to an earlier one is sent once.
What each archive search returns:
- First, the entities it matched, with only
__typename(and, for a person,__url). - Then up to 50 records: the items whose
__typenameisRecord. It returns a record when the record’s data names the searched name or address, whether or not the record is linked to an entity. - For a question that names record types, each record carries one of their tags. A question for records in general gets records with any tag.
- One page, with no cursor to read more.
Check what you get:
- The archive matches names loosely, so a record can belong to another business or person with a similar name. Unless the searched address has a street line, the archive search gets no city or state, so that namesake can be anywhere. Check the name in the record’s
data. - A dataset can carry a record type’s tag without belonging to it, so check
sourceTitle. - Records are not sorted by date.
- The archive searches miss many records of these types: UCC and lien filings, contractor licenses, PPP loans, government contracts, SAM.gov registrations, workers’ compensation, lobbying, and Form 990 filings. When the entities get no
recordspage, a question for these types often returns few records or none.
To leave the archive searches out of queries a local strategy writes, set ENIGMA_ARCHIVE_SEARCH=off.
For the example question, the query gains recordCount on each entity it returns, and archive searches next to search. The archiveRecords search, abbreviated:
archiveRecords: search(searchInput: { name: "Walgreens", entityType: LEGAL_ENTITY, dataLayer: UNGROUNDED, conditions: { limit: 50, filter: { IN: ["tags", ["abc_license", "active_occupational_licenses", ...]] } } }) { __typename ... on Record { sourceTitle sourceUrl tags firstObservedDate lastObservedDate data }}dataLayer: UNGROUNDED makes the search read the archive’s records directly, whether or not they are linked to an entity.
What each record holds
Section titled “What each record holds”Each record, on an entity or in an archive search, carries:
sourceTitle: the dataset’s title.sourceUrl: a link to the dataset, not to the row. It can be null.tags: the dataset’s tags, such asucc_lienorabc_license.firstObservedDate,lastObservedDate: when Enigma first and last saw the row. These are usually not filing dates.data: the row itself, as column names and values. The filing dates are here.
Read more of an entity’s records
Section titled “Read more of an entity’s records”When an entity’s records page has pageInfo.hasNextPage set to true, read the next page:
- Search that entity alone by its id:
searchInput: { id: "<its id>", entityType: <its type>, conditions: { limit: 1 } }. SetentityTypetoBRAND,LEGAL_ENTITY,OPERATING_LOCATION,PERSON, orADDRESSto match its__typename. - Select
recordswith the samefirstandconditionsas before, plusafter: "<endCursor>". The cursor is only valid for those arguments.
To get a query to adapt, call generate_query.
Record types and their phrases
Section titled “Record types and their phrases”The installed package lists the record types a question can ask for, with the phrases that ask for each and the tags that select it:
import jsonfrom importlib.resources import files
path = files("enigma_api_client") / "plugins/enigma-api/skills/enigma-graphql/references/record_topics.json"for topic in json.loads(path.read_text())["record_topics"]["topics"]: print(topic["id"], topic["phrases"][:3])Records and unavailable data
Section titled “Records and unavailable data”- An
unavailable_dataentry for something the selected records answer in full, such as “liquor licenses”, is removed. - When the query selects record counts but none of the records the question asks for, the SDK keeps each entry those records would answer in full and gives it the message “This query does not return these records.” This happens, for example, on a search by website alone when the entities get no
recordspage. - When the query selects the records, an entry for something they answer only in part, such as “tax liens” or “lawsuits and violations”, gets the message “The returned records cover this only in part.”
Records and the API schema
Section titled “Records and the API schema”A local strategy adds records only once it has the API schema for your tier.
TemplateStrategy fetches the schema as follows:
- With
address_searchset toauto, the default, it fetches the schema before it answers its first question, because it needs the schema to decide on address lookups. - If you set address lookups yourself (
address_search=TrueorFalse, orENIGMA_ADDRESS_SEARCHset toonoroff), it doesn’t wait for the schema; it fetches it in the background. Until the schema arrives, its answers can come without records, andgenerate_queryreportsrecordsasno_schema. - After its first fetch fails, it starts another background fetch only when it finishes generating a query, so it starts none while no questions come in. These fetches start at most once every five minutes, or once every
refresh_secondsseconds when you pass a number asrefresh_secondstoset_schema_introspector. Until a fetch succeeds, its answers lack records.
GenerativeStrategy and AgentStrategy fetch the schema while they answer their first question, even when you set address lookups yourself. After a failed fetch, they try again on their next question.
GenerativeStrategyfetches it before it writes its first query whenaddress_searchisauto, and otherwise when it checks that query. Until a fetch succeeds, its answers lack records.AgentStrategyfetches it before its agent starts. Until a fetch succeeds, it raisesPROVIDER_ERROR.