Skip to content
Console(opens in a new tab)

Look up addresses and government records

Find what is at a street address and get the government records of a business, person, or address.

A question about a street address with a house number and no business name searches addresses:

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="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, and zip.
  • 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 street2 in 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.

Local strategies take an address_search= argument: True, False, or "auto".

  • Without the argument, a strategy reads the ENIGMA_ADDRESS_SEARCH environment variable (on, off, or auto).
  • When neither is set, it uses auto.
  • auto turns 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_REQUESTED or INVALID_QUERY.
    • Sometimes its LLM takes the address as a business name, and the strategy can return a query that searches for that name. GenerativeStrategy and AgentStrategy refuse such a query only when the question uses wording such as “tenants” or “registered at” (see GenerativeStrategy).
  • 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_search says. It raises UNSUPPORTED_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, TemplateStrategy and GenerativeStrategy with address lookups turned on (address_search=True or ENIGMA_ADDRESS_SEARCH=on) still write address lookups.

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 search returns (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 with archiveRecords or archiveBrandRecords (see Records from archive searches).

This example prints both:

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())

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 matchingRecordCount only 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 records page 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 a records page.

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: ADDRESS search.
    • In a PERSON search, name doesn’t count; only the person’s first and last name do.
  • A name search with entityType: BRAND, entityType: OPERATING_LOCATION, or no entityType gets two archive searches:
    • archiveRecords searches legal entities.
    • archiveBrandRecords searches 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 search has 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 the search key 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 __typename is Record. 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 records page, 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.

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 as ucc_lien or abc_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.

When an entity’s records page has pageInfo.hasNextPage set to true, read the next page:

  1. Search that entity alone by its id: searchInput: { id: "<its id>", entityType: <its type>, conditions: { limit: 1 } }. Set entityType to BRAND, LEGAL_ENTITY, OPERATING_LOCATION, PERSON, or ADDRESS to match its __typename.
  2. Select records with the same first and conditions as before, plus after: "<endCursor>". The cursor is only valid for those arguments.

To get a query to adapt, call generate_query.

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 json
from 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])
  • An unavailable_data entry 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 records page.
  • 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.”

A local strategy adds records only once it has the API schema for your tier.

TemplateStrategy fetches the schema as follows:

  • With address_search set to auto, 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=True or False, or ENIGMA_ADDRESS_SEARCH set to on or off), it doesn’t wait for the schema; it fetches it in the background. Until the schema arrives, its answers can come without records, and generate_query reports records as no_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_seconds seconds when you pass a number as refresh_seconds to set_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.

  • GenerativeStrategy fetches it before it writes its first query when address_search is auto, and otherwise when it checks that query. Until a fetch succeeds, its answers lack records.
  • AgentStrategy fetches it before its agent starts. Until a fetch succeeds, it raises PROVIDER_ERROR.