Address Verification lets you verify and standardize addresses in your applications. For example, the service can correct misspelled city or street names, complete postal codes, and standardize abbreviations like Pkwy. The service takes your data and returns matches—one match or multiple matches—and you can select which version you want to use as the standard.

Topics:

About Address Verification

Oracle Address Verification provides a REST-based endpoint that supports searching and verifying addresses worldwide. It can be used in conjunction with DaaS (Data as a Service), or it can be used as a standalone service with other applications.

There is no user interface, but you have access to your usage report on the DaaS interface. The following screen shot shows 0 address records used (0%) on a 10,000 record subscription. For an unlimited subscription, it shows only the number of records used (and not a percentage). If you haven’t purchased a subscription for DaaS, then this interface shows only the Address Verification Usage and the Learn More boxes.

Address Verification can be used in real time to verify addresses or to provide type-ahead smart data when entering addresses. It can also be used in batch mode to verify large numbers of addresses.

Watch these videos for a summary of Address Verification functionality.
  • Verify Addresses in Real Time

  • Verify Addresses using Smart Data

  • Run Batch Address Cleansing

How to Begin with Address Verification

Here's a summary of the key steps to get started with Address Verification subscriptions.

There is no charge to search addresses. Search as much as you want, and when you see a record you want to verify, then call the verify API with this record, and the usage count increases accordingly. The record usage count only increases when the "verified" field in the response body is "Y".

  1. Request a trial or purchase a subscription. See Sign Up for a Trial Subscription or Buying a Nonmetered Subscription to an Oracle Cloud Service in Getting Started with Oracle Cloud. Address Verification is available with one of the following subscriptions:
    • Unlimited annual subscription

    • Per record annual subscription (for example, purchase a pool of 200,000 address verification transactions)

    • Free monthly trial subscription with 1,000 address verification transactions

    Note:

    Address Verification and DaaS (Data as a Service) offer a combined trial subscription; that is, when you order a trial for one service, you also get the other. Each service must be purchased separately, but they can be part of the same subscription order. Trial subscriptions last for 30 days and include 1,000 Address Verification records, 500 Account Enrichment records, and 500 Contact Enrichment records.
  2. Activate the service. See Activating Oracle Cloud Services in Getting Started with Oracle Cloud.
  3. Log on to the Oracle Cloud console to get the Address Verification API URL.
    The following default account roles are created during Address Verification provisioning:
    • Data Service Administrator (dataService_administrator)
    • Data Service Client APPID (dataservice_client_api_appid)
    • Data Service User (dataService_user)
  4. Create accounts for your users and assign them appropriate privileges and roles. See Managing Your Oracle Cloud Service in Getting Started with Oracle Cloud.Optionally, enable Oracle CX Sales or B2B Service to integrate with Address Verification for real-time address verification. This also lets you schedule large-scale batch verifications. Assuming you have an active CX Sales or B2B Service subscription, and then add an Address Verification subscription (completing all steps above), just follow these four steps:
    1. In the Oracle Cloud console, create a new user. Expand the Advanced Roles section and add the Data Service Client AppID role for this user.
    2. In the Oracle Cloud console, reset the password for this user.
    3. In CX Sales or B2B Service, configure the Manage Integration with Oracle Address Verification task. In the Setup and Maintenance work area, go to the following:

      - Offering: Sales

      - Functional Area: Integrations

      - Task: Manage Integration with Oracle Address Verification

      For the URL, remove /data/ui from the end of the instance address listed in your Welcome email and on the Oracle Cloud console; for example, https://mydataservice-myidentitydomain.data.us2.oraclecloud.com. Select oracle/wss_username_token_over_ssl_client_policy for Security Policy to connect to Address Verification, and enter the user and password for the user you created in the first step.

    For more information, see Getting Started with Your Sales Implementation.

    Note:

    If you have a preproduction environment for CX Sales or B2B Service, test the service association between your CX Sales or B2B Service preproduction environment and your trial subscription (limit 500 records to test). When you go to production, do the service association between your CX Sales or B2B Service production environment and your Address Verification production environment. The service association steps are the same, but the trial/production service URLs are different.

Use Address Verification REST APIs

Oracle Address Verification lets you search and verify addresses in your applications. Access the REST APIs in the following format: https://serviceName-identityDomain.data.us2.oraclecloud.com/av/api. For example: https://datatrial1234-usoracletrial1234.data.us2.oraclecloud.com/av/api/v3/address/find.

Watch this video for an overview of the REST API features.

Search Addresses

The Address Verification service supports Capture+ (by GBG|Loqate) for searching valid mailing addresses worldwide.

Note:

Previously, you could enter your known information into the API (such as city and address1) and specify search mode (S). In the response, the API returned a list of records (or a single record with verified="None" if nothing was found for that input). The search mode (available in v2, based on Oracle EDQ) and the auto complete method (available in v3, based on Loqate) now are in maintenance mode only.

Capture+ is available through the following RESTful endpoints:

/api/v2/address/find
/api/v2/address/preparefind
/api/v2/address/retrieve
/api/v3/address/find
/api/v3/address/preparefind 
/api/v3/address/retrieve

Capture+ functions the same in v2 and in v3. The only difference is that /address/retrieve shows EDQ-style fields in v2, and it shows Loqate-style fields in v3.

Search Simple Use Case

This simple use case applies whether you search via /preparefind or /find: the functionality is identical. When you enter the first three digits (such as “123”) of an address in the United States, as in the following request and response, the first find request is issued.

Request 1

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

Response 1

[
  {
    "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"
  }
]

The service assumes that you’re looking for mailing addresses. These can be found in the response: all JSON objects which have the Type field set to the value Address. In this simple use case, the UI could suppress all other types (such as BuildingNumber, Street, and so on) and display only address objects.

If you see the address you want, such as “123 Guerrero St”, click that. 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, continue to enter more of the address, and the UI continually issues equivalent find requests, until the desired address is found.  

Retrieve Addresses

After an ID has been found, get the full and componentized information for this address by invoking the /address/retrieve endpoint with the Id parameter. The simple find example then produces the following results:

Version 2 Request

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

Version 2 Response

[
    {
        "addressid": "US|US|A|Z222437371|123",
        "address1": "123 Guerrero St",
        "address2": "",
        "address3": "",
        "address4": "",
        "dependentlocality": "",
        "doubledependentlocality": "",
        "city": "San Francisco",
        "subadminarea": "San Francisco",
        "adminarea": "CA",
        "superadminarea": "",
        "postalcode": "94103-1072",
        "postalcodeprimary": "94103",
        "postalcodesecondary": "1072",
        "country": "United States",
        "fulladdress": "123 Guerrero St|SAN FRANCISCO CA 94103-1072",
        "countrycode": "US",
        "verificationcode": null,
        "verified": null,
        "verificationcodedescription": null,
        "latitude": null,
        "longitude": null,
        "geoaccuracycode": null,
        "geoaccuracycodedescription": null,
        "geodistance": null
    }
]

Version 3 Request

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

Version 3 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"
    }
]

Search Advanced Drilldown Use Case

Suppose that you want to search for the address “941 Dolores St, unit #3”. You enter 941. The following Request 1 and Response 1 show the corresponding REST transaction initiated by the UI.

In this advanced drilldown search case, the UI takes all types of records into account, not only Type=Address. From the results in Response 1, you might not continue typing additional characters, but instead select the result “Dolores St Apt”, where Type is BuildingNumber.

The UI understands 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, the previous result is not visible anymore, but all four apartments are presented. After seeing the desired #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.us.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.us.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 Verification Cloud.

Verify Addresses

Use Address Verification in verify mode to do the following tasks:
  • Check if an address is valid (addressclean).

  • 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; for example, input addresses in Arabic and get the verified output in English. This is supported for a native (local) language to Latin (that is, English) outputscript or from Latin to a native outputscript. Requests in a non-Latin language cannot have an OutputScript response in another non-Latin language. For example, you cannot search addresses in Arabic and get the verified output in Chinese. Both these languages are supported, but the transliteration between them is not supported.

    The following values are supported for the OutputScript option:
    • 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

If the result is verified or changed according to the configuration specified, then verified=Y. By default, if no option is specified, then the output script will match the input wherever possible.

Note:

Do not set minimumverificationmatchscore to 100 unless you know you have a valid address and you just want 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.

Use a REST Client to Make Calls to Address Verification

This section shows the steps to verify an address using SoapUI. The process is the same for a single address verification request and for multiple (batch) requests.
  1. In SoapUI, select File — New REST Project.
  2. Enter the Address Verification Cloud URL as http://host:port/av/api/v2/addressclean.
  3. In the new REST project, click Auth to add new authorization.
  4. Select Basic for the authorization type (or create one if it is not present).
  5. Enter user credentials, and select Authenticate pre-emptively.
  6. From the Method list, select POST.
  7. Enter the request in the Media Type (application/json) window. For example:
    [{"addressid":"234",
    "address1":"300 ORACLE PKWY",
    "address2":"",
    "address3":"",
    "address4":"",
    "city":"REDWOOD CITY",
    "postalcode":"94065 ",
    "country":"US",
    "defaultcountrycode":"",
    "charcase":"M",
    "mode":"V",
    "minimumverificationmatchscore":"70",
    "allowedverificationresultcodes":"V"}]
  8. Submit the request. On success, it sends any output records back.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.