---
title: "Resolve Address"
method: POST
path: "/api/v1/project/address/resolve"
tags: ["project"]
---

# Resolve Address

`POST /api/v1/project/address/resolve`

Resolve free text to ranked, label-hydrated candidates for address entry.

Pre-project: bounded to ``request.county_fips`` when the caller picked a
county first, otherwise across every county the caller's workspace has
loaded (the sandbox partition is the access control either way). A read
failure surfaces as 503 rather than the raw error, which can carry a
sandbox connection URI.

## Request body

- AddressResolveRequest — Autocomplete resolve for address entry: free text (street address, place name, or parcel number) — no project exists yet on this path. ``county_fips`` (5-digit GEOID) bounds the match to the picked county; absent, it matches across every county the caller's workspace has loaded.
  - `query` string, required
  - `county_fips` string, nullable

## Response `200`

Successful Response

- AddressResolveResponse — Ranked, label-hydrated candidates for one resolve. ``not_in_dataset`` means the reference isn't in any county the workspace has loaded — the surface reports "not in your coverage" rather than an empty dropdown.
  - `outcome` 'matched' | 'not_in_dataset' | 'not_loaded_county', required — Result classification. ``not_loaded_county`` (a real reference in a county this workspace hasn't loaded) is reserved for the forward-geocoder path, the only place able to confirm a reference is real and name its county.
  - `candidates` AddressCandidate[]
    - `source_table` 'parcel' | 'building' | 'place' | 'address' | 'school', required — The table a resolved feature lives in — what a caller pulls its data from, and the feature's kind. A text match in the ``address``, ``place`` or ``school`` table resolves (point-in-feature) to a ``parcel``/``building``; a ``parcel`` attribute match resolves to the parcel itself.
    - `feature_id` string, required
    - `label` string, required
    - `similarity` number, nullable
    - `matched_via` string, required
    - `county_fips` string, nullable

## Other responses

- `422` — Validation Error

---

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