Global Address Verification:Request: Difference between revisions

From Melissa Data Wiki
Jump to navigation Jump to search
← Older edit
No edit summary
No edit summary
 
(10 intermediate revisions by the same user not shown)
Line 6: Line 6:
{{CustomTOC}}
{{CustomTOC}}


A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID and at least one address record.
A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and at least one address record.


Global Address Verification supports JSON, JSONP, REST, SOAP, and XML protocols.
Global Address Verification supports JSON, JSONP, REST, SOAP, and XML protocols.
==URL==
{{URL-GlobalAddressVerification}}




Line 16: Line 20:
{| class="alternate01 sortable"
{| class="alternate01 sortable"
!Field Name !! Level !! REST !! JSON/XML
!Field Name !! Level !! REST !! JSON/XML
|- style="vertical-align:top;"
|Transmission Reference||Request||t||TransmissionReference
|-
|-
|Customer ID||Request||id||CustomerID
|Transmission Reference||rowspan="4" valign="center"|Request||t||TransmissionReference
|-
|Customer ID||id||CustomerID
|-
|Options||opt||Options
|-
|-
|Options||Request||opt||Options
|Format||format||Format
|-
|-
|Record ID||Record|| ||RecordID
|Record ID||rowspan="19" valign="center"|Record|| ||RecordID
|-
|-
|Organization||Record||org||Organization
|Organization||org||Organization
|-
|-
|Address Line 1||Record||a1||AddressLine1
|Last Name||last||LastName
|-
|-
|Address Line 2||Record||a2||AddressLine2
|Address Line 1||a1||AddressLine1
|-
|-
|Address Line 3||Record||a3||AddressLine3
|Address Line 2||a2||AddressLine2
|-
|-
|Address Line 4||Record||a4||AddressLine4
|Address Line 3||a3||AddressLine3
|-
|-
|Address Line 5||Record||a5||AddressLine5
|Address Line 4||a4||AddressLine4
|-
|-
|Address Line 6||Record||a6||AddressLine6
|Address Line 5||a5||AddressLine5
|-
|-
|Address Line 7||Record||a7||AddressLine7
|Address Line 6||a6||AddressLine6
|-
|-
|Address Line 8||Record||a8||AddressLine8
|Address Line 7||a7||AddressLine7
|-
|-
|Double Dependent Locality||Record||ddeploc||DoubleDependentLocality
|Address Line 8||a8||AddressLine8
|-
|-
|Dependent Locality||Record||deploc||DependentLocality
|Double Dependent Locality||ddeploc||DoubleDependentLocality
|-
|-
|Locality||Record||loc||Locality
|Dependent Locality||deploc||DependentLocality
|-
|-
|Sub Administrative Area||Record||subadmarea||SubAdministrativeArea
|Locality||loc||Locality
|-
|-
|Administrative Area||Record||admarea||AdministrativeArea
|Sub Administrative Area||subadmarea||SubAdministrativeArea
|-
|-
|Postal Code||Record||postal||PostalCode
|Administrative Area||admarea||AdministrativeArea
|-
|-
|Sub National Area||Record||subnatarea||SubNationalArea
|Postal Code||postal||PostalCode
|-
|-
|Country||Record||ctry||Country
|Sub National Area||subnatarea||SubNationalArea
|-
|-
|Format||Request||format||Format
|Country||ctry||Country
|}
|}


Line 85: Line 91:
:''Required.''
:''Required.''


:This is a string value containing the identification number issued to the customer by Melissa Data for Global Address Verification.
:This is a string value containing the License Key issued to the customer by Melissa Data for Global Address Verification.


:If this element is absent, the Web Service will return an error. To receive a customer ID, please contact your Melissa Data sales representative at 1-800-MELISSA.
:If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.


:{| class="alternate01"
:{| class="alternate01"
Line 170: Line 176:
|-
|-
|<code>NATIVE</code>||Returns in the native script for the designated country.
|<code>NATIVE</code>||Returns in the native script for the designated country.
|}
:<h4 style="border-bottom:1px solid black;">OutputGeo</h4>
::Allows you to specify if you want geocoding output in the response.
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="3"|'''OutputGeo'''||<code>ON</code>||'''''Default.''''' Latitude and longitude is returned in the output when available
|-
|<code>OFF</code>||Do not return latitude and longitude for the record.
|}
|}


Line 190: Line 208:
|}
|}


:<h4 style="border-bottom:1px solid black;">USPreferredCityNames</h4>
::Allows you to override the city name and return only the USPS preferred city name.
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''USPreferredCityNames'''||<code>ON</code>||If set to on, we will override and return only the USPS preferred city name.
|-
|<code>OFF</code>||'''''Default.''''' Leave valid vanity city names as preferred by the USPS.
|}
:<h4 style="border-bottom:1px solid black;">USStandardizationType</h4>
::Allows you to specify the standardization of the address abbreviation.
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="3"|'''USStandardizationType'''||<code>Auto</code>||This uses the input as a guide for how to standardize.
|-
|<code>Short</code>||'''''Default.''''' Leave the US address in short abbreviated form as preferred by the USPS. For example: <pre>100 W Main St East</pre>
|-
|<code>Long</code>||Always spell the address out. For example: <pre>100 West Main Street East</pre>
|}
:<h4 style="border-bottom:1px solid black;">DetailedResults</h4>
::This is for users that have experience or code using Address Object and would like to have those codes alongside the Global Address result codes.
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''DetailedResults'''||<code>ON</code>||For US and CA addresses only. This will return more detailed and different result codes that come from our Address Object product.
|-
|<code>OFF</code>||'''''Default.''''' No extra result codes will be returned.
|}
:<h4 style="border-bottom:1px solid black;">IncludeRemnant</h4>
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''IncludeRemnant'''||<code>ON</code>||'''''Default.''''' In cases where Global Address identifies a piece of the input as extra information, we label this as Remnant and append it to the beginning of the address lines. This is because it is common to add additional delivery information like Care Of or Attention data, that may be useful and we do not want to throw away. The downside is that this information may not always be useful information, but that is not something we can always determine so we lean on the side of caution.
|-
|<code>OFF</code>||By setting this option to false, we will no longer append the Remnant information anywhere in the address lines. This may be useful for users who identify that Remnant information in their data is mostly not useful.
|}
:<h4 style="border-bottom:1px solid black;">ExtendedDateTime</h4>
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''ExtendedDateTime'''||<code>ON</code>||Additional information related to time zone names and UTC information for both standard and daylight savings will be made available in the Extras section. Please see the Extras section for additional details.
|-
|<code>OFF</code>||'''''Default.''''' No additional output information is provided.
|}
:<h4 style="border-bottom:1px solid black;">USExtras</h4>
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''USExtras'''||<code>ON</code>||Additional US only output will be made available in the Extras section. These outputs are related to Census, County, and School information. Please see the Extras section for additional details.
|-
|<code>OFF</code>||'''''Default.''''' No additional output information is provided.
|}
:<h4 style="border-bottom:1px solid black;">OriginDateTime (BETA)</h4>
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|'''OriginDateTime'''||(String)||A string DateTime value with UTC data to use in the calculation of the local date time. This feature will allow you to convert the origin time into the local time at the output address. This calculation takes into account the different in UTC from the origin to the output address and also takes into account the dates that daylight savings is observed at the destination. Example: OriginDateTime:2022-01-13 18:33:16 (UTC-8:00). Note, we need the UTC value to know exactly where the origin time is from. If you do not specify a UTC value, we will assume UTC value of 0.
|}
:<h4 style="border-bottom:1px solid black;">GBExtras</h4>
::Allows you to choose to add the UPRN output.
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''GBExtras'''||<code>ON</code>||Adds the additional output value of UPRN. Please see the Extras section for additional details.
|-
|<code>OFF</code>||'''''Default.''''' No additional output information is provided.
|}
<h3 style="background-color:rgb(240,240,240);">Format</h3>
:''Optional.''
:The desired format of the response.
:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&format = '''''string'''''</code>
|-
|JSON (HTTP Header)||<code>Accept: application/json</code>
|-
|SOAP/XML (HTTP Header)||<code>Accept: application/xml</code>
|}


==Request Record Elements==
==Request Record Elements==
Line 234: Line 355:
|-
|-
|SOAP/XML||<code><Organization>'''''string'''''</Organization></code>
|SOAP/XML||<code><Organization>'''''string'''''</Organization></code>
|}
<h3 style="background-color:rgb(240,240,240);">LastName</h3>
:''Optional.''
:US Only. For addresses missing a secondary like a suite or apartment, we can use the last name and append that information for residential addresses.
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"LastName":"'''''string'''''"</code>
|-
|REST||<code>&last = '''''string'''''</code>
|-
|SOAP/XML||<code><LastName>'''''string'''''</LastName></code>
|}
|}


Line 507: Line 644:
|-
|-
|SOAP/XML||<code><Country>'''''string'''''</Country></code>
|SOAP/XML||<code><Country>'''''string'''''</Country></code>
|}
<h3 style="background-color:rgb(240,240,240);">Format</h3>
:''Optional.''
:The desired format of the response.
:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&format = '''''string'''''</code>
|-
|JSON/XML
|
{| class="alternate01"
|-
|colspan="2"|'''HTTP Header'''
|-
|XML||<code>application/xml</code>
|-
|JSON||<code>application/json</code>
|}
|}
|}


Latest revision as of 00:34, 11 June 2022

← Global Address Verification

Global Address Navigation
Introduction
Licensing
Input/Output
Request Fields
Response Fields
Examples
REST JSON
REST JSONP
REST XML
Batch JSON
Batch SOAP
Batch XML
Result Codes
Result Code Use
Global Address Verification Result Codes
Sample Code



A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and at least one address record.

Global Address Verification supports JSON, JSONP, REST, SOAP, and XML protocols.


URL

SOAP

Use URL
Secure https://address.melissadata.net/v3/SOAP/GlobalAddress


REST, XML, JSON, etc.

Use URL
Secure https://address.melissadata.net/v3/WEB/GlobalAddress/doGlobalAddress


Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name Level REST JSON/XML
Transmission Reference Request t TransmissionReference
Customer ID id CustomerID
Options opt Options
Format format Format
Record ID Record RecordID
Organization org Organization
Last Name last LastName
Address Line 1 a1 AddressLine1
Address Line 2 a2 AddressLine2
Address Line 3 a3 AddressLine3
Address Line 4 a4 AddressLine4
Address Line 5 a5 AddressLine5
Address Line 6 a6 AddressLine6
Address Line 7 a7 AddressLine7
Address Line 8 a8 AddressLine8
Double Dependent Locality ddeploc DoubleDependentLocality
Dependent Locality deploc DependentLocality
Locality loc Locality
Sub Administrative Area subadmarea SubAdministrativeArea
Administrative Area admarea AdministrativeArea
Postal Code postal PostalCode
Sub National Area subnatarea SubNationalArea
Country ctry Country


Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Transmission Reference

Optional.
This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Protocol Syntax
JSON "TransmissionReference":"string"
REST ?t = string
SOAP/XML <TransmissionReference>string</TransmissionReference>


Customer ID

Required.
This is a string value containing the License Key issued to the customer by Melissa Data for Global Address Verification.
If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.
Protocol Syntax
JSON "CustomerID":"string"
REST &id = string
SOAP/XML <CustomerID>string</CustomerID>


Options

Optional.
This is a string value containing the options set by the user.
Protocol Syntax
JSON "Options":"string"
REST ?opt = string
SOAP/XML <Options>string</Options>


List options in the following format, with multiple options delimited with a ",".
Syntax
OptionName:Parameter,OptionName:Parameter


DeliveryLines

This options allows you to specify if the Address Lines 1-8 should contain just the delivery address or the entire address.
Option Name Parameter Description
DeliveryLines Off Default. Address Lines 1-8 return the entire address.
On Address Lines 1-8 return just the street address and dependent locality. It will not contain locality, administrative area, postal code, etc.


LineSeparator

This is the line separator used for the FormattedAddress result.
Option Name Parameter Description
LineSeparator SEMICOLON Default. A semicolon (;).
PIPE A pipe (|).
CR A carriage return.
LF A line feed.
CRLF A carriage return + line feed.
TAB A tab.
BR A line break.


OutputScript

This is the script type used for all applicable fields.
Option Name Parameter Description
OutputScript NOCHANGE Default. Returns the same script that is sent in.
LATN Returns in the Latin script.
NATIVE Returns in the native script for the designated country.


OutputGeo

Allows you to specify if you want geocoding output in the response.
Option Name Parameter Description
OutputGeo ON Default. Latitude and longitude is returned in the output when available
OFF Do not return latitude and longitude for the record.


CountryOfOrigin

This is used to determine whether or not to include the country name as the last line in FormattedAddress.
Option Name Parameter Description
CountryOfOrigin (Any valid ISO-3166-1 Alpha-2, ISO-3166-1 Alpha-3, or ISO-3166-1 Numeric code)
  • If blank, invalid, or the same as the destination country, then the destination country is not appended to the end of the formatted address.
  • If valid and different from the destination country, then the destination country is appended to the formatted address.
  • US or US Territory:
  • If CountryOfOrigin and destination country being verified are both US or US Territories then the country will not be appended to FormattedAddress.
  • US Territories will have "United States of America" appended if the CountryOfOrigin is not a US Territory, but the CountryName and ISO codes will be that of the territory.
  • Canada is treated like any other non-US Territory.


USPreferredCityNames

Allows you to override the city name and return only the USPS preferred city name.
Option Name Parameter Description
USPreferredCityNames ON If set to on, we will override and return only the USPS preferred city name.
OFF Default. Leave valid vanity city names as preferred by the USPS.


USStandardizationType

Allows you to specify the standardization of the address abbreviation.
Option Name Parameter Description
USStandardizationType Auto This uses the input as a guide for how to standardize.
Short Default. Leave the US address in short abbreviated form as preferred by the USPS. For example: 
100 W Main St East
Long Always spell the address out. For example: 
100 West Main Street East


DetailedResults

This is for users that have experience or code using Address Object and would like to have those codes alongside the Global Address result codes.
Option Name Parameter Description
DetailedResults ON For US and CA addresses only. This will return more detailed and different result codes that come from our Address Object product.
OFF Default. No extra result codes will be returned.


IncludeRemnant

Option Name Parameter Description
IncludeRemnant ON Default. In cases where Global Address identifies a piece of the input as extra information, we label this as Remnant and append it to the beginning of the address lines. This is because it is common to add additional delivery information like Care Of or Attention data, that may be useful and we do not want to throw away. The downside is that this information may not always be useful information, but that is not something we can always determine so we lean on the side of caution.
OFF By setting this option to false, we will no longer append the Remnant information anywhere in the address lines. This may be useful for users who identify that Remnant information in their data is mostly not useful.


ExtendedDateTime

Option Name Parameter Description
ExtendedDateTime ON Additional information related to time zone names and UTC information for both standard and daylight savings will be made available in the Extras section. Please see the Extras section for additional details.
OFF Default. No additional output information is provided.


USExtras

Option Name Parameter Description
USExtras ON Additional US only output will be made available in the Extras section. These outputs are related to Census, County, and School information. Please see the Extras section for additional details.
OFF Default. No additional output information is provided.


OriginDateTime (BETA)

Option Name Parameter Description
OriginDateTime (String) A string DateTime value with UTC data to use in the calculation of the local date time. This feature will allow you to convert the origin time into the local time at the output address. This calculation takes into account the different in UTC from the origin to the output address and also takes into account the dates that daylight savings is observed at the destination. Example: OriginDateTime:2022-01-13 18:33:16 (UTC-8:00). Note, we need the UTC value to know exactly where the origin time is from. If you do not specify a UTC value, we will assume UTC value of 0.


GBExtras

Allows you to choose to add the UPRN output.
Option Name Parameter Description
GBExtras ON Adds the additional output value of UPRN. Please see the Extras section for additional details.
OFF Default. No additional output information is provided.


Format

Optional.
The desired format of the response.
Protocol Syntax
REST &format = string
JSON (HTTP Header) Accept: application/json
SOAP/XML (HTTP Header) Accept: application/xml

Request Record Elements

JSON will only contain the Records element.

Protocol Definition
JSON Each email will be contained within [{}] under the Records element.
REST The REST interface only allows a single record per request.
SOAP This element is an array of object variables of the type RequestRecords.
XML There will be one RequestRecord element per address being submitted to the Cloud Service.


RecordID

Optional.
This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return the input.
Protocol Syntax
JSON "RecordID":"string"
SOAP/XML <RecordID>string</RecordID>


Organization

Optional.
The organization name associated with the address record.
Protocol Syntax
JSON "Organization":"string"
REST &org = string
SOAP/XML <Organization>string</Organization>


LastName

Optional.
US Only. For addresses missing a secondary like a suite or apartment, we can use the last name and append that information for residential addresses.
Protocol Syntax
JSON "LastName":"string"
REST &last = string
SOAP/XML <LastName>string</LastName>


AddressLine1

Required.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine1":"string"
REST &a1 = string
SOAP/XML <AddressLine1>string</AddressLine1>


AddressLine2

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine2":"string"
REST &a2 = string
SOAP/XML <AddressLine2>string</AddressLine2>


AddressLine3

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine3":"string"
REST &a3 = string
SOAP/XML <AddressLine3>string</AddressLine3>


AddressLine4

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine4":"string"
REST &a4 = string
SOAP/XML <AddressLine4>string</AddressLine4>


AddressLine5

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine5":"string"
REST &a5 = string
SOAP/XML <AddressLine5>string</AddressLine5>


AddressLine6

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine6":"string"
REST &a6 = string
SOAP/XML <AddressLine6>string</AddressLine6>


AddressLine7

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine7":"string"
REST &a7 = string
SOAP/XML <AddressLine7>string</AddressLine7>


AddressLine8

Optional.
The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.
Protocol Syntax
JSON "AddressLine8":"string"
REST &a8 = string
SOAP/XML <AddressLine8>string</AddressLine8>


DoubleDependentLocality

Optional.
The smallest population center data element. This depends on the Locality and DependentLocality elements.
Protocol Syntax
JSON "DoubleDependentLocality":"string"
REST &ddeploc = string
SOAP/XML <DoubleDependentLocality>string</DoubleDependentLocality>


DependentLocality

Optional.
The smaller population center data element. This depends on the Locality element.
US Term: Urbanization
In terms of US Addresses, this element applies only to Puerto Rican addresses. It is used to break ties when a ZIP Code™ is linked to multiple instances of the same address.
Protocol Syntax
JSON "DependentLocality":"string"
REST &deploc = string
SOAP/XML <DependentLocality>string</DependentLocality>


Locality

Required.
The most common population center data element.
US Term: City
Canada Term: Municipality
Protocol Syntax
JSON "Locality":"string"
REST &loc = string
SOAP/XML <Locality>string</Locality>


SubAdministrativeArea

Optional.
The smallest geographic data element.
US Term: County
Protocol Syntax
JSON "SubAdministrativeArea":"string"
REST &subadmarea = string
SOAP/XML <SubAdministrativeArea>string</SubAdministrativeArea>


AdministrativeArea

Required.
The most common geographic data element.
US Term: State
Canada Term: Province
Protocol Syntax
JSON "AdministrativeArea":"string"
REST &admarea = string
SOAP/XML <AdministrativeArea>string</AdministrativeArea>


PostalCode

Required.
The complete postal code for a particular delivery point.
US Term: ZIP
Canadian Term: Postcode
If all three elements are provided and the PostalCode is incorrect, it can be corrected from the data on the Locality and AdministrativeArea.
Protocol Syntax
JSON "PostalCode":"string"
REST &postal = string
SOAP/XML <PostalCode>string</PostalCode>


SubNationalArea

Optional.
The administrative region within a country on an arbitrary level below that of the sovereign state.
Protocol Syntax
JSON "SubNationalArea":"string"
REST &subnatarea = string
SOAP/XML <SubNationalArea>string</SubNationalArea>


Country

Required.
The country name, abbreviation, or code.
Protocol Syntax
JSON "Country":"string"
REST &ctry = string
SOAP/XML <Country>string</Country>
Retrieved from "http://wiki.melissadata.com/index.php?title=Global_Address_Verification:Request&oldid=18882"