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

# Resolve and normalize a street address

> Resolve one street address through the Geocodio geocoding/normalization source (v2.1). Supply address={formatted or line1+city,country in US,CA,MX,GB,AU,NZ}; optional fields selects up to 3 documented appends (timezone,cd,stateleg,school,census,acs-housing,zip4; US-only appends rejected elsewhere), each one additional billed provider lookup. Success costs50 credits and stores one account-owned addr_geocodio_ observation24h; retained reads1, errors/replay0. Match accuracy and source_name are provider-reported; rooftop/point coordinates are geographic matches, not parcel, occupancy, deliverability or address-existence proof. No address autocomplete, unit inventory, USPS-certified delivery point, parcel or ownership verification. Source: Geocodio pay-as-you-go API. Documentation-backed beta; not fresh live-source verification.

Normalize one street address through the Geocodio pay-as-you-go geocoding source (v2.1). Supply `address={formatted:...}` for free-form text or `address={line1,city,region or postal_code,country}` for structured components; country is the ISO code and must be one of US, CA, MX, GB, AU or NZ. Success costs 50 credits and stores one account-owned normalized-address observation for24 hours.

The response carries the provider-formatted address, parsed components, address lines, coordinates (WGS84/EPSG:4326), numeric accuracy, literal accuracy\_type, provider source name and the stable\_address\_key retained as a reference. Coordinates are geographic matches, not parcel boundaries, deliverability confirmation or ownership evidence. Zero-result requests cost 0 and return status no\_match.

Optional fields selects up to 3 documented provider appends: timezone, cd (congressional district), stateleg (state legislative districts), school (districts), census (Census geographies), acs-housing (ACS housing) and zip4 (ZIP+4). Appends other than timezone are US-only. Each requested append is billed by the provider as one additional lookup, so appends are checked against the configured run allowance before execution. Provider credentials and enablement are checked before every call.

> [!NOTE]
>
> Check [live capabilities](https://realtycrawl.dev/v1/meta/capabilities?platform=geocodio) before calling this operation.

This binding is documentation-backed beta, not fresh live source verification. GEOCODIO\_API\_KEY must be configured and the source enabled explicitly.


## OpenAPI

````yaml POST /v1/addresses/resolve
openapi: 3.1.0
info:
  title: RealtyCrawl API
  version: 0.1.0
  description: >-
    Unified real estate API with source-specific operations, markets and access
    requirements. Check current capabilities before source requests.
    Documentation-backed beta contracts require explicit configuration and do
    not establish fresh live source acceptance.
servers: []
security:
  - ApiKeyAuth: []
paths:
  /v1/addresses/resolve:
    post:
      tags:
        - addresses
      summary: Resolve and normalize a street address
      description: >-
        Resolve one street address through the Geocodio geocoding/normalization
        source (v2.1). Supply address={formatted or line1+city,country in
        US,CA,MX,GB,AU,NZ}; optional fields selects up to 3 documented appends
        (timezone,cd,stateleg,school,census,acs-housing,zip4; US-only appends
        rejected elsewhere), each one additional billed provider lookup. Success
        costs50 credits and stores one account-owned addr_geocodio_
        observation24h; retained reads1, errors/replay0. Match accuracy and
        source_name are provider-reported; rooftop/point coordinates are
        geographic matches, not parcel, occupancy, deliverability or
        address-existence proof. No address autocomplete, unit inventory,
        USPS-certified delivery point, parcel or ownership verification. Source:
        Geocodio pay-as-you-go API. Documentation-backed beta; not fresh
        live-source verification.
      operationId: resolveAddress
      parameters:
        - name: fields
          in: query
          description: >-
            Response-only comma-separated field paths relative to data items; up
            to 32 paths. Source requests and billing are unchanged.
          schema:
            type: string
            maxLength: 4127
        - name: format
          in: query
          description: >-
            Response-only export format. JSON retains the envelope; CSV/NDJSON
            contain data records, with request/credit metadata in headers.
            Errors stay JSON.
          schema:
            type: string
            enum:
              - json
              - csv
              - ndjson
            default: json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressResolveRequest'
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resolveAddressResponse'
            text/csv:
              schema:
                type: string
                description: Data rows only; request, row count and credits are in headers.
            application/x-ndjson:
              schema:
                type: string
                description: One JSON data item per line; metadata is in headers.
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AddressResolveRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressSelector'
        fields:
          type: array
          description: >-
            Optional documented Geocodio field appends; each is one additional
            billed provider lookup. US-only appends are rejected for other
            countries.
          items:
            type: string
            enum:
              - timezone
              - cd
              - stateleg
              - school
              - census
              - acs-housing
              - zip4
          maxItems: 3
          uniqueItems: true
      required:
        - address
      additionalProperties: false
    resolveAddressResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Resolution'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - meta
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            details:
              type: array
              items:
                $ref: '#/components/schemas/SourceOutcome'
          required:
            - code
            - message
            - retryable
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    AddressSelector:
      oneOf:
        - type: object
          properties:
            formatted:
              type: string
              minLength: 3
            country:
              type: string
              pattern: ^[A-Z]{2}$
          required:
            - formatted
            - country
          additionalProperties: false
        - type: object
          properties:
            line1:
              type: string
              minLength: 1
            unit:
              anyOf:
                - type: string
                - type: 'null'
            city:
              type: string
              minLength: 1
            region:
              anyOf:
                - type: string
                - type: 'null'
            postal_code:
              anyOf:
                - type: string
                - type: 'null'
            country:
              type: string
              pattern: ^[A-Z]{2}$
            original_text:
              anyOf:
                - type: string
                - type: 'null'
          required:
            - line1
            - city
            - country
          additionalProperties: false
    Resolution:
      type: object
      properties:
        status:
          type: string
          enum:
            - matched
            - ambiguous
            - unmatched
        candidates:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              entity_type:
                type: string
                enum:
                  - listing
                  - property
                  - building
                  - address
              confidence:
                anyOf:
                  - type: number
                  - type: 'null'
              method:
                type: string
              source:
                $ref: '#/components/schemas/Source'
            required:
              - id
              - entity_type
              - method
              - source
            additionalProperties: false
      required:
        - status
        - candidates
      additionalProperties: false
    Meta:
      type: object
      properties:
        request_id:
          type: string
        schema_version:
          type: string
        generated_at:
          type: string
          format: date-time
        completeness:
          type: string
          enum:
            - complete
            - partial
            - unknown
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceOutcome'
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
            required:
              - code
              - message
            additionalProperties: false
        pagination:
          type: object
          properties:
            next_cursor:
              anyOf:
                - type: string
                - type: 'null'
            has_more:
              type: boolean
            returned:
              type: integer
            total:
              anyOf:
                - type: integer
                - type: 'null'
            total_relation:
              type: string
              enum:
                - exact
                - lower_bound
                - unknown
          required:
            - next_cursor
            - has_more
            - returned
            - total
            - total_relation
          additionalProperties: false
        property_groups:
          type: array
          items:
            $ref: '#/components/schemas/PropertyGroup'
      required:
        - request_id
        - schema_version
        - generated_at
        - completeness
        - sources
      additionalProperties: false
    SourceOutcome:
      type: object
      properties:
        platform:
          type: string
        provider:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - success
            - partial
            - failed
            - unsupported
        error_code:
          anyOf:
            - type: string
            - type: 'null'
        truncated:
          type: boolean
        observed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
      required:
        - platform
        - status
      additionalProperties: false
    Source:
      type: object
      properties:
        platform:
          type: string
        country:
          type: string
        native_id:
          anyOf:
            - type: string
            - type: 'null'
        url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
        provider:
          type: string
        observed_at:
          type: string
          format: date-time
        source_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        access_class:
          type: string
          enum:
            - public_portal
            - licensed_feed
            - public_record
            - modeled
        retrieved_at:
          type: string
          format: date-time
      required:
        - platform
        - provider
        - observed_at
        - access_class
      additionalProperties: false
    PropertyGroup:
      type: object
      properties:
        property_id:
          anyOf:
            - type: string
            - type: 'null'
        listing_ids:
          type: array
          items:
            type: string
        match_method:
          type: string
        confidence:
          anyOf:
            - type: number
            - type: 'null'
        status:
          type: string
          enum:
            - matched
            - ambiguous
      required:
        - property_id
        - listing_ids
        - match_method
        - status
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.