Autocomplete

POST/v1/addver/completions

Resolves a partial street address into a list of full address candidates, optionally selecting a specific candidate by index and verifying it.

Basic usage — omit index: returns an array of CompletedAddressItem results for the given partialStreet.

With index — specify index to resolve a single candidate. Returns a single CompletedAddressItem.

With index + verify=true — additionally runs the selected address through the USPS/Canada Post verifier and returns a StandardVerifiedAddress.

Uses 1 lookup per call (plus 1 more if geocoding a result).

Query ParametersExpand Collapse

filterExact: optional boolean

geocode: optional boolean

includeDetails: optional boolean

index: optional number

limit: optional number

properCase: optional boolean

verifiedOnly: optional boolean

verify: optional boolean

Body ParametersJSONExpand Collapse

partialStreet: string

The partial street address to complete (e.g. "22 Bay").

cityFilter: optional string

Filter results to a specific city.

countryFilter: optional string

Filter results to a specific country code.

pcFilter: optional string

Filter results to a specific postal code prefix.

stateFilter: optional string

Filter results to a specific state or province abbreviation.

verifiedOnly: optional boolean

If true, only return addresses that passed USPS/Canada Post verification.

ReturnsExpand Collapse

data: object { address, errors, geocodeResult } or array of object { address, errors, geocodeResult } or object { city, country, line1, 11 more }

One of the following:

CompletedAddressItem object { address, errors, geocodeResult }

address: object { address, address2, city, 3 more }

The resolved address components.

address: string

The first line of the address.

address2: optional string

The second line of the address.

city: optional string

The city.

country: optional string

The ISO 2-letter country code.

pc: optional string

The postal code.

prov: optional string

The province or state abbreviation.

errors: optional Errors { city, generic, line1, 3 more }

Errors encountered during address verification.

city: optional array of string

Errors related to the city.

generic: optional array of string

Generic errors not tied to a specific field.

line1: optional array of string

Errors related to the first address line.

line2: optional array of string

Errors related to the second address line.

postalOrZip: optional array of string

Errors related to the postal or ZIP code.

provinceOrState: optional array of string

Errors related to the province or state.

geocodeResult: optional object { accuracy, accuracyType, location }

Geocoding result. Only present when geocode=true is supplied and an index is specified.

accuracy: number

A real number from 0.00 to 1.00 which represents an accuracy score

accuracyType: "rooftop" or "point" or "range_interpolation" or 5 more

A string representing the accuracy type

One of the following:

"rooftop"

"point"

"range_interpolation"

"nearest_rooftop_match"

"intersection"

"street_center"

"place"

"state"

location: object { lat, lng }

Object that contains lat, lng properties with number values

lat: number

lng: number

array of object { address, errors, geocodeResult }

address: object { address, address2, city, 3 more }

The resolved address components.

address: string

The first line of the address.

address2: optional string

The second line of the address.

city: optional string

The city.

country: optional string

The ISO 2-letter country code.

pc: optional string

The postal code.

prov: optional string

The province or state abbreviation.

errors: optional Errors { city, generic, line1, 3 more }

Errors encountered during address verification.

city: optional array of string

Errors related to the city.

generic: optional array of string

Generic errors not tied to a specific field.

line1: optional array of string

Errors related to the first address line.

line2: optional array of string

Errors related to the second address line.

postalOrZip: optional array of string

Errors related to the postal or ZIP code.

provinceOrState: optional array of string

Errors related to the province or state.

geocodeResult: optional object { accuracy, accuracyType, location }

Geocoding result. Only present when geocode=true is supplied and an index is specified.

accuracy: number

A real number from 0.00 to 1.00 which represents an accuracy score

accuracyType: "rooftop" or "point" or "range_interpolation" or 5 more

A string representing the accuracy type

One of the following:

"rooftop"

"point"

"range_interpolation"

"nearest_rooftop_match"

"intersection"

"street_center"

"place"

"state"

location: object { lat, lng }

Object that contains lat, lng properties with number values

lat: number

lng: number

StandardVerifiedAddress object { city, country, line1, 11 more }

city: string

The city name of the address.

country: string

The country code of the address.

line1: string

The first line of the address.

postalOrZip: string

The postal code or ZIP code of the address.

provinceOrState: string

The province or state of the address.

countryName: optional string

The country name of the address.

details: optional object { boxID, county, countyNum, 45 more }

If you supply includeDetails=true as a query parameter, we will also populate an additional details field that follows the Address Details schema.

boxID: optional string

PO Box ID

county: optional string

County in the United States (US address only)

countyNum: optional string

FIPS code for county (US address only)

deliveryInstallationAreaName: optional string

Delivery installation area name

deliveryInstallationQualifier: optional string

Delivery installation qualifier

deliveryInstallationType: optional string

Delivery installation type

extraInfo: optional string

Any extra information relevant to the address

postDirection: optional string

The post-direction of the street (after the street name, US addresses only)

preDirection: optional string

The pre-direction of the street (before the street name, US addresses only)

residential: optional boolean

Indicates that the address is residential (US address only)

ruralRouteNumber: optional string

Rural route number

ruralRouteType: optional string

Rural route type

streetDirection: optional string

The direction of the street (N, S, E, W, etc)

streetName: optional string

Name of the street where the address is located

streetNumber: optional string

Street number (e.g. the 20 in 20 Bay St)

streetType: optional string

Type of the street (DR, ST, BLVD, etc)

suiteID: optional string

The unit number/name

suiteKey: optional string

The suite key

usCensusBlockNumber: optional string

US Census block number

usCensusCMSA: optional string

US Census consolidated metropolitan statistical area

usCensusFIPS: optional string

US Census FIPS code (US address only)

usCensusMA: optional string

US Census metropolitan area

usCensusMSA: optional string

US Census metropolitan statistical area

usCensusPMSA: optional string

US Census primary metropolitan statistical area

usCensusTractNumber: optional string

US Census tract number

usCongressionalDistrictNumber: optional string

US congressional district number

usHasDaylightSavings: optional boolean

True if address location recognizes DST

usMailingCheckDigit: optional string

PostNet barcode digit

usMailingsCarrierRoute: optional string

4-character code assigned to mail delivery route within a 5 digit zip code

usMailingsDefaultFlag: optional boolean

True if US address matches a high-rise default or rural route default in the USPS data

usMailingsDeliveryPoint: optional string

Unique USPS identifier for the delivery point

usMailingsDpvConfirmationIndicator: optional string

See USPS DPV

usMailingsDpvCrmaIndicator: optional string

Y if this is a commercial mail receiving agency, N otherwise

usMailingsDpvFootnote1: optional string

See USPS DPV

usMailingsDpvFootnote2: optional string

See USPS DPV

usMailingsDpvFootnote3: optional string

See USPS DPV

usMailingsElotAscDesc: optional string

A for ascending, D for descending

usMailingsElotSequenceNumber: optional string

eLOT sequence number

usMailingsEWSFlag: optional string

Y if address is in early warning system database

usMailingsLACSFlag: optional string

Y if address converted by LACS

usMailingsLACSReturnCode: optional string

Corresponds to USPS LACSLink return code

usMailingsRecordTypeCode: optional string

See USPS DPV

usMailingsSuiteLinkReturnCode: optional string

See USPS DPV

usPostnetBarcode: optional string

PostNet barcode for the address (US address only)

usStateLegislativeLower: optional string

Lower legislative district for the US address

usStateLegislativeUpper: optional string

Upper legislative district for the US address

usTimeZone: optional string

Time zone for the US address area

vacant: optional boolean

Indicates that the address is vacant according to the USPS (US address only)

errors: optional Errors { city, generic, line1, 3 more }

Errors encountered during address verification.

city: optional array of string

Errors related to the city.

generic: optional array of string

Generic errors not tied to a specific field.

line1: optional array of string

Errors related to the first address line.

line2: optional array of string

Errors related to the second address line.

postalOrZip: optional array of string

Errors related to the postal or ZIP code.

provinceOrState: optional array of string

Errors related to the province or state.

firmName: optional string

The firm name of the address.

geocodeResult: optional object { accuracy, accuracyType, location }

If the geocode=true query parameter is supplied, the response will include a geocodeResult which follows the Geocoding schema. You can request this feature be enabled by emailing support@postgrid.com. This includes our verification, batch verification, suggestions, and POST /completions endpoint. Note that you must supply country when geocoding to get the result successfully.

accuracy: number

A real number from 0.00 to 1.00 which represents an accuracy score

accuracyType: "rooftop" or "point" or "range_interpolation" or 5 more

A string representing the accuracy type

One of the following:

"rooftop"

"point"

"range_interpolation"

"nearest_rooftop_match"

"intersection"

"street_center"

"place"

"state"

location: object { lat, lng }

Object that contains lat, lng properties with number values

lat: number

lng: number

line2: optional string

The second line of the address.

provinceOrStateName: optional string

The full name of the province or state.

status: optional Status

The verification status of an address.

One of the following:

"verified"

"corrected"

"failed"

zipPlus4: optional string

The zip plus 4 code of the address.

message: string

status: "success" or "error"

One of the following:

"success"

"error"

Autocomplete

curl https://api.postgrid.com/v1/addver/completions \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -d '{
          "partialStreet": "partialStreet"
        }'

{
  "data": {
    "address": {
      "address": "address",
      "address2": "address2",
      "city": "city",
      "country": "country",
      "pc": "pc",
      "prov": "prov"
    },
    "errors": {
      "city": [
        "string"
      ],
      "generic": [
        "string"
      ],
      "line1": [
        "string"
      ],
      "line2": [
        "string"
      ],
      "postalOrZip": [
        "string"
      ],
      "provinceOrState": [
        "string"
      ]
    },
    "geocodeResult": {
      "accuracy": 0,
      "accuracyType": "rooftop",
      "location": {
        "lat": 0,
        "lng": 0
      }
    }
  },
  "message": "message",
  "status": "success"
}

Returns Examples

{
  "data": {
    "address": {
      "address": "address",
      "address2": "address2",
      "city": "city",
      "country": "country",
      "pc": "pc",
      "prov": "prov"
    },
    "errors": {
      "city": [
        "string"
      ],
      "generic": [
        "string"
      ],
      "line1": [
        "string"
      ],
      "line2": [
        "string"
      ],
      "postalOrZip": [
        "string"
      ],
      "provinceOrState": [
        "string"
      ]
    },
    "geocodeResult": {
      "accuracy": 0,
      "accuracyType": "rooftop",
      "location": {
        "lat": 0,
        "lng": 0
      }
    }
  },
  "message": "message",
  "status": "success"
}