Skip to main content
POST
/
addresses
/
resolve
{
  "object": "address.resolution_result",
  "created": 1764892800,
  "input": {
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "normalized": "1600 Amphitheatre Parkway, Mountain View, CA 94043, United States",
  "components": {
    "street_number": "1600",
    "thoroughfare": {
      "name": "Amphitheatre Parkway"
    },
    "localities": [
      {
        "name": "Mountain View",
        "type": "city"
      }
    ],
    "admin_areas": [
      {
        "name": "California",
        "code": "CA",
        "type": "state",
        "level": 1
      }
    ],
    "region": "California",
    "region_code": "CA",
    "postal_code": "94043",
    "country": "United States",
    "country_code": "US",
    "address_lines": [
      "1600 Amphitheatre Parkway",
      "Mountain View, CA 94043",
      "United States"
    ],
    "canonical_form": "1600 AMPHITHEATRE PARKWAY, MOUNTAIN VIEW, CA 94043, US",
    "coordinates": {
      "lat": 37.4224764,
      "lng": -122.0842499
    },
    "metadata": {
      "confidence": 0.95,
      "address_type": "commercial",
      "deliverability": "deliverable",
      "timezone": "America/Los_Angeles"
    }
  }
}
Normalizes an address into a clean, canonical form. Optionally validates deliverability and consistency. By default, only normalization is performed. Set validate: true in options to include deliverability and consistency checks in the response.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
terrakit-version
string
required

API version in YYYY-MM-DD format.

​
idempotency-key
string

Provide on POST requests to make them idempotent for safe retries.

Body

application/json

Request to resolve an address into normalized, structured format.

​
address
string
required

Free-form address text.

​
structured
object

A structured representation of a postal address designed for global coverage. Compatible with the Universal Postal Union (UPU) standards, CLDR address formats, and major geocoding providers. Supports addresses from all countries including complex East Asian, Middle Eastern, and rural addressing systems.

​
options
object

Optional processing instructions for address resolution.

Response

OK

Result of address resolution. Fields present depend on options.

​
object
string
required
Allowed value: "address.resolution_result"
​
created
integer
required

Epoch seconds.

​
input
object
required
​
metadata
object

Arbitrary key/value pairs attached to the request; echoed in results.

​
normalized
string | null

Canonical single-line address in requested format (e.g., postal).

​
components
object

A structured representation of a postal address designed for global coverage. Compatible with the Universal Postal Union (UPU) standards, CLDR address formats, and major geocoding providers. Supports addresses from all countries including complex East Asian, Middle Eastern, and rural addressing systems.

​
validation
object

High-level quality assessment of the resolved address.

​
id
string | null

Present only if the result is persisted.

​
result_url
string | null