Use Address Verification REST API

Topics

Search Addresses
Verify Addresses

Search Addresses

Address Verification contains functionality for type-ahead address search and address completion. We provide this functionality in three endpoints, available in version 2 (v2) and version 3 (v3). New users should use v3.

You can use the Search API in either Indirect Mode or Direct Mode.

Indirect Mode

REST endpoints:

/api/v3/address/find

/api/v3/address/retrieve

With indirect mode, the client doesn't call the third-party provider directly – the client only interacts with Oracle Address Verification Service. Oracle then forwards the find call to the third-party provider.

First, find is called to narrow down the search, and then retrieve is called to obtain the complete address record. Because the performance for find is slower in this mode, we recommend using Direct Mode whenever possible.

Direct Mode

REST endpoints:

/api/v3/address/preparefind

/api/v3/address/retrieve

Here the client first calls preparefind at application page initialization time. As a response to preparefind, the client receives information and credentials to perform find calls directly on the third-party application. Retrieve is then again performed against the verification endpoint, not the third-party application (see use cases in subsequent sections).

Simple Search Use Case

Suppose the first find request is issued as soon as you type the first three letters of an intended US address as “123”. This is the result request and response:

Note: Examples show Indirect Mode. Functionality is identical for Direct Mode, but with an initial preparefind.

Request

http://adc00qrw.oracle.com:7767/av/api/v3/address/find?Text=123

Response

[
  {
    "Id": "US|US|ENG|94107-CA-SAN_FRANCISCO--ST-TOWNSEND--123",
    "Type": "BuildingNumber",
    "Text": "123 Townsend St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94107 - 320 Addresses"
  },
  {
    "Id": "US|US|ENG|94105-CA-SAN_FRANCISCO--ST-MISSION--123",
    "Type": "BuildingNumber",
    "Text": "123 Mission St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105 - 48 Addresses"
  },
  {
    "Id": "US|US|A|Z222445177|123",
    "Type": "Address",
    "Text": "123 2nd St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105"
  },
  {
    "Id": "US|US|A|Z222445178|1",
    "Type": "Address",
    "Text": "123 2nd St Ste 1",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105"
  },
  {
    "Id": "US|US|A|Z223933823|123",
    "Type": "Address",
    "Text": "123 Mission St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105"
  },
  {
    "Id": "US|US|ENG|94103-CA-SAN_FRANCISCO--ST-GUERRERO--123",
    "Type": "BuildingNumber",
    "Text": "123 Guerrero St Apt",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94103 - 3 Addresses"
  },
  {
    "Id": "US|US|A|Z222437371|123",
    "Type": "Address",
    "Text": "123 Guerrero St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94103"
  },
  {
    "Id": "US|US|A|Z222457206|123",
    "Type": "Address",
    "Text": "123 Waverly Pl",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94108"
  },
  {
    "Id": "US|US|A|Z222454357|123",
    "Type": "Address",
    "Text": "123 Joice St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94108"
  },
  {
    "Id": "US|US|ENG|94108-CA-SAN_FRANCISCO--ST-JOICE--123",
    "Type": "BuildingNumber",
    "Text": "123 Joice St Apt",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94108 - 4 Addresses"
  }
]

Mailing addresses can be found in the response of all JSON objects that have the Type field set to Address. In this simple use case, the user interface could just suppress all other types (such as BuildingNumber, Street, and so on) and display only address objects.

To find the address “123 Guerrero St”, you click it. This causes the client application to issue a request to the /address/retrieve endpoint, passing an ID parameter with the value US|US|A|Z222437371|123, which then retrieves the full address record.

Otherwise, you must continue typing the address, while the UI continually issues equivalent find requests until the address you want is found.

Retrieve Addresses

After an ID is obtained, the full and componentized information for this address can be obtained by calling the /address/retrieve endpoint with that ID as a parameter.

Doing so for the simple find use case produces the following results:

Request

http://adc00qrw.oracle.com:7767/av/api/v3/address/retrieve?Id=US|US|A|Z222437371|123

Response

[
    {
        "Id": "US|US|A|Z222437371|123",
        "Premise": "123",
        "Thoroughfare": "Guerrero St",
        "Locality": "San Francisco",
        "DeliveryAddress1": "123 Guerrero St",
        "SubAdministrativeArea": "San Francisco",
        "AdministrativeArea": "CA",
        "AdministrativeAreaName": "California",
        "PostalCode": "94103-1072",
        "CountryName": "United States",
        "ISO3166-2": "US",
        "ISO3166-3": "USA",
        "ISO3166-N": "840",
        "Address": "123 Guerrero St|SAN FRANCISCO CA 94103-1072",
        "DeliveryAddress": "123 Guerrero St",
        "Address1": "123 Guerrero St",
        "Address2": "SAN FRANCISCO CA 94103-1072",
        "PostalCodePrimary": "94103",
        "PostalCodeSecondary": "1072"
    }
]

Advanced Search Use Case

Suppose you want to search for the address “941 Dolores St, unit #3” in the USA, and you start typing the characters “941”. The corresponding REST transaction initiated by the UI is shown in Request 1 and Response 1.

Note: Examples show Indirect Mode. Functionality is identical for Direct Mode, but with an initial preparefind.

In this case, the UI takes all types of records into account, not only Type=Address. Looking at the results from Response 1, you might not continue typing additional characters, but instead select the result “Dolores St Apt”, where the Type is BuildingNumber. The UI should understand that this is not a final selection of an address, but rather a drilldown into one of the results, which contains four more addresses. This is accomplished by using the result’s ID and passing it as a Container parameter into a new request, as shown in Request 2. In Response 2, you see that the previous result is not visible anymore, but all four apartments are shown.

After seeing the #3 unit, you get the record by calling the /address/retrieve endpoint using the ID value of US|US|A|Z222467771|3.

Request 1

http://adc00qrw.oracle.com:7767/av/api/v3/address/find?Text=941

Response 1

[
 {
 "Id": "US|US|A|Z222467773|941",
 "Type": "Address",
 "Text": "941 Dolores St",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|ENG|94110-CA-SAN_FRANCISCO--ST-DOLORES--941",
 "Type": "BuildingNumber",
 "Text": "941 Dolores St Apt",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94110 - 4 Addresses"
 },
 {
 "Id": "US|US|ENG|94117-CA-SAN_FRANCISCO--ST-PAGE--941",
 "Type": "BuildingNumber",
 "Text": "941 Page St Apt",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94117 - 5 Addresses"
 },
 {
 "Id": "US|US|A|Z222490758|941",
 "Type": "Address",
 "Text": "941 Page St",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94117"
 },
 {
 "Id": "US|US|A|Z222412877|941",
 "Type": "Address",
 "Text": "941 Ridgeview Ct Unit",
 "Highlight": "0-3",
 "Description": "South San Francisco CA 94080"
 },
 {
 "Id": "US|US|A|Z222412876|941",
 "Type": "Address",
 "Text": "941 Ridgeview Ct",
 "Highlight": "0-3",
 "Description": "South San Francisco CA 94080"
 },
 {
 "Id": "US|US|A|Z213529633|941",
 "Type": "Address",
 "Text": "941 Shorepoint Ct",
 "Highlight": "0-3",
 "Description": "Alameda CA 94501"
 },
 {
 "Id": "US|US|ENG|94501-CA-ALAMEDA--CT-SHOREPOINT--941",
 "Type": "BuildingNumber",
 "Text": "941 Shorepoint Ct Apt",
 "Highlight": "0-3",
 "Description": "Alameda CA 94501 - 146 Addresses"
 },
 {
 "Id": "US|US|ENG|94608-CA-EMERYVILLE--ST-37TH--941",
 "Type": "BuildingNumber",
 "Text": "941 37th St Apt",
 "Highlight": "0-3",
 "Description": "Emeryville CA 94608 - 5 Addresses"
 },
 {
 "Id": "US|US|A|Z224475658|941",
 "Type": "Address",
 "Text": "941 Aileen St",
 "Highlight": "0-3",
 "Description": "Emeryville CA 94608"
 }
]

Request 2

http://adc00qrw.oracle.com:7767/av/api/v3/address/find?Text=941&Container=US|US|ENG|94110-CA-SAN_FRANCISCO--ST-DOLORES--941

Response 2

[[
 {
 "Id": "US|US|A|Z222467771|1",
 "Type": "Address",
 "Text": "941 Dolores St Apt 1",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467771|2",
 "Type": "Address",
 "Text": "941 Dolores St Apt 2",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467771|3",
 "Type": "Address",
 "Text": "941 Dolores St Apt 3",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467771|4",
 "Type": "Address",
 "Text": "941 Dolores St Apt 4",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467772|A",
 "Type": "Address",
 "Text": "941 Dolores St Apt A",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 }
]

For detailed information, see REST API for Oracle Address, Email, and Phone Verification.

Verify Addresses

Use Address Verify to do the following:

Correct and enhance an address. For example, you can correct misspelled city or street names; add missing elements, like full postal code or state; and get geographic location, such as latitude, longitude.
Get accurate representation of address from postal files. For example, change “street” to “St” or “parkw” to “Pkwy”.
Transliterate an address using outputscript (v2) or OutputScript (v3). The following values are supported:
- Native: This returns output in the script most commonly used in that country (see below).
- Latn: This returns output in the Latin alphabet (English).
- no value (default): This tries to match the address output script to whatever is provided as the address input script.
For example, input Japan addresses that are in Latin script and get the verified output in Hani script. This is supported for addresses for certain countries.

Here are the native scripts (in ISO and full name) with the country where this is known to be supported:
- Latn – Latin (English transliteration wherever possible)
- Cyrl – Cyrillic (Russia)
- Grek – Greek (Greece)
- Hebr – Hebrew (Israel)
- Hani – Kanji (Japan)
- Hans – Simplified Chinese (China)
- Arab – Arabic (United Arab Emirates)
- Thai – Thai (Thailand)
- Hang – Hangul (South Korea)
- Native – Output in the native script wherever possible
Transliteration is bi-directional and generally happens from Native to Latn and Latn to Native using data for countries stated above next to the scripts. However, Latn to Hans is not available for any country other than China.

Loqate does not support processing nor transliteration between Latin and native scripts outside of these stated countries. For example, if Greek (Grek) is used on a Portugal address, Loqate cannot parse or validate the record, nor transliterate it into Latin script. Similarly, a Portugal address entered in Latin cannot transliterate to any other script.

For information on Loqate's transliteration support, see https://support.loqate.com/character-scripts/.

Note: Do not set minimumverificationmatchscore to 100 unless you know you have a valid address and you just want to standardize it. In general, use a country's default minimumverificationlevel (for example, US=4). The exception is if you need to verify a zip code.

The following example shows the steps to verify an address. The process is the same for a single address verification request and for multiple addresses.

First, set up authorization. The API uses a standard OAuth 2.0 flow to authorize and authenticate API clients and users. If you're using the API, you should already have an OAuth client ID and client secret. You can request an access token with the following POST method: http://host:port/av/api/v3/oauth2/token.

Then enter the credentials (key value) you received.
Enter the Address Verify URL as http://host:port/av/api/v3/address/verify, and then enter the address you want verified as input in the body. This example provides only Address1, Address2, and Country.
Click Send, and the complete verified, standardized address is returned as the response.