> ## 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.

# What is a geo_id and How Do I Get One?

> A geo_id is Shovels' unified geographic identifier for addresses, zip codes, cities, counties, jurisdictions, and states. Each geography level has its own search endpoint for resolving a geo_id.

**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 Level | Example geo\_id | Resolve with |
| - | - | - |
| State | `CA` | [Search States](https://docs.shovels.ai/api-reference/states/search-states.md) |
| Zip Code | `94103` | [Search Zipcodes](https://docs.shovels.ai/api-reference/zipcodes/search-zipcodes.md) |
| County | `Q291bnR5XzEyMzQ1` | [Search Counties](https://docs.shovels.ai/api-reference/counties/search-counties.md) |
| City | `Q2l0eV8xMjM0NQ` | [Search Cities](https://docs.shovels.ai/api-reference/cities/search-cities.md) |
| Jurisdiction | `Q2l0eV8xMjM0NQ` | [Search Jurisdictions](https://docs.shovels.ai/api-reference/jurisdictions/search-jurisdictions.md) |
| Address | `MDEyMzQ1Njc4OWFiY2RlZg==` | [Search Addresses](https://docs.shovels.ai/api-reference/addresses/search-addresses.md) |

> [!TIP]
>
> 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:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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`)

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
GET /v2/permits/search?geo_id=CA&permit_from=2024-01-01
```

To confirm coverage or look up the exact value, use [Search States](https://docs.shovels.ai/api-reference/states/search-states.md) or [Search Zipcodes](https://docs.shovels.ai/api-reference/zipcodes/search-zipcodes.md).

## 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:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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](https://docs.shovels.ai/api-reference/counties/search-counties.md) and [Search Jurisdictions](https://docs.shovels.ai/api-reference/jurisdictions/search-jurisdictions.md).

## 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

## Related Articles

* [Resolving addresses](https://docs.shovels.ai/docs/knowledge-base/api/address-resolution/resolving-addresses.md)
* [Error handling for geo\_id](https://docs.shovels.ai/docs/knowledge-base/api/errors/error-handling.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.