Global Address API — API Reference

01 /

Endpoints

Two read-only routes. Both accept the same query parameters and respond with JSON. Any method other than GET returns 405 with an Allow: GET header.

GET/api/search

Search ranked address suggestions

Query Parameters

Param	Req	Notes
country	Yes	Country to search. One of `US`, `JP`, or `SG` (case-insensitive). This is the only required parameter; omitting it returns a `400`.
line1	No	First address line. Meaning varies by country: street address (US/JP) or block (SG). For Singapore you may use the `block` alias instead.
line2	No	Second address line. Apartment/suite/unit (US), supplementary line (JP), or street (SG). Always optional.
city	No	City name. Required for US and JP validation; not part of the SG schema.
region	No	State (US) or prefecture (JP). Not used for SG. For Japan you may use the `ken` alias instead.
postalCode	No	ZIP / postal code. Required for validation in all supported countries.
ken	No	Japan-only alias for `region` (prefecture). Resolved to `region` before validation and search. Ignored for US and SG.
block	No	Singapore-only alias for `line1` (block). Resolved to `line1` before validation and search. Ignored for US and JP.

Whitespace is trimmed from every value. Repeated params (?city=A&city=B) are rejected with 400.

US search by city (?country=US&city=Seattle)200 OK

application/json

{
  "suggestions": [
    {
      "recipient": "",
      "line1": "123 Main St",
      "city": "Seattle",
      "region": "WA",
      "postalCode": "98101",
      "country": "US",
      "score": 1
    }
  ]
}

SG search using the `block` alias (?country=SG&block=Blk%20123)200 OK

application/json

{
  "suggestions": [
    {
      "recipient": "",
      "line1": "Blk 123",
      "line2": "Ang Mo Kio Ave 6",
      "city": "Singapore",
      "postalCode": "560123",
      "country": "SG",
      "score": 1
    }
  ]
}

No matches200 OK

application/json

{
  "suggestions": []
}

GET/api/validate

Validate an address and resolve its canonical record

Query Parameters

Param	Req	Notes
country	Yes	Country to search. One of `US`, `JP`, or `SG` (case-insensitive). This is the only required parameter; omitting it returns a `400`.
line1	No	First address line. Meaning varies by country: street address (US/JP) or block (SG). For Singapore you may use the `block` alias instead.
line2	No	Second address line. Apartment/suite/unit (US), supplementary line (JP), or street (SG). Always optional.
city	No	City name. Required for US and JP validation; not part of the SG schema.
region	No	State (US) or prefecture (JP). Not used for SG. For Japan you may use the `ken` alias instead.
postalCode	No	ZIP / postal code. Required for validation in all supported countries.
ken	No	Japan-only alias for `region` (prefecture). Resolved to `region` before validation and search. Ignored for US and SG.
block	No	Singapore-only alias for `line1` (block). Resolved to `line1` before validation and search. Ignored for US and JP.

Whitespace is trimmed from every value. Repeated params (?city=A&city=B) are rejected with 400.

JP recognized using the `ken` alias (?country=JP&line1=1-1&city=Tokyo&ken=Tokyo&postalCode=100-0001)200 OK

application/json

{
  "recognized": true,
  "canonical": {
    "recipient": "",
    "line1": "1-1",
    "line2": "Chiyoda",
    "city": "Tokyo",
    "region": "Tokyo",
    "postalCode": "100-0001",
    "country": "JP"
  }
}

US recognized (?country=US&line1=123%20Main%20St&city=Seattle&region=WA&postalCode=98101)200 OK

application/json

{
  "recognized": true,
  "canonical": {
    "recipient": "",
    "line1": "123 Main St",
    "city": "Seattle",
    "region": "WA",
    "postalCode": "98101",
    "country": "US"
  }
}

Not recognized — partial input (?country=US&city=Seattle)200 OK

application/json

{
  "recognized": false
}

02 /

Field schema by territory

Each country defines its own field set and required fields. Pick a territory to see how its address shape differs. Required fields are flagged in postal red.

United States — 4 required, 1 optional

line1Street Addressrequired

line2Address Line 2optional

cityCityrequired

regionStaterequired

postalCodeZIP Coderequired

03 /

Errors

Errors arrive as JSON with a numeric status, a human message, and — where relevant — the offending field.

400

Bad Request

The request was malformed — missing/unsupported `country`, or a repeated query parameter. When the error is attributable to a specific field, `field` names it.

405

Method Not Allowed

The HTTP method is not allowed; only `GET` is supported. The `Allow` header advertises the permitted method.

400 payload400

application/json

{
  "status": 400,
  "message": "Duplicate values are not allowed for field 'city'",
  "field": "city"
}

405 payload405

application/json · Allow: GET

{
  "status": 405,
  "message": "Method Not Allowed"
}

Plot any address, three territories deep.

Endpoints

Field schema by territory

Errors

Bad Request

Method Not Allowed