Use Address Verification REST API
Address verification lets you search and verify global addresses in your applications.
Watch this video for an overview of the REST API features.
Topics
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 ModeREST 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.
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).
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:preparefind
.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.
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:
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
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
.
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
-
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) orOutputScript
(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/.
-
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.-
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.