> ## 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](/api-reference/states/search-states)                      |
| Zip Code        | `94103`                    | [Search Zipcodes](/api-reference/zipcodes/search-zipcodes)                |
| County          | `Q291bnR5XzEyMzQ1`         | [Search Counties](/api-reference/counties/search-counties)                |
| City            | `Q2l0eV8xMjM0NQ`           | [Search Cities](/api-reference/cities/search-cities)                      |
| Jurisdiction    | `Q2l0eV8xMjM0NQ`           | [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions) |
| Address         | `MDEyMzQ1Njc4OWFiY2RlZg==` | [Search Addresses](/api-reference/addresses/search-addresses)             |

<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.
</Tip>

## 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={null}
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={null}
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={null}
GET /v2/permits/search?geo_id=CA&permit_from=2024-01-01
```

To confirm coverage or look up the exact value, use [Search States](/api-reference/states/search-states) or [Search Zipcodes](/api-reference/zipcodes/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:

```bash theme={null}
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](/api-reference/counties/search-counties) and [Search Jurisdictions](/api-reference/jurisdictions/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

## Related Articles

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