> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terrakit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve an Address

> Normalize and optionally validate an address

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.


## OpenAPI

````yaml POST /addresses/resolve
openapi: 3.1.0
info:
  title: TerraKit API
  version: '2025-10-04'
  description: >
    TerraKit is the API platform for developers and AI systems that need clean,
    structured, and precise real-world data.
servers:
  - url: https://api.terrakit.dev/v1
security:
  - bearerAuth: []
tags:
  - name: addresses
    description: Operations for resolving (canonicalizing + validating) address data.
paths:
  /addresses/resolve:
    post:
      tags:
        - addresses
      summary: Resolve an address
      description: >
        Resolves free-form or structured address input into a normalized,
        structured format.


        By default, only normalization is performed. Set `validate: true` in
        options to include deliverability and consistency checks in the
        response.
      operationId: resolveAddress
      parameters:
        - $ref: '#/components/parameters/TerraKitVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressResolveRequest'
            examples:
              free_form:
                $ref: fa75be35-330b-4e82-b94e-52fc2ed9f55c
              with_validation:
                $ref: 0295787b-ee8a-4832-92b1-2f9935c4fa12
              structured_input:
                $ref: f6cf4cc2-e148-48b3-b1da-3552c45ed2bc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResolveResult'
              examples:
                basic:
                  summary: Basic normalization
                  value:
                    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
                with_validation:
                  summary: Normalization with validation
                  value:
                    object: address.resolution_result
                    created: 1764892815
                    input:
                      address: 1600 Amphitheatre Parkway, Mountain View, CA
                      options:
                        validate: true
                    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.98
                        address_type: commercial
                        deliverability: deliverable
                        timezone: America/Los_Angeles
                    validation:
                      valid: true
                      confidence: 0.98
                      issues: []
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    TerraKitVersion:
      name: terrakit-version
      in: header
      required: true
      description: API version in YYYY-MM-DD format.
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
    IdempotencyKey:
      name: idempotency-key
      in: header
      required: false
      description: Provide on POST requests to make them idempotent for safe retries.
      schema:
        type: string
  schemas:
    AddressResolveRequest:
      type: object
      description: Request to resolve an address into normalized, structured format.
      properties:
        address:
          type: string
          description: Free-form address text.
        structured:
          $ref: '#/components/schemas/AddressStructured'
        options:
          $ref: '#/components/schemas/AddressOptions'
      oneOf:
        - required:
            - address
        - required:
            - structured
      examples:
        free_form:
          summary: Free-form address
          value:
            address: 1600 Amphitheatre Parkway, Mountain View, CA
        with_validation:
          summary: Address with validation
          value:
            address: 1600 Amphitheatre Parkway, Mountain View, CA
            options:
              validate: true
        structured_input:
          summary: Structured address input
          value:
            structured:
              street_number: 221B
              thoroughfare:
                name: Baker Street
              localities:
                - name: London
                  type: city
              postal_code: NW1 6XE
              country_code: GB
            options:
              validate: true
    AddressResolveResult:
      type: object
      description: Result of address resolution. Fields present depend on options.
      properties:
        object:
          type: string
          const: address.resolution_result
        created:
          type: integer
          description: Epoch seconds.
        metadata:
          $ref: '#/components/schemas/Metadata'
        input:
          type: object
          properties:
            address:
              type: string
              nullable: true
            structured:
              anyOf:
                - $ref: '#/components/schemas/AddressStructured'
                - type: 'null'
            options:
              anyOf:
                - $ref: '#/components/schemas/AddressOptions'
                - type: 'null'
            tag:
              type: string
              nullable: true
        normalized:
          type: string
          nullable: true
          description: Canonical single-line address in requested format (e.g., postal).
        components:
          anyOf:
            - $ref: '#/components/schemas/AddressStructured'
            - type: 'null'
        validation:
          anyOf:
            - $ref: '#/components/schemas/ValidationSummary'
            - type: 'null'
        id:
          type: string
          description: Present only if the result is persisted.
          nullable: true
        result_url:
          type: string
          nullable: true
      required:
        - object
        - created
        - input
    AddressStructured:
      type: object
      description: >
        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.
      properties:
        recipient:
          type: string
          nullable: true
          description: Person name or primary recipient.
        organization:
          type: string
          nullable: true
          description: Company or institution name.
        attention:
          type: string
          nullable: true
          description: Attention line (e.g., c/o, Attn:).
        building_name:
          type: string
          nullable: true
          description: >-
            Named building, complex, or estate (e.g., Empire State Building,
            小区名称).
        sub_building:
          type: string
          nullable: true
          description: Block, tower, wing, or staircase identifier within a building.
        entrance:
          type: string
          nullable: true
          description: Specific entrance identifier or code.
        floor:
          type: string
          nullable: true
          description: Floor number or level (e.g., 5F, Ground Floor, 3階).
        door:
          type: string
          nullable: true
          description: Door number or identifier.
        unit:
          type: string
          nullable: true
          description: Apartment, suite, or room number.
        thoroughfare:
          type: object
          nullable: true
          description: Street or road information with directional and type components.
          properties:
            name:
              type: string
              nullable: true
              description: Street name without type or direction (e.g., Main, 中山路).
            type:
              type: string
              nullable: true
              description: Street type (e.g., St, Rd, Ave, Boulevard, 大道, Straße).
            pre_direction:
              type: string
              nullable: true
              description: Directional prefix (e.g., N, South, 东).
            post_direction:
              type: string
              nullable: true
              description: Directional suffix (e.g., NE, West, 西).
            sub_thoroughfare:
              type: string
              nullable: true
              description: Block, sector, quarter, or chome (丁目) designation.
        street_number:
          type: string
          nullable: true
          description: >-
            Primary street number or building number (e.g., 123, 1-2-3 for
            Japanese addresses).
        block_number:
          type: string
          nullable: true
          description: >-
            East Asian block number (e.g., Japanese chome/banchi 丁目/番地, Korean
            block 번지).
        lot_number:
          type: string
          nullable: true
          description: Lot or parcel number within a block.
        landmark:
          type: string
          nullable: true
          description: >-
            Reference landmark for landmark-based addressing (common in
            developing countries).
        delivery_instructions:
          type: string
          nullable: true
          description: Special delivery instructions or access codes.
        localities:
          type: array
          nullable: true
          description: >
            Ordered smallest-to-largest locality hierarchy (e.g., neighborhood →
            city → post_town). At least one locality is typically present for
            valid addresses.
          minItems: 1
          items:
            type: object
            required:
              - name
              - type
            properties:
              name:
                type: string
                description: Locality name in specified language.
              type:
                type: string
                enum:
                  - neighborhood
                  - dependent_locality
                  - village
                  - town
                  - city
                  - post_town
                  - municipality
                  - district
                  - subdistrict
                  - quarter
                  - unknown
                description: Type of locality.
              language:
                type: string
                nullable: true
                description: BCP-47 language code of the locality name.
        admin_areas:
          type: array
          nullable: true
          description: >
            Ordered smallest-to-largest administrative areas (e.g., county →
            state → region). Supports hierarchical structures with up to 5
            levels for countries with complex administrative divisions.
          minItems: 1
          items:
            type: object
            required:
              - name
              - type
            properties:
              name:
                type: string
                description: Administrative area name.
              code:
                type: string
                nullable: true
                description: >-
                  Official code (e.g., ISO 3166-2 subdivision code, postal
                  abbreviation).
              type:
                type: string
                enum:
                  - county
                  - department
                  - province
                  - state
                  - prefecture
                  - region
                  - oblast
                  - canton
                  - parish
                  - emirate
                  - district
                  - governorate
                  - unknown
                description: Type of administrative division.
              level:
                type: integer
                minimum: 1
                maximum: 5
                description: Hierarchical level (1=smallest, 5=largest).
        region:
          type: string
          nullable: true
          description: >-
            Top-level administrative area (convenience field, typically
            duplicates largest admin_area).
        region_code:
          type: string
          nullable: true
          description: >-
            Top-level administrative area code (e.g., CA for California, SP for
            São Paulo).
        postal_code:
          type: string
          nullable: true
          description: Postal or ZIP code. Format varies by country.
        postal_code_suffix:
          type: string
          nullable: true
          description: Extended postal code suffix (e.g., +4 in US ZIP+4).
        sorting_code:
          type: string
          nullable: true
          description: Additional sorting/routing codes (e.g., CEDEX in France, DPS codes).
        po_box:
          type: string
          nullable: true
          description: Post office box number.
        po_box_type:
          type: string
          nullable: true
          description: Type of postal box (e.g., PO Box, Private Bag, Locked Bag).
        rural_route:
          type: object
          nullable: true
          description: Rural route or highway contract delivery information.
          properties:
            type:
              type: string
              enum:
                - rural_route
                - highway_contract
                - general_delivery
                - unknown
              description: Type of rural delivery.
            number:
              type: string
              nullable: true
              description: Route or contract number.
            box:
              type: string
              nullable: true
              description: Box number on the rural route.
        country:
          type: string
          nullable: true
          description: Full country name.
        country_code:
          type: string
          nullable: true
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2 country code (uppercase).
        language:
          type: string
          nullable: true
          pattern: ^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?$
          description: >-
            Primary language of this address (BCP-47 format, e.g., en-US,
            zh-Hans-CN).
        local_script:
          type: object
          nullable: true
          description: >
            Native-script representation for display, printing, and labels.
            Essential for addresses in non-Latin scripts (Arabic, CJK, Cyrillic,
            etc.).
          properties:
            address_lines:
              type: array
              items:
                type: string
              description: Formatted address lines in local script.
            language:
              type: string
              nullable: true
              description: BCP-47 language code for the local script.
        address_lines:
          type: array
          nullable: true
          description: >
            Canonical formatted display lines in postal order for the target
            country. Generated by the resolver based on country-specific
            formatting rules.
          items:
            type: string
        canonical_form:
          type: string
          nullable: true
          description: >
            Fully normalized single-line postal form for equality testing and
            deduplication. Standardized format regardless of input variations.
        coordinates:
          allOf:
            - $ref: '#/components/schemas/Coordinates'
          nullable: true
        metadata:
          allOf:
            - $ref: '#/components/schemas/AddressMetadata'
          nullable: true
      required: []
    AddressOptions:
      type: object
      description: Optional processing instructions for address resolution.
      properties:
        validate:
          type: boolean
          default: false
          description: >-
            If true, perform deliverability/consistency checks and include
            validation results.
    Metadata:
      type: object
      description: Arbitrary key/value pairs attached to the request; echoed in results.
      additionalProperties:
        type: string
    ValidationSummary:
      type: object
      description: High-level quality assessment of the resolved address.
      properties:
        valid:
          type: boolean
        confidence:
          type: number
        issues:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              issue:
                type: string
              suggest:
                type: string
                nullable: true
      required:
        - valid
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error category (e.g.
              invalid_request_error): null
            message:
              type: string
            code:
              type: string
              nullable: true
            param:
              type: string
              nullable: true
            doc_url:
              type: string
              nullable: true
            request_log_url:
              type: string
              nullable: true
      required:
        - error
    Coordinates:
      type: object
      nullable: true
      properties:
        lat:
          type: number
        lng:
          type: number
      description: WGS84 latitude/longitude.
    AddressMetadata:
      type: object
      description: Metadata about the resolution process and data sources.
      properties:
        confidence:
          type: number
          nullable: true
          description: Normalizer confidence score (0–1).
        source:
          type: string
          nullable: true
          description: Original data source/provider reference.
        address_type:
          allOf:
            - $ref: '#/components/schemas/AddressType'
          nullable: true
        deliverability:
          type: string
          enum:
            - deliverable
            - undeliverable
            - unknown
          nullable: true
          description: Deliverability assessment of the address.
        timezone:
          type: string
          nullable: true
          description: IANA timezone identifier (e.g., America/Los_Angeles).
    AddressType:
      type: string
      enum:
        - residential
        - commercial
        - po_box
        - military
        - educational
        - government
        - unknown
      description: Classification of the address type.
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````