--- title: International Address Verification and Autocomplete | PostGrid description: Reference for PostGrid's international address verification API — covers autocomplete flow, response schema, verification status, match levels, and geodata. --- Allows you to autocomplete, verify, and standardize international addresses of 245+ countries in real-time. ## 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 international address previews 3. If the selected type is ‘Address’. Make a `POST /completions` request with request body ‘id’ which its value comes from the ‘id’ field of the selected preview. 4. If the selected type is not ‘Address’. Use the `GET /completions` endpoint again but this time supplies ‘container’ which its value comes from the ‘id’ of the selected preview as query param. In addition, supply query param advanced=true. Then proceed to step 2 again. ## 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. | ## 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 | | ------------ | -------------- | ---------------------------------------------------------------- | | organization | string or null | Name of the company or organization where the address is located | | building | string or null | Name of the building where the address is located | | subBuilding | string or null | Name of the sub building where the address is located | | premise | string or null | Premise number where the address is located | | postBox | string or null | Postal box number where the address is located | | telephone | string or null | Telephone number registered where the address is located | **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`. ## Geographical Data You can request additional geographical details when using the verification endpoints (both batch and single address) by supplying a query parameter `geoData=true`. | Name | Type | Description | | ----------- | ------ | --------------------------------------------------------------------- | | latitude | number | The latitude of the resulting address | | longitude | number | The longitude of the resulting address | | geoAccuracy | number | The accuracy of the geographical information of the resulting address | ## Summary of Verification | Name | Type | Description | | ----------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | verificationStatus | string or null | The status of the verification. See [Verification Status](#verification-status) | | postProcessedVerificationMatchLevel | string or null | The level to which the input data matches the available reference data once all changes and additions performed during the verification process have been taken into account.See [Verification Match Level](#) | | preProcessedVerificationMatchLevel | string or null | The level to which the input data matches the available reference data prior to any changes or additions performed during the verification process.See [Verification Match Level](#) | | parsingStatus | string or null | Either ‘identified\_and\_parsed’ or ‘unable\_to\_parse’ | | lexiconIdentificationMatchLevel | string or null | The level to which the output data has some recognized form, through the use of pattern matching and lexicon matching.See [Verification Match Level](#) | | contextIdentificationMatchLevel | string or null | The level to which the output data can be recognized based on the context in which it appears.See [Verification Match Level](#) | | postCodeStatus | string or null | The status about postal code.See [PostalCode Status](#) | | matchScore | string or null | Indicates how much the input data has been changed during the verification process in order to achieve the post-processed verification match level | ### Verification Status - V: Verified\ A complete match was made between the input data and a single record from the available reference data - P: Partially Verified\ A partial match was made between the input data and a single record from the available reference data - U: Unverified\ Unable to verify. The output fields will contain the input data| - A: Ambiguous\ More than one close reference data match - C: Conflict\ More than one close reference data match with conflicting values - R: Reverted\ Record could not be verified to the specified minimum acceptable level. The output fields will contain the input data ### Verification Match Level - 5: Delivery Point (PostBox or SubBuilding) - 4: Premise (Premise or Building) - 3: Thoroughfare (Street or Road) - 2: Locality (City) - 1: AdministrativeArea (Province or State) - 0: None ### Postcode Status - postal\_code\_primary\_and\_postal\_code\_secondary\_verified - postal\_code\_primary\_verified, postal\_code\_secondary\_added\_or\_changed - postal\_code\_primary\_verified - postal\_code\_primary\_verified\_with\_small\_change - postal\_code\_primary\_verified\_with\_large\_change - postal\_code\_primary\_added - postal\_code\_primary\_identified\_by\_lexicon - postal\_code\_primary\_identified\_by\_context - postal\_code\_primary\_empty ## Verification This is the data returned from the international verification endpoints. The batch verification endpoint returns an array of these. The final status of each result is stored inside the `verificationStatus` property of the `summary` field. See [Verification Status](#verification-status). In addition, the `summary` field provides other information regarding the quality of each verification. See [Summary of Verification](#verification-summary) | Name | Type | Description | | ---------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- | | formattedAddress | string | The complete address including all details | | line1 | string | The first line of the resulting address | | line2 | string or null | The second line of the resulting address | | line3 | string or null | The third line of the resulting address | | line4 | string or null | The fourth 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 | | country | string or null | The country of the resulting address | | summary | [Summary of Verification](#verification-summary) or null | Contains accuracy information of the verification (see below for details) | | geoData | [Geographical Data](#geographical-data) or null | Contains geographic information (see below for details) | | details | [Address Details](#address-details) or null | Detailed information about the address (see below for details) | | errors | string or null | The address errors that were fixed or caused verification failure | ## 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 | | ----------- | ------ | -------------------------------------------------------------------------------------- | | id | string | The ID of the autocompleted address | | type | string | Either ‘Address’ or ‘BuildingNumber’ | | text | string | The name of the autocompleted address | | highlight | string | A list of number ranges identifying the matched characters in the Text and Description | | description | string | Descriptive information about the result | ## Autocompleted Address This is the data returned from the `POST` completions endpoint. | Name | Type | Description | | ---------------- | -------------- | ----------------------------------------------------------------- | | formattedAddress | string | The complete address including all details | | line1 | string | The first line of the resulting address | | line2 | string or null | The second line of the resulting address | | line3 | string or null | The third line of the resulting address | | line4 | string or null | The fourth 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 | | country | string or null | The country of the resulting address | | building | string or null | Name of the building where the address is located | | department | string or null | Name of the department where the address is located | | company | string or null | Name of the company where the address is located | | errors | string or null | The address errors that were fixed or caused verification failure |