Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt

Use this file to discover all available pages before exploring further.

A geo_id is Shovels’ unified geographic identifier that can represent a state (CA), zip code (94103), city, or specific address. To get a geo_id for an address, use the Address Search endpoint (GET /v2/addresses/search). The returned geo_id is then used to query permits. The address search endpoint returns the geo_id associated with an address: 
curl -X GET \
  "https://api.shovels.ai/v2/addresses/search?street=123+Main+St&city=San+Francisco&state=CA&zip=94102" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

​
Understanding geo_id

The geo_id is a unified geography identifier that works at multiple levels:
Geography LevelExample geo_id
StateCA
Zip Code94103
CityCity-specific ID
AddressAddress-specific ID
The same permit search works whether you pass a state abbreviation, zip code, or individual address geo_id—you’re just changing the geography level.

​
geo_id for State Searches

For state-level searches, use the 2-letter state abbreviation as the geo_id:
  • California = CA
  • Texas = TX
  • Florida = FL
GET /v2/permits/search?geo_id=CA&permit_from=2024-01-01

​
What If No geo_id Is Found?

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