1. REST API for Oracle Address, Email, and Phone Verification
  2. Tasks
  3. Version2

Search and Verify Address

post

/api/v2/addressclean

Address Clean

Note: We recommend you use the equivalent function in the latest version, v3/.

This method expects one or more address input records to be cleaned. On success, it sends any output records back.

This input should be sent as a JSON array containing at least one record element. The input must be sent as a content, type 'application-json'. Each record element must have all required attributes set and should be formatted as a JSON map.

Each input record and each output record is a JSON map, and the parameters are described in the following table. Each parameter, input or output, can be included in the JSON map, even if the parameter is not applicable to the mode of this particular record. In this case, the parameter is ignored. For more information, see Address Clean Interface of Enterprise Data Quality 11.1.1.7.9.
Attribute Name Data Type Direction Applicable Modes Notes
addressid String In/Out V,S Identifier to map input records to output records and vice versa.
address1 String In/Out V,S Address line 1.

For SEARCH mode: Oracle recommends that you provide all known information (except country) as text in this field. Only use the country or defaultcountrycode fields when the country is known.
address2 String In/Out V,S Address line 2.
address3 String In/Out V,S Address line 3.
address4 String In/Out V,S Address line 4.
dependentlocality String In/Out V,S A smaller population center data element, dependent on the contents of the city field. For example, a neighborhood in Turkey. For many countries, this attribute is not used.
doubledependentlocality String In/Out V,S The smallest population center data element, dependent on both the contents of the city and dependentlocality fields. For example, a village in the UK. For many countries, this attribute is not used.
city String In/Out V,S The locality, town, or city of the address.
subadminarea String In/Out V,S The smallest geographic data element within a country. For example, a county in the USA.
adminarea String In/Out V,S The most common geographic data element within a country. For example, a state in the USA or a province in Canada.
postalcode String In/Out V,S Postal or zip code for the address, if relevant for the country.
postalcodeprimary String In/Out V,S First part of the postal/zip code.
postalcodesecondary String In/Out V,S Second part of the postal/zip code, if relevant for the country.
country String In/Out V,S On input, an ISO two-character country code (preferred) or country name. On output, the full country name (even if the input is the country ISO code).

Note: If this field is blank, then other fields can be used internally to derive the country. Verify mode requires a country. If both the country field and the defaultcountrycode field are blank, then USA is assigned as the country.

defaultcountrycode String Input only V,S Default ISO two-character country code to use if the country code is blank. This overrides the default country value.
outputscript (parameter) String Input only V,S Certain input and output fiels such as (address1..n, administrative areas, city) can be sent and returned in different scripts. (Not country - or postal-code related fields, these must be in Latn (i.e. English).)
As input, only the native script, and, if different, Latn (i.e. English) can be expected to work well. This parameter (optional) then can be used to request a specific script to be returned via an ISO 15924 Code, such as Latn (i.e. English), Cyrl, Grek, Hebr, Hani, Hans, Arab, Thai, Hang, Native>. Native is not a code but rather a suggestion to pick whatever the local script for a given country is. A request to use "Native" and "Latn" can always be fulfilled. If this parameter is not provided or has an empty value, we will turn the option to transliterate off, this is the default behavior. This means, the output script will be selected based on the input script used (i.e. If the input is provided in a native script, and we support this native script, then the output will be in the same native script. In all other cases, the output script will be set to Latn (English))
charcase (parameter) String Input only V,S Transforms output according to the setting:

U (Upper) - Transforms all text to upper case.

L (Lower) - Transforms all text to lower case.

M (Mixed) - Transforms all text to mixed case, except postalcode and adminarea. These field values are left as returned from the AV processor if the address was verified. If the address was not verified, then the postalcode is left as entered, and the adminarea is converted to mixed case.

O (Original) - Text is not transformed.

mode (parameter) String Input only V,S Mode in which the request is to be run.

Enter V to verify this record or S to search for this record. The Version2 API now supports different ways of searching for this added. Setting this mode to "S" is one of them. (For another way, please also refer to find and preparefind) Note that in search mode you can get back up to 20 output records for each input record. These records will be in sorted order, from the best potential search result to the worst.
minimumverificationmatchscore (parameter) Number Input only V,S A numeric value between 0 and 100, representing the minimum score that a match must achieve to be used as a cleaned address. Input addresses are left unchanged if the Match Score of the Address Verification processor for the address is lower than the input value. Optional, default is 0
minimumverificationlevel (parameter) Number Input only V,S A numeric value between 1 and 5, representing the minimum verification level that a match must achieve to be used as a cleaned address. Optional, default is 1.

Input addresses are left unchanged if the Verification Level of the Address Verification processor for the address is lower than the input value. For a description of each level, see Section 2.1.3, "Notes on Verification Levels".

allowedverificationresultcodes (parameter) String Input only S A list of any of the following single-letter result codes with no separator. Optional, the default string for Verify Mode is 'VP' and for Search Mode 'VPAR'.

V (Verified)

P (Partially Verified)

A (Ambiguous)

R (Reverted)

U (Unverified, can not be requested as input)

Input addresses are left unchanged if the Verification Result Code (for example, the first character of the verificationcode) for the address is not one of the listed input values.

fulladdress String Output only V,S Full verified address returned from address verification. The address lines are pipe-separated.
countrycode String Output only V,S ISO 2 char country code of verified address country.
verificationcode String Output only V,S Verification code for the address. For detailed information, see the verificationcodedescription field the AccuracyCode tab AccuracyCode on the Address Verification Processor page.
verified String Output only V,S In Verify mode: Whether the result produced was verified to a sufficient level according to the configuration of the process and the resultant verification code. This also indicates whether or not the input address was changed to the returned address from address verification.

In Search mode: Could find at least one or more results for this input. Return values: Y Yes successful, N No not successful, or X EDQ AV misconfigured.
verificationcodedescription String Output only V,S English description of the verification code.

The country provided (implicitly or explicitly), has a special status in verification mode. And in verification mode, it is possible to get results back that contain the overall status UNVERIFIED / verified=N but contain a match score of 100. In this case, the UNVERIFIED status is given priority over the score.

latitude Number Output only V This attribute is not supported.
longitude Number Output only V This attribute is not supported.
geoaccuracycode String Output only V This attribute is not supported.
geoaccuracycodedescription String Output only V This attribute is not supported.
geodistance Number Output only V This attribute is not supported.

Request

Query Parameters
Supported Media Types
Request Body - application/json; charset=UTF-8 ()
Root Schema : schema
Type: array
Show Source
Nested Schema : InputRecord
Type: object
Show Source
Back to Top

Response

Supported Media Types

200 Response

Success
Body ()
Root Schema : schema
Type: array
Show Source
Nested Schema : OutputRecord
Type: object
Show Source

401 Response

Unauthorized

403 Response

Forbidden

500 Response

An unexpected error occurred during the request.
Back to Top

Examples

Example Requests

[{"addressid":"a225-65f8b7f90b18","address1":"500 Oracle Parkway","city":"Redwood City","defaultcountrycode":"US","charcase":"M","mode":"V"}]

The following example shows a client invocation using the command-line tool curl. Copy/paste the line for a quick test.
curl -i -H "Accept: application/json" -H "Content-Type: application/json" --basic --user myname:mypasswd -X POST -d "[{"addressid":"a225-65f8b7f90b18","address1":"500 Oracle Parkway","city":"Redwood City","defaultcountrycode" :"US","charcase":"M","mode":"V"}]" https://mydataservice-a18451.data.dc777.oraclecloud.com/av/api/v2/addressclean
Back to Top