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.

To search for permits in the Shovels API, you’ll use the geo_id parameter as the unique identifier linking addresses to their permit data.

​
Two-Step Process

​
Step 1: Get the Address’s geo_id

Use the Search Addresses endpoint with your target address: 
curl -X GET \
  "https://api.shovels.ai/v2/addresses/search?street=123+Main+St&city=San+Francisco&state=CA" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
This returns the address’s geo_id—a unique identifier you’ll need for the next step.

​
Step 2: Search Permits Using the geo_id

Use the Search Permits endpoint with the geo_id and your desired date range: 
curl -X GET \
  "https://api.shovels.ai/v2/permits/search?geo_id=ADDRESS_GEO_ID&permit_from=2020-01-01&permit_to=2024-12-31" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
The geo_id parameter is a unified geography filter. The same permit search works whether you pass a state abbreviation (CA), a zip code (94103), or an individual address’s geo_id. You’re just swapping out the geography level.

​
Available Filters

The permit search endpoint supports additional filters:
  • Date ranges (permit_from, permit_to)
  • Permit types and subtypes
  • Property types (residential, commercial)
  • Contractor information
  • Tags for specific permit categories

​
Alternative: Shovels Online

For quick lookups without code, use the Location Search feature in Shovels Online to search by address directly.

​
Best Practices

  1. Always resolve addresses first to get accurate geo_ids
  2. Use date ranges to limit result sets
  3. Apply filters to get exactly the permits you need
  4. Handle pagination for large result sets