Get Autocomplete Previews

GET/v1/intl_addver/completions

Returns address completion previews for a partial address string, suitable for populating an autocomplete dropdown.

Regular mode — supply partialStreet to search by partial street address. Results may include Address types (resolvable directly) and Container types (buildings/complexes that require a follow-up call).

Advanced mode — supply advanced=true and a container ID (from a previous regular call) to drill into a building or complex and retrieve individual unit addresses.

Results with type: "Address" can be fully resolved by passing their id to POST /completions.

Does not consume a lookup.

Query ParametersExpand Collapse

advanced: optional boolean

cityFilter: optional string

container: optional string

countriesFilter: optional string

disableIPBiasing: optional boolean

language: optional string

limit: optional number

partialStreet: optional string

postalOrZipFilter: optional string

standardFallback: optional boolean

streetFilter: optional string

useEnhancedChinaDataset: optional boolean

ReturnsExpand Collapse

data: array of object { id, description, error, 3 more }

id: optional string

The unique identifier for this result. Pass this to POST /completions to retrieve the full address. If the type is Container, pass it as the container parameter to GET /completions to drill down further.

description: optional string

A secondary description of the result (e.g. city and country).

error: optional string

An error message if the lookup failed for this result.

highlight: optional string

Character ranges within text that match the search input, for bolding in UI.

text: optional string

The human-readable address suggestion text.

type: optional string

The type of result. Address means this can be resolved directly via POST /completions. Container means the result represents a building or complex — perform another GET /completions with this id as container to get individual unit addresses.

message: string

status: "success" or "error"

One of the following:

"success"

"error"

Get Autocomplete Previews

curl https://api.postgrid.com/v1/intl_addver/completions \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY"

{
  "status": "success",
  "message": "Address previews retrieved successfully",
  "data": [
    {
      "id": "GB|RM|A|54186236",
      "type": "Address",
      "text": "Flat 1, One Canada Square",
      "description": "London, E14 5AB"
    }
  ]
}

{
  "status": "success",
  "message": "Address previews retrieved successfully",
  "data": [
    {
      "id": "GB|RM|A|54186236",
      "type": "Address",
      "text": "10 Downing Street",
      "description": "London, SW1A 2AA"
    }
  ]
}

Returns Examples

{
  "status": "success",
  "message": "Address previews retrieved successfully",
  "data": [
    {
      "id": "GB|RM|A|54186236",
      "type": "Address",
      "text": "Flat 1, One Canada Square",
      "description": "London, E14 5AB"
    }
  ]
}

{
  "status": "success",
  "message": "Address previews retrieved successfully",
  "data": [
    {
      "id": "GB|RM|A|54186236",
      "type": "Address",
      "text": "10 Downing Street",
      "description": "London, SW1A 2AA"
    }
  ]
}