Global Address

Upcoming Major Update

Melissa is preparing for a major update to our Global Address Web Service. With this major update, we are introducing a number of new fields and options. We believe these new additional bring a major benefit for users of the service and we encourage everyone to review these new items and plan to incorporate them into your application.

Is this new version backwards compatible?

This new version is completely backwards compatible. We have not removed or renamed any existing inputs or outputs. We have only added additional inputs and outputs as well as options.

If this version is backwards compatible, why are you staging the roll-out?

In the past, we have seen some clients have issues with any change to our service, even backwards compatible ones like this one, particularly with Java applications. Out of an abundance of caution, we want to give everyone time to test and confirm so there are no service interruptions for any clients.

Update Process and Timeline:

  1. Release of BETA version on new URL

    2. We have already released the BETA version of the new version of the service on these URL’s:

    SOAP:

    https://globaladdress-beta.melissadata.net/v3/SOAP/GlobalAddress

    XML/REST/JSON:

    https://globaladdress-beta.melissadata.net/v3/WEB/GlobalAddress/doGlobalAddress
  2. Clients will test and make sure this new service does not cause any issues with their application.
  3. On September 7th, 2020, we will update the regular Global Address with this new version.
  4. On September 30th, 2020, we will disable the BETA URL.

New Input Fields:

Input Name Description
LastName This field has been added to allow the use of a Melissa proprietary database. For addresses missing a secondary like a suite or apartment, we can use the last name and append that information for residential addresses. This feature is only available for the US.

New Output Fields:

Input Name Description
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
US This returns the 2 digit delivery point assigned by the USPS to an DPV validated address.
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 See below.

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.

<Extras>
    <root>
        <extra>
            <key>CBSACode</key>
            <value>31080</value>
        </extra>
        <extra>
            <key>CBSADivisionCode</key>
            <value>11244</value>
        </extra>
        <extra>
            <key>CBSADivisionLevel</key>
            <value>Metropolitan Statistical Area</value>
        </extra>
    </root>
</Extras>

Here are the possible output and groups:

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

AddressKey

This is a country dependent field. We have added Great Britain as a country that will return a value for this 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.

AddressTypeCode

This is a country dependent field. We have added Great Britain as a country that will return a value for this field.

US
Code Description
A Alias address
F Firm or Company
G General Delivery
H Highrise or Business Complex
P PO Box
R Rural Route
S Street or Residential
CA
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
GB
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.
Last Updated 07/07/2020

Here are new options that allow the user additional control over the output of US or CA addresses.

USPreferredCityNames

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.

USStandardizationType

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

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.

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.
Last Updated 09/14/2020