Allows you to autocomplete, verify, and standardize US & Canada addresses in real-time. It also offers batch verification which allows you to do the same for thousands of addresses per second.

Integrating Autocomplete

We provide a pre-built web-based autocomplete integration in the Developers section of the dashboard. However, if you want to integrate autocomplete manually, here are our recommended steps:

Use the GET /completions endpoint and supply partialStreet via the query params
- This endpoint does not use any lookups
Allow the user to select one of the autocompleted address previews
Make a POST /completions?index=N request where N is the index of the address the user selected

If you follow these steps, there will only be 1 lookup made in total (when the user selects the address).

Response

The top-level JSON response has the following structure:

Name	Type	Description
status	string	Either `success` or `error`
message	string	Describes the result of the request
data	object or array	The response data.

Errors

This object is returned from the verification and autocomplete endpoint to describe issues or incomplete aspects of the given address that were either fixed (which the verification endpoint will always attempt to do) or caused verification failure.

Name	Type	Description
line1	array of string	Issues related to the first line of the address
line2	array of string	Issues related to the second line of the address
city	array of string	Issues related to the city
provinceOrState	array of string	Issues related to the province or state
generic	array of string	Issues with the address in general

Address Details

You can request additional address details when using the verification endpoints (both batch and single address) by supplying a query parameter includeDetails=true.

The details have the following schema:

Name	Type	Description
streetName	string or null	Name of the street where the address is located
streetType	string or null	Type of the street (DR, ST, BLVD, etc)
streetDirection	string or null	The direction of the street (N, S, E, W, etc)
streetNumber	string or null	Street number (e.g. the 20 in 20 Bay St)
suiteID	string or null	The unit number/name
boxID	string or null	PO Box ID
deliveryInstallationAreaName	string or null	Delivery installation area name
deliveryInstallationType	string or null	Delivery installation type
deliveryInstallationQualifier	string or null	Delivery installation qualifier
ruralRouteNumber	string or null	Rural route number
ruralRouteType	string or null	Rural route type
extraInfo	string or null	Any extra information relevant to the address
county	string or null	County in the United States (US address only)
countyNum	string or null	County number in the United States (US address only)
residential	boolean or null	Indicates that the address is residential (US address only)
vacant	boolean or null	Indicates that the address is vacant according to the USPS (US address only)

Note that the details will be returned in a 'details' subobject and only the relevant fields for a given address will be returned. The fields that are empty will not.

Proper Case

You can have the verification and suggestion endpoints return addresses in Proper Case (e.g. 22-20 Bay St) by supplying a query parameter properCase=true.

Geocoding

All of our POST endpoints also provide geolocation information when geocode=true is provided as a query parameter. You can request this feature be enabled by emailing [email protected]. This includes our verification, batch verification, suggestions, and POST /completions endpoint. Note that you must supply country when geocoding to get the result successfully.

If the query parameter is supplied, the response will include a geocodeResult which has the following schema:

Name	Type	Description
location	Object	Object that contains `lat`, `lng` properties with number values
accuracy	number	A real number from 0.00 to 1.00 which represents an accuracy score
accuracyType	string	A string representing the accuracy type

Accuracy Score

This real number value from 0.00 to 1.00 which represents our confidence in the geocodes. Generally speaking, scores larger than 0.8 are quite accurate. Anything below could be a rough match.

Accuracy Type

One of the following values:

rooftop indicating that the exact point was found
point indicating that the exact point was found within a range of addresses
range_interpolation indicating that we used interpolation to generate the result (still fairly accurate)
nearest_rooftop_match indicating we found a nearby rooftop point and used that
intersection indicating we found a street intersection at the point
street_center indicating we used the center of the closest street
place indicating that the point was a city/town/place
state indicating that the point was just a state

Verification

This is the data returned from the verification endpoints. The batch verification endpoint returns an array of these. Note that a verified status means that an address is deliverable as-is, corrected indicates we fixed it (errors will explain what we fixed), and failed means we were not able to fix it (errors might explain why).

Name	Type	Description
line1	string	The first line of the resulting address
line2	string or null	The second line of the resulting address
city	string or null	The city of the resulting address
provinceOrState	string or null	The province or state of the resulting address
postalOrZip	string or null	The Postal/ZIP code of the resulting address
zipPlus4	string or null	4-digit USPS ZIP+4 code
firmName	string or null	USPS Firm Name
country	string or null	One of 'ca' or 'us'
errors	Errors	The address errors that were fixed or caused verification failure
status	string	Either 'verified', 'corrected' or 'failed'
details	Address Details or null	Detailed information about the address
geocodeResult	Geocode Result	The geocoding result, if `geocode=true` query was supplied

Completion Preview

This is the data returned from the GET completion endpoint (i.e. the preview endpoint). Each element of the returned array follows this schema.

Name	Type	Description
address	string	The first line of the autocompleted address
city	string	The city of the autocompleted address
pc	string	The first 3 digits of the postal/ZIP code of the autocompleted address

Autocompleted Address

This is the data stored in the address field of the full completion response (see below).

Name	Type	Description
address	string	First line of the autocompleted address
city	string	City of the autocompleted address
prov	string	Province or state of the autocompleted address
pc	string	Postal/ZIP code of the autocompleted address
country	string	One of 'CA' or 'US'

Completion

This is the data returned from the POST completions endpoint. Each element of the returned array follows this schema. If you supply an index query parameter to the completions endpoint, it returns an object instead of an array in data.

Name	Type	Description
address	Autocompleted Address	The address
geocodeResult	Geocode Result	The geocoding result
errors	Errors	Issues with the address (e.g. user also needs to supply unit number)