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


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


Accept: application/json

Make sure the header includes this line:


  "TransmissionReference":"JSON BATCH TEST",
  "CustomerID":"LICENSE KEY",
    "AddressLine1":"22382 Avenida Empresa",
    "AddressLine1":"61 Rue de Douai",
    "AddressLine2":"75009 Paris",

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

Last Updated 09/14/2020
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.
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.
Code Description
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.
Code Description
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
Code Description
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.
RecordID Batch Only. Used as a unique identifier for each individual address record No
Organization org The Input Organization No
LastName last US Only. For addresses missing secondary information we can use the last name to append more information for residential addresses. 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 09/14/2020

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

Or as parsed inputs:

AddressLine1=22382 Avenida Empresa
Locality=Rancho Santa Margarita

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">
    <FormattedAddress>22382 Avenida Empresa;Rancho Santa Margarita, CA 92688-2112</FormattedAddress>
    <AddressLine1>22382 Avenida Empresa</AddressLine1>
    <AddressLine2>Rancho Santa Margarita, CA 92688-2112</AddressLine2>
    <Locality>Rancho Santa Margarita</Locality>
    <CountryName>United States of America</CountryName>
    <Thoroughfare>Avenida Empresa</Thoroughfare>
    <ThoroughfareName>Avenida Empresa</ThoroughfareName>


Here is the response from the sample batch request.

  "Version": "",
  "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

The type of address.

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
Code Description
1 Street
2 Street Served by Route and General Delivery
3 Lock Box
4 Route Service
5 General Delivery
B Large Volume Receiver Street
C Government Street
D Large Volume Receiver Lock Box
E Government Lock Box
L Large Volume Receiver General Delivery
K Building
Code Description
L This address is identified as having a large user postal code. This is due to the large volume of mail received at that address, or because a PO Box or Selectapost service has been set up.
S This address is identified as having a smaller user postal code. This means this postal code will have usually around 15 delivery points but never more than 100.
AddressKey Country dependent field.
  • US: This returns a 11 digit code representing the combination of the zip code, the plus4, and the delivery point. This is a fairly good representation of a unique US address and often used as the core of postal barcode. However, this code is not guaranteed to be unique to an individual address, please use the MelissaAddressKey instead for that purpose. It is possible that this field is empty or not 11 digits if the address is a Non-USPS address (link to something about non-usps addresses).
  • GB: This field returns the UDPRN, which stands for Unique Delivery Point Reference Number. It is an 8 character code that is assigned and maintained by Royal Mail to each delivery point address.
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
MelissaAddressKey This is a globally unique and persistent key for the location, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary key for the address. With AddressKey (US and Canada only), if an address zip code changes, the AddressKey would also change. Melissa Address Key (MAK) is independent and will not change. This makes MAK a good way to permanently identify and locate addresses. Once you have a MAK it can be used as an input in most Melissa services and thus is a good tool for deduping. Currently available for US, CA, GB, IT, SI, and PT with many more countries planned for the future.
MelissaAddressKeyBase Every full address has its own Melissa Address Key (MAK). If that address is a suites or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. This provides a link between all the individual MAK addresses that belong to the same building. This field also returns a 10-digit proprietary key. Note, if we can validate the address to the building but not the suite, we can return just the BaseMAK. Currently available for countries that have support for MelissaAddressKey.
DeliveryIndicator This field returns a one character code that indicates if the address is a residence (R), business (B), or unknown (U). It is not available for all countries. Currently, it is available only for the US but more countries are planned for future inclusion.
DeliveryPointSuffix This is a country dependent field. This field returns an identifier that represents asuffix code usually tied to a delivery point.
Code Description
GB This is a 2 character (first is numerical, 2nd character is alphabetic) that is assigned by Royal Mail. When added to the postal code, this allows each live delivery point to be uniquely identified.
PostalCodeType This is a country dependent field. This field returns an identifier that represents the type of postal code returned. Currently only the US uses this field.
Code Description
P PO Box Postal Code
U Unique Postal Code usually assigned to a large organization or government institution.
M Military Postal Code
Empty Regular postal code
PostOfficeLocation This field, if available for a country, returns the value that is associated to the location of the post office in relation to the address. This value may or may not be used in the official mailing address for the country in question. Currently, these are the countries we will return the data for: Serbia and Slovakia.
Country Description
Serbia The PostOfficeLocation contains the old 5 digit postal number and name. The postal code field will contain the new 6 digit PAK number.
Slovakia The PostOfficeLocation retuns the name of the post office location if it is not the same as the delivery address locality.
SubPremiseLevel This is a secondary piece of subpremise information used to describe a more generic division of the subpremise. For example, if you have an address like “1123 Market Way, Floor 12 Apt 25A” then the Subpremises will be “Apt 25A” and the SubPremiseLevel will be “Floor 12”. This value is not widely used in official address data.

SubPremiseLevelType and SubPremiseLevelNumber make up the SubPremiseLevel. In our example, the SubPremiseLevelType is “Floor” and the SubPremiseLevelNumber is “12”.
SubBuilding This value describes a smaller division of the building. For example, if an address has a building name that is a part of a larger set of buildings, then the subbuilding may be populated.

SubBuildingType and SubBuildingNumber make up the parts of SubBuilding.
UTC Returns the Coordinated Universal Time number in format of UTC+#. Note that there are timezones that are not whole hours only, like UTC+9:30.
DST Returns a Y or a N based on if the country or area of the input observes daylight savings time. Note that the value returned by the UTC output does not change based on whether the country/area is currently in daylight savings time for not. We will only return the standard timezone and this flag to indicate is daylight savings is observed.
CensusKey This is a country dependent field. It is designed to return a code that correspond to the census division information for a country. Currently, this field is only returned for the US.

US: The CensusKey for the US is a 15 or 16 digit code that is made up of the following components: FIPS Code, Census Tract, Census Block, and CensusBlockGroup if it exists
Extras This element is usually not populated but is reserved to be able to return less used fields if the user requests. Currently, we are using this to return some US only fields.
If you specify USExtras:ON in the request options, we can return additional outputs. These outputs are presented in a different format. They will look like this below.
            <value>Metropolitan Statistical Area</value>


Output Name Description
CBSA Outputs Core-Based Statistical Areas (CBSA) outputs. These values are assigned by the US Census.
  • CBSACode
  • CBSADivisionCode
  • CBSADivisionLevel
  • CBSADivisionTitle
  • CBSALevel
  • CBSATitle
CarrierRoute Carrier Route Code assigned by the USPS
CensusBlock The Census block number from the most recent yearly census
CensusTract The Census tract number from the most recent yearly census
CongressionalDistrict The congressional district number for the address
CountyFIPS The Census FIPS number from the most recent yearly census
CountyName The county name that corresponds to the county FIPS code
CountySubdivisionCode The county subdivision code value as defined by the US Census
CountySubdivisionName The county subdivision name value as defined by the US Census
DeliveryPointCheckDigit The single digit value that acts as a checksum to the delivery point code
DeliveryPointCode The 2 digit delivery point code as assigned by the USPS
ElementarySchoolDistrictCode Returns a 5 digit string representing the elementary school district code for the address
ElementarySchoolDistrictName Returns a 5 digit string representing the elementary school district code for the address
PlaceCode The FIPS Place code as defined by the Census
PlaceName The FIPS Place name as defined by the Census
SecondarySchoolDistrictCode The secondary school district code for the address
SecondarySchoolDistrictName The secondary school district name for the address
StateDistrictLower Returns a 3 digit string representing the Lower State District Code for the requested record
StateDistrictUpper Returns a 3 digit string representing the Upper State District Code for the requested record
UnifiedSchoolDistrictCode Returns a 5 digit string representing the Unified School District Code if the address is in a unified school district
UnifiedSchoolDistrictNameString Returns a 5 digit string representing the Unified School District Name if the address is in a unified school district
Last Updated 09/14/2020

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*/ }
    { /*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