Quickstart Guide

Global Address

Global Address can be used to:

  • Verify, Correct, & Standardize addresses from 240+ countries & territories
  • Append latitude & longitude
  • Return address as parsed components
  • Return address in mailing label format according to the standards of each country
  • Append additional information like unique identifier, delivery indicator, & more depending on the country.
Last Updated 10/10/2019

Real Time

Batch

  • Put the input request together using JSON or XML. Put up to 100 records into the request array.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default. They will apply to all records in the request.
  • Make sure to specify the same options for all records in the batch to maintain consistency.
  • Send the full request to the service URL: https://address.melissadata.net/v3/WEB/GlobalAddress/doGlobalAddress using HTTP POST
  • Receive the result back for all addresses from the input
Last Updated 02/06/2020

NOTE: This service deals with multiple languages and scripts. It expects UTF-8 character encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

curl -X GET http://address.melissadata.net/V3/WEB/GlobalAddress/doGlobalAddress?id=LICENSE_KEY&a1=22382 Avenida Empresa&loc=Rancho Santa Margarita&admarea=CA&postal=92688&ctry=US&format=JSON

You can also put the URL without the "curl -X GET" command directly into your browser. You can also toggle between getting XML or JSON back using the format input parameter. As you can see, in this example, we are asking for JSON back.

Batch

Batch requests from 1 to 100 records at a time are sent using HTTP POST. This means you cannot send it in a browser like with HTTP GET.

Header

Accept: application/json

Make sure the header includes this line:

Body

{
  "TransmissionReference":"JSON BATCH TEST",
  "CustomerID":"LICENSE KEY",
  "Options":"",
  "Records":[{
    "RecordID":"1",
    "Organization":"",
    "AddressLine1":"22382 Avenida Empresa",
    "AddressLine2":"",
    "AddressLine3":"",
    "AddressLine4":"",
    "AddressLine5":"",
    "AddressLine6":"",
    "AddressLine7":"",
    "AddressLine8":"",
    "DoubleDependentLocality":"",
    "DependentLocality":"",
    "Locality":"CA",
    "SubAdministrativeArea":"",
    "AdministrativeArea":"",
    "PostalCode":"92688",
    "SubNationalArea":"",
    "Country":"US"
  },
  {
    "RecordID":"2",
    "Organization":"",
    "AddressLine1":"61 Rue de Douai",
    "AddressLine2":"75009 Paris",
    "AddressLine3":"",
    "AddressLine4":"",
    "AddressLine5":"",
    "AddressLine6":"",
    "AddressLine7":"",
    "AddressLine8":"",
    "DoubleDependentLocality":"",
    "DependentLocality":"",
    "Locality":"",
    "SubAdministrativeArea":"",
    "AdministrativeArea":"",
    "PostalCode":"",
    "SubNationalArea":"",
    "Country":"FR"
  }]
}

Here, we are sending a batch request with 2 records.

Last Updated 10/10/2019
Batch Input Name REST Input Description REQUIRED
TransmissionReference t Value passed through unchanged to the response for identification or any other purpose No
CustomerID id The License Key issued by Melissa Yes
Options opt Delivery Lines
Code Description
On Only Put Delivery Address into the address lines and move all area information into their parsed fields.
Off (Default) Put the full address into the Address lines.
OutputScript
Code Description
NOCHANGE Leave the output in the same script as the input.
LATN Return output in Latin Script.
NATIVE Return output in the script of the native language of the country.
RecordID Batch Only. Used as a unique identifier for each individual address record No
Organization org The Input Organization No
AddressLine1 a1 The Input Address Line 1 Yes
AddressLine2 a2 The Input Address Line 2 No
AddressLine3 a3 The Input Address Line 3 No
AddressLine4 a4 The Input Address Line 4 No
AddressLine5 a5 The Input Address Line 5 No
AddressLine6 a6 The Input Address Line 6 No
AddressLine7 a7 The Input Address Line 7 No
AddressLine8 a8 The Input Address Line 8 No
DependentLocality deploc The Input Dependent Locality (Like an district or suburb that is an official part of the address. Rarely used) No
DoubleDependentLocality ddeploc The Input Double Dependent Locality (An area even smaller than dependent locality but larger than the thoroughfare that is an official part of the address. Very rarely used) No
Locality loc The Input Locality (Also called City, Canton, etc. The most common area name for almost all countries) No
SubAdministrativeArea subadmarea The Input SubAdministrative Area (An area that is bigger than the locality but smaller than the Administrative Area that is an official part of the address. Very rarely used) No
AdministrativeArea admarea The Input Administrative Area (Also common called State, Municipality, etc. Common in larger countries) No
SubNationalArea subnatarea The Input Sub National Area (Area larger than Administrative Area but not the whole country. Very rarely used as part of the address) No
PostalCode postal The Input Postal Code No
Country ctry The Country ISO2, ISO3, or spelled out name Yes
Last Updated 10/10/2019

Most organizations are somewhat limited in how much control they have over how users enter addresses. Here are some best practices to get the most of the service and to avoid possible issues.

Address Format

The service is designed for full addresses. In most cases, this means a house number, a thoroughfare (street name), a subpremise if present (like an apartment or suite), a locality, an administrative area if used, a postal code if used, and the country. Some countries may have other common inputs but the main concept is that of a full address. If you have input that is not a full address (like just a cross section, a point of interest, or just an area), do not expect a full verification. Also, if you have an address with non-address information (like descriptors/directions such as "turn left the river"), the likelihood of a correct verification drops significantly.

Try not to have repeated information in the input.

The address may be fully entered in the address lines:

AddressLine1=22382 Avenida Empresa
AddressLine2=Rancho Santa Margarita, CA 92688
Country=US

Or as parsed inputs:

AddressLine1=22382 Avenida Empresa
Locality=Rancho Santa Margarita
AdministrativeArea=CA
PostalCode=92688
Country=US

Our recommendation is to use the format that you have. If you have the fields parsed out already, used the parsed input fields and do not combine them to use just the address lines.

Handling Scripts and Languages

Global Address Web Service has the ability to change from one script to another using the OutputScript option. This is not to be confused with language, as multiple languages can belong to the same script. For example, both English and Spanish belong to the Latin script. The scripts that we currently support are:

  1. Latin
  2. Cyrillic
  3. Greek
  4. Hebrew
  5. Kanji
  6. Chinese
  7. Arabic
  8. Thai
  9. Hangul

By setting the OutputScript to Native, we will always return the script of the native language of that country. Setting it to Latn will return it in latin. While those are available to use, we actually recommend using the NoChange option which will keep the output in the same script as the input. This is recommended because, in our experience, the input is in a particular script for a reason. Our main method of conversion is to use transliteration: a phonetic conversion keeping the sound of the word as close as possible to the original. This usually means some meaning or intention from the input is lost when doing that. To maintain the input integrity as much as possible, it is best to keep it in the script it came in as.

Last Updated 10/20/2019

Real Time

Here is a response of the real time request above.

<Response xmlns="urn:mdGlobalAddress" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Version>3.0.1.150</Version>
  <TransmissionReference/>
  <TransmissionResults/>
  <TotalRecords>1</TotalRecords>
  <Records>
    <ResponseRecord>
    <RecordID>1</RecordID>
    <Results>AC16,AV24,GS05</Results>
    <FormattedAddress>22382 Avenida Empresa;Rancho Santa Margarita, CA 92688-2112</FormattedAddress>
    <Organization/>
    <AddressLine1>22382 Avenida Empresa</AddressLine1>
    <AddressLine2>Rancho Santa Margarita, CA 92688-2112</AddressLine2>
    <AddressLine3/>
    <AddressLine4/>
    <AddressLine5/>
    <AddressLine6/>
    <AddressLine7/>
    <AddressLine8/>
    <SubPremises/>
    <DoubleDependentLocality/>
    <DependentLocality/>
    <Locality>Rancho Santa Margarita</Locality>
    <SubAdministrativeArea>Orange</SubAdministrativeArea>
    <AdministrativeArea>CA</AdministrativeArea>
    <PostalCode>92688-2112</PostalCode>
    <AddressType>S</AddressType>
    <AddressKey>92688211282</AddressKey>
    <SubNationalArea/>
    <CountryName>United States of America</CountryName>
    <CountryISO3166_1_Alpha2>US</CountryISO3166_1_Alpha2>
    <CountryISO3166_1_Alpha3>USA</CountryISO3166_1_Alpha3>
    <CountryISO3166_1_Numeric>840</CountryISO3166_1_Numeric>
    <CountrySubdivisionCode>US-CA</CountrySubdivisionCode>
    <Thoroughfare>Avenida Empresa</Thoroughfare>
    <ThoroughfarePreDirection/>
    <ThoroughfareLeadingType/>
    <ThoroughfareName>Avenida Empresa</ThoroughfareName>
    <ThoroughfareTrailingType/>
    <ThoroughfarePostDirection/>
    <DependentThoroughfare/>
    <DependentThoroughfarePreDirection/>
    <DependentThoroughfareLeadingType/>
    <DependentThoroughfareName/>
    <DependentThoroughfareTrailingType/>
    <DependentThoroughfarePostDirection/>
    <Building/>
    <PremisesType/>
    <PremisesNumber>22382</PremisesNumber>
    <SubPremisesType/>
    <SubPremisesNumber/>
    <PostBox/>
    <Latitude>33.637572</Latitude>
    <Longitude>-117.606868</Longitude>
    </ResponseRecord>
  </Records>
</Response>

Batch

Here is the response from the sample batch request.

{
  "Version": "3.0.1.150",
  "TransmissionReference": "JSON BATCH TEST",
  "TransmissionResults": "",
  "TotalRecords": "2",
  "Records": [{
    "RecordID": "1",
    "Results": "AC02,AC03,AC16,AV24,GS05",
    "FormattedAddress": "22382 Avenida Empresa;Rancho Santa Margarita, CA 92688-2112",
    "Organization": "",
    "AddressLine1": "22382 Avenida Empresa",
    "AddressLine2": "Rancho Santa Margarita, CA 92688-2112",
    "AddressLine3": "",
    "AddressLine4": "",
    "AddressLine5": "",
    "AddressLine6": "",
    "AddressLine7": "",
    "AddressLine8": "",
    "SubPremises": "",
    "DoubleDependentLocality": "",
    "DependentLocality": "",
    "Locality": "Rancho Santa Margarita",
    "SubAdministrativeArea": "Orange",
    "AdministrativeArea": "CA",
    "PostalCode": "92688-2112",
    "AddressType": "S",
    "AddressKey": "92688211282",
    "SubNationalArea": "",
    "CountryName": "United States of America",
    "CountryISO3166_1_Alpha2": "US",
    "CountryISO3166_1_Alpha3": "USA",
    "CountryISO3166_1_Numeric": "840",
    "CountrySubdivisionCode": "US-CA",
    "Thoroughfare": "Avenida Empresa",
    "ThoroughfarePreDirection": "",
    "ThoroughfareLeadingType": "",
    "ThoroughfareName": "Avenida Empresa",
    "ThoroughfareTrailingType": "",
    "ThoroughfarePostDirection": "",
    "DependentThoroughfare": "",
    "DependentThoroughfarePreDirection": "",
    "DependentThoroughfareLeadingType": "",
    "DependentThoroughfareName": "",
    "DependentThoroughfareTrailingType": "",
    "DependentThoroughfarePostDirection": "",
    "Building": "",
    "PremisesType": "",
    "PremisesNumber": "22382",
    "SubPremisesType": "",
    "SubPremisesNumber": "",
    "PostBox": "",
    "Latitude": "33.637572",
    "Longitude": "-117.606868"
  },
  {
    "RecordID": "2",
    "Results": "AC02,AC09,AC16,AC17,AV24,GS05",
    "FormattedAddress": "61 RUE DE DOUAI;9E ARRONDISSEMENT;75009 PARIS;FRANCE",
    "Organization": "",
    "AddressLine1": "61 Rue de Douai",
    "AddressLine2": "9E Arrondissement",
    "AddressLine3": "75009 Paris",
    "AddressLine4": "",
    "AddressLine5": "",
    "AddressLine6": "",
    "AddressLine7": "",
    "AddressLine8": "",
    "SubPremises": "",
    "DoubleDependentLocality": "",
    "DependentLocality": "9E Arrondissement",
    "Locality": "Paris",
    "SubAdministrativeArea": "Paris",
    "AdministrativeArea": "Paris",
    "PostalCode": "75009",
    "AddressType": "",
    "AddressKey": "",
    "SubNationalArea": "Paris",
    "CountryName": "France",
    "CountryISO3166_1_Alpha2": "FR",
    "CountryISO3166_1_Alpha3": "FRA",
    "CountryISO3166_1_Numeric": "250",
    "CountrySubdivisionCode": "FR-75",
    "Thoroughfare": "Rue de Douai",
    "ThoroughfarePreDirection": "",
    "ThoroughfareLeadingType": "Rue de",
    "ThoroughfareName": "Douai",
    "ThoroughfareTrailingType": "",
    "ThoroughfarePostDirection": "",
    "DependentThoroughfare": "",
    "DependentThoroughfarePreDirection": "",
    "DependentThoroughfareLeadingType": "",
    "DependentThoroughfareName": "",
    "DependentThoroughfareTrailingType": "",
    "DependentThoroughfarePostDirection": "",
    "Building": "",
    "PremisesType": "",
    "PremisesNumber": "61",
    "SubPremisesType": "",
    "SubPremisesNumber": "",
    "PostBox": "",
    "Latitude": "48.8836040366693",
    "Longitude": "2.32918780839551"
  }]
}
Last Updated 10/10/2019

Response Level

Output Name Description
Version The current revision number of Global Address.
TransmissionReference Returned value will be the same as the input TransmissionReference to be used as a unique identifier.
Total Records The total number of records returned.
TransmissionResults Service Errors (SE Codes) and General Transmission Errors (GE Codes)
Results Shows you the result of the address verification with codes for status, error, and changes. See the Results section below for more details.

Record Level

Output Name Description
Latitude The Latitude of the output address
Longitude The Longitude of the output address
CountryName The official name of the country
CountryISO3166_1_Alpha2 The official ISO 3166 2 character code of the country
CountryISO3166_1_Alpha3 The official ISO 3166 3 character code of the country
CountryISO3166_1_Numeric The official ISO 3166 number of the country
CountrySubdivisionCode The ISO 3166-2 Subdivisioncode value for the address
AddressType The type of the address. Currently only available for the US.
Code Description
A Alias
F Firm or Company
G General Delivery
H Highrise or Business Complex
P PO Box
R Rural Route
S Street or Residential
AddressKey A identification value for the US making up the postal code, Plus4, and delivery point.
Output Group 1: The full address as a mailing label
FormattedAddress This is the Mailing Label version of the address with all pieces included in the format for the country.
Output Group 2: The full address in database format
Organization The organization tied to the address. Will use the input organization if one if one from the database is not available for override.
AddressLine1 The first line of the address in database format.
AddressLine2 The second line of the address in database format.
AddressLine3 The third line of the address in database format.
AddressLine4 The fourth line of the address in database format.
AddressLine5 The fifth line of the address in database format.
AddressLine6 The sixth line of the address in database format.
AddressLine7 The seventh line of the address in database format.
AddressLine8 The eighth line of the address in database format.
Output Group 3: The output as parsed fields
SubPremises The subdivided information within a single house number like a suite or apartment.
SubPremisesType The type value of the SubPremises. Ex: Suite
SubPremisesNumber The number value of the SubPremises. Ex: 10A
Building The name of the building attached to the address.
PremisesType The house number type of the address. Ex: No. (Rarely used)
PremisesNumber The house number value of the address
Locality The most common area value, also known as city or canton.
Thoroughfare The full named street that correspond to the address. This value includes the Pre Direction, Leading Type, Name, Trailing Type, and Post Direction.
ThoroughfarePreDirection The directional that preceeds the thoroughfare name. Ex: North
ThoroughfareLeadingType The street type of the thoroughfare that preceeds the thoroughfare name. EX: Rue de
ThoroughfareName The main name of the thoroughfare. Ex: Main
ThoroughfareTrailingType The street type of the thoroughfare that comes after the thoroughfare name. EX: Blvd
ThoroughfarePostDirection The directional that comes after the thoroughfare name. Ex: South
DependentThoroughfare A second (usually smaller) thoroughfare value attached to the address if necessary.
DependentThoroughfarePreDirection The predirection of the dependent thoroughfare
DependentThoroughfareLeadingType The leading type of the dependent thoroughfare
DependentThoroughfareName The name of the dependent thoroughfare
DependentThoroughfareTrailingType The trailing type of the dependent thoroughfare
DependentThoroughfarePostDirection The post direction of the dependent thoroughfare
DependentLocality Dependent Locality is the area smaller than the locality but bigger than the thoroughfare. Rarely used.
DoubleDependentLocality Double Dependent Locality is the area smaller than a dependent locality but bigger than a thoroughfare. Very rarely used.
SubAdministrativeArea The area smaller than an Administrative Area but bigger than a city (like a county). Often used in larger countries but rarely included as part of an official address.
AdministrativeArea The common administrative division larger than locality, also called State, Municipality…)
PostalCode The postal code
SubNationalArea The area larger than administrative area but smaller than the nation. Rarely used.
PostBox The post office box value if it exists
Last Updated 10/10/2019

The Results field returned back by the service will tell all the status, error and change information about the output address returned back to you. The results are split into four main categories:

AV Codes

  • AV2X denotes an address that has been verified to the highest possible level with the reference data.
  • AV1X denotes a partially verified address, but NOT to the highest level possible with the reference data.
  • The second number indicates the level of verification. There are five levels:

AE Codes

These are error codes that will tell you what type of error we encountered.

AC Codes

These are change codes that will tell you which address pieces we changed from the input to the output. They include field that were blank in the input and added in the output.

GS & GE Codes

For the users who get geocoding information, this will tell you to what precision level the latitude and longitude appended are.

Using Result Codes Programmatically

The concept behind the result codes are that the service will include a full list of delimited result codes, many of which may not be important to you. As a user, you should decide what codes define a good address for you and use a string.Contains search to look for those codes. If you find it, you have a good address. If you don't, then you have a bad address. You can also cascade them into 3 or more condition layers. Here is a common example:

Result Code Web Service Error

If(Results.Contains("AV23") or Results.Contains("AV24") or Results.Contains("AV25"))
    { /*Handle Good Address*/ }
Else if(Results.Contains("AV22") or Results.Contains("AV14") or Results.Contains("AV13"))
    { /*Handle Suspect Address*/ }
Else
    { /*Handle Bad Address*/ }
Code Description Recommendation
AV25 Full Verification to SubPremise Good
AV24 Full Verification to House Number Good
AV23 Full Verification to Thoroughfare. House Number data not available. Good
AV22 Full Verification to Locality. Medium. Only locality data was available, odds on quality is dependent on source of input.
AV14 Address Verified to the House Number. Issue found with SubPremise. Medium. Most of the address was good, just bad/missing suite.
AV13 Address Verified to the Thoroughfare. Issue found with House Number. Medium. Most of the address was good, house number not verified.
AV12 Address Verified to the Locality. Could not verify any delivery address data. Bad. Could not verify the address but found a good locality value.
AV11 Address Verified to the Administrative Area only. Bad. Could not verify the address but found a good administrative area value.

Common Transmission Errors

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page here.

Last Updated 10/10/2019