---
title: "Search Addresses"
method: GET
path: "/addresses/search"
tags: ["Addresses"]
---

# Search Addresses

`GET /addresses/search`

Searches addresses by their text fields (street number, street, city, state, and ZIP code) using prefix, full-text, and fuzzy matching.

## Query parameters

- `q` string, required — The text to search for in the address fields.

## Response `200`

A list of addresses that match the search text, ordered by relevance and in USPS notation.

- PaginatedAddressesResponse — Paginated response for addresses.
  - `items` ApiAppModelsGeoAddressesRead[], required — The list of items returned in the response following given criteria.
    - `street_no` string, nullable — The number of the street of the address.
    - `street` string, nullable — The name of the street of the address.
    - `city` string, nullable — The city of the address.
    - `county` string, nullable — The county of the address.
    - `zip_code` string, nullable — The ZIP code of the address.
    - `zip_code_ext` string, nullable — The extension of the ZIP code of the address.
    - `state` string, nullable — The state of the address.
    - `jurisdiction` string, nullable — The jurisdiction the address belongs to.
    - `lat` number, nullable
    - `long` number, nullable
    - `geo_id` string, required — Geolocation ID
    - `name` string, required — Formatted address name
  - `size` integer, required — The number of items returned in the response.
  - `next_cursor` string, nullable, required — The cursor for retrieving the next page of results.
  - `total_count` TotalCount — Capped result count with Elasticsearch-style {value, relation} shape. When the exact count is known and within the cap, relation is "eq" and value is that exact count. When the count exceeds the cap, relation is "gte" and value is the cap the count was probed against, meaning "the actual count is at least value". The cap is COUNT_CAP for every wire-facing endpoint; internal guard paths probe against their own cap, so value carries whatever cap produced it.
    - `value` integer, required — The count value; capped at the probe's cap (10,000 on the wire).
    - `relation` 'eq' | 'gte', required — "eq" means value is the exact count. "gte" means the actual count is at least value (the cap).

## Other responses

- `404` — The specified search query didn't match any addresses
- `422` — Validation Error

---

[API](https://skmtc.net/shovels/apis/the-shovels-api-v2.md) · [All operations](https://skmtc.net/shovels/apis/the-shovels-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shovels/the-shovels-api-v2/revisions/d3f0e1f3afa8/schema)