Skip to main content
A geo_id is Shovels’ unified geographic identifier that can represent a state (CA), zip code (94103), city, county, jurisdiction, or specific address. Once you have a geo_id, you pass it to other endpoints (such as permit search) to query data at that geography level. Each geography level has its own search endpoint for resolving a geo_id. For an address-level geo_id, use the Address Search endpoint (GET /v2/addresses/search).

​
Understanding geo_id

The geo_id is a unified geography identifier that works at multiple levels. State and zip code geo_ids are human-readable, while city, county, jurisdiction, and address geo_ids are opaque encoded strings:
Geography LevelExample geo_idResolve with
StateCASearch States
Zip Code94103Search Zipcodes
CountyQ291bnR5XzEyMzQ1Search Counties
CityQ2l0eV8xMjM0NQSearch Cities
JurisdictionQ2l0eV8xMjM0NQSearch Jurisdictions
AddressMDEyMzQ1Njc4OWFiY2RlZg==Search Addresses
The same permit search works whether you pass a state abbreviation, zip code, or city/address geo_id—you’re just changing the geography level.

​
Getting an Address geo_id

The Address Search endpoint returns the geo_id associated with an address. Pass your search text in the required q parameter: 
curl -X GET \
  "https://api.shovels.ai/v2/addresses/search?q=123+Main+St,+San+Francisco,+CA" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
The returned address geo_id is an opaque encoded string. Use it to query permits: 
GET /v2/permits/search?geo_id=ADDRESS_GEO_ID&permit_from=2024-01-01

​
State and Zip geo_ids

State and zip code geo_ids are human-readable, so you can often use them directly without a lookup:
  • State: the 2-letter abbreviation (California = CA, Texas = TX, Florida = FL)
  • Zip code: the 5-digit ZIP, optionally with a 4-digit extension (94103 or 94103-1234)
GET /v2/permits/search?geo_id=CA&permit_from=2024-01-01
To confirm coverage or look up the exact value, use Search States or Search Zipcodes.

​
City, County, and Jurisdiction geo_ids

City, county, and jurisdiction geo_ids are opaque encoded strings, so you can’t construct them by hand. Resolve them through their dedicated search endpoints first, then pass the returned geo_id to your query: 
curl -X GET \
  "https://api.shovels.ai/v2/cities/search?q=San+Francisco,+CA" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
The same pattern applies to Search Counties and Search Jurisdictions.

​
What If No geo_id Is Found?

If the address or jurisdiction isn’t in our system, the API returns a 200 response with an empty items array. This means:
  • The address format was understood
  • No matching address or jurisdiction exists for that query in our database