Oracle® Cloud

Using Oracle Address Verification Cloud

20.1.3

E59772-17

March 2020

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 can be used in conjunction with DaaS (Data as a Service), or it can be used as a standalone service with other applications. It provides a REST-based endpoint that supports searching and verifying addresses worldwide.

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

There is no charge for the search capability. 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 with the VERIFY record and when the "verified" field in the response body is "Y".

There is no user interface provided, but you have access to your usage report on the DaaS interface. The following screen shot shows 0 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.

How to Begin with Address Verification

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

  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.

    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.

  5. 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.

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.


Oracle Cloud Using Oracle Address Verification Cloud, 20.1.3

E59772-17

Copyright © 2016, 2020, Oracle and/or its affiliates.

Primary Author: Michele Cyran

Contributor: Tom Enderes, Keerthy Jayaraj, Srini Pendem, Alicia Wu

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or “commercial computer software documentation” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloud services are defined by the applicable contract for such services. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.