Addresses

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.

POST

addresses

resolve

curl --request POST \
  --url https://api.example.com/v1/addresses/resolve \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "address": {
    "formatted": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://api.example.com/v1/addresses/resolve"

payload = { "address": {
        "formatted": "<string>",
        "country": "<string>"
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: {formatted: '<string>', country: '<string>'}})
};

fetch('https://api.example.com/v1/addresses/resolve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "status": "matched",
    "candidates": [
      {
        "id": "<string>",
        "entity_type": "listing",
        "method": "<string>",
        "source": {
          "platform": "<string>",
          "provider": "<string>",
          "observed_at": "2023-11-07T05:31:56Z",
          "access_class": "public_portal",
          "country": "<string>",
          "native_id": "<string>",
          "url": "<string>",
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z"
        },
        "confidence": 123
      }
    ]
  },
  "meta": {
    "request_id": "<string>",
    "schema_version": "<string>",
    "generated_at": "2023-11-07T05:31:56Z",
    "completeness": "complete",
    "sources": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ],
    "pagination": {
      "next_cursor": "<string>",
      "has_more": true,
      "returned": 123,
      "total": 123,
      "total_relation": "exact"
    },
    "property_groups": [
      {
        "property_id": "<string>",
        "listing_ids": [
          "<string>"
        ],
        "match_method": "<string>",
        "status": "matched",
        "confidence": 123
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "details": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "request_id": "<string>"
}

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.

Check live capabilities 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.

Authorizations

x-api-key

string

header

required

Query Parameters

fields

string

Response-only comma-separated field paths relative to data items; up to 32 paths. Source requests and billing are unchanged.

Maximum string length: 4127

format

enum<string>

default:json

Response-only export format. JSON retains the envelope; CSV/NDJSON contain data records, with request/credit metadata in headers. Errors stay JSON.

Available options:

json,

csv,

ndjson

Body

application/json

address

object

required

Option 1
Option 2

Show child attributes

fields

enum<string>[]

Optional documented Geocodio field appends; each is one additional billed provider lookup. US-only appends are rejected for other countries.

Maximum array length: 3

Available options:

timezone,

cd,

stateleg,

school,

census,

acs-housing,

zip4

Response

Successful response; meta discloses source completeness

data

object

required

Show child attributes

meta

object

required

Show child attributes

Resolve and normalize a street address

curl --request POST \
  --url https://api.example.com/v1/addresses/resolve \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "address": {
    "formatted": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://api.example.com/v1/addresses/resolve"

payload = { "address": {
        "formatted": "<string>",
        "country": "<string>"
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: {formatted: '<string>', country: '<string>'}})
};

fetch('https://api.example.com/v1/addresses/resolve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "status": "matched",
    "candidates": [
      {
        "id": "<string>",
        "entity_type": "listing",
        "method": "<string>",
        "source": {
          "platform": "<string>",
          "provider": "<string>",
          "observed_at": "2023-11-07T05:31:56Z",
          "access_class": "public_portal",
          "country": "<string>",
          "native_id": "<string>",
          "url": "<string>",
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z"
        },
        "confidence": 123
      }
    ]
  },
  "meta": {
    "request_id": "<string>",
    "schema_version": "<string>",
    "generated_at": "2023-11-07T05:31:56Z",
    "completeness": "complete",
    "sources": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ],
    "pagination": {
      "next_cursor": "<string>",
      "has_more": true,
      "returned": 123,
      "total": 123,
      "total_relation": "exact"
    },
    "property_groups": [
      {
        "property_id": "<string>",
        "listing_ids": [
          "<string>"
        ],
        "match_method": "<string>",
        "status": "matched",
        "confidence": 123
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "details": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "request_id": "<string>"
}

Overview

Meta

Listings

Platform listings

Properties

Buildings

Developments

Agents

Agencies

Auctions

Markets

Stays

Locations

Jobs

Observations

Addresses

Permits

Resolve and normalize a street address

Authorizations

Query Parameters

Body

Response