--- title: Standard Address Verification and Autocomplete | PostGrid description: API reference for PostGrid's US and Canada address verification and autocomplete — covers response schemas, error fields, address details, and geocoding. --- 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: 1. Use the `GET /completions` endpoint and supply `partialStreet` via the query params - This endpoint does not use any lookups 2. Allow the user to select one of the autocompleted address previews 3. 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** [**support@postgrid.com**](mailto: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.** 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](#accuracy-score) | | accuracyType | string | A string representing the [accuracy type](#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](https://en.wikipedia.org/wiki/Address_geocoding#Address_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](#errors) | The address errors that were fixed or caused verification failure | | status | string | Either ‘verified’, ‘corrected’ or ‘failed’ | | details | [Address Details](#address-details) or null | Detailed information about the address | | geocodeResult | [Geocode Result](#geocoding) | 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](#autocompleted-address) | The address | | geocodeResult | [Geocode Result](#geocoding) | The geocoding result | | errors | [Errors](#errors) | Issues with the address (e.g. user also needs to supply unit number) |