Quickstart Guide

Global Express Entry

Introduction

Global Express Entry can be used to:

  • Complete free form partial address input with standardized and verified addresses
  • Return geocoding coordinates along with address (in supported countries)
  • Filter output by state, distance from a lat/long point, Residence or Business, or ZIP Code (U.S. only)

Basic Order of Operations

Global Endpoint

  • Put the partial address into REST parameter &ff=
  • Make sure to include your license key in &id=
  • Choose a format with &format=xml or &format=json
  • Set the maximum number of records to return with &maxrecords=
  • Set the parameter &Country= to the country desired
  • Send the request to the service URL:
  • Receive the result back from the service.

U.S. Endpoint

  • Put the partial address into REST parameter &ff=
  • Make sure to include your license key in &id=
  • Choose a format with &format=xml or &format=json
  • Set the maximum number of records to return with &maxrecords=
  • Send the request to the service URL:
  • Receive the result back from the service.

Sample code is provided if you would rather code to HTML/CSS/JavaScript/JQuery.

Input Request

NOTE: 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 "https://expressentry.melissadata.net/web/GlobalExpressFreeForm?ff=22382+Avenida&format=xml&id=&maxrecords=10&country=US"

You will have to replace the fields surrounded by < > to generate a result.

You can also put the URL without the url -X GET command directly into your browser. This service will return either XML, JSON, or JSONP results.

Input Fields

Global

Input Name REST Input Description REQUIRED
Customer ID id The License Key issued by Melissa. YES
Free Form Input ff The Free-Form partial address to complete YES
Maximum Records to Return maxrecords Maximum number of records for the service to return YES
Output Format format Return the response in XML or JSON YES
Country to Search country The country to search for the address in YES
Options opt=poboxes:true Return P.O. Boxes (US Only) NO
Columns cols=gbextras
cols=results 		Return UPRN and UDPRN (GB only)
Return Address Object Result Codes for each address in the Extras field (US Only) 		NO
NO

U.S.

Input Name REST Input Description REQUIRED
Customer ID id The License Key issued by Melissa. YES
Free Form Input ff The Free-Form partial address to complete in the U.S. YES
Maximum Records to Return maxrecords Maximum number of records for the service to return YES
Output Format format Return the response in XML or JSON YES
Options opt=poboxes:true Return P.O. Boxes NO
Columns cols=results Return Address Object Result Codes NO

Input Best Practices

Generally, around 7-10 keystrokes from the beginning of an address are required to uniquely identify and complete the address using Free Form input.

The sample JavaScript/JQuery code throttles the input for less friction in your User Experience.

Set the maxrecords parameter according to the number of results that you want to see in the pick list appearing below the input box. This encourages your User to keep typing in order to find the address they are looking for, and adds ‘tactile feedback’ to your web site or application.

Output Response

Real Time

Here is a generic JSON response of the real time Global REST request from above.

{
    "Version": "String",
    "ResultCode": "String",
    "ErrorString": "String",
    "Results": [{
      "Address": {
        "Address": "String",
        "Address1": "String",
        "Address2": "String",
        "Address3": "String",
        "Address4": "String",
        "Address5": "String",
        "Address6": "String",
        "Address7": "String",
        "Address8": "String",
        "Address9": "String",,
        "Address10": "String",
        "Address11": "String",
        "Address12": "String",
        "DeliveryAddress": "String",
        "DeliveryAddress1": "String",
        "DeliveryAddress2": "String",
        "DeliveryAddress3": "String",
        "DeliveryAddress4": "String",
        "DeliveryAddress5": "String",
        "DeliveryAddress6": "String",
        "DeliveryAddress7": "String",
        "DeliveryAddress8": "String",
        "DeliveryAddress9": "String",
        "DeliveryAddress10": "String",
        "DeliveryAddress11": "String",
        "DeliveryAddress12": "String",
        "CountryName": "String",
        "ISO3166_2": "String",
        "ISO3166_3": "String",
        "ISO3166_N": "String",
        "SuperAdministrativeArea": "String",
        "AdministrativeArea": "String",
        "SubAdministrativeArea": "String",
        "Locality": "String",
        "DependentLocality": "String",
        "DoubleDependentLocality": "String",
        "Thoroughfare": "String",
        "DependentThoroughfare": "String",
        "Building": "String",
        "Premise": "String",
        "SubBuilding": "String",
        "PostalCode": "String",
        "PostalCodePrimary": "String",
        "PostalCodeSecondary": "String",
        "Organization": "String",
        "PostBox": "String",
        "Unmatched": "String",
        "GeneralDelivery": "String",
        "DeliveryInstallation": "String",
        "Route": "String",
        "AdditionalContent": "String",
        "CountrySubdivisionCode": "String",
        "MAK": "String",
        "BaseMAK": "String",
        "Latitude": "String",
        "Longitude": "String",
        "DistanceFromPoint": String
      }
    }]
  }

Output Fields

Global Response (Base Level)

Output Name Description
Version The current revision number of Global Express Entry
ResultCode The Result Code indicating whether the complete, partial, or null set was returned
ErrorString The Error String returned with the response

Global Record Level

Output Name Description
Address The full formatted address
Address1 The first line of the address returned
Address2 The second line of the address returned
Address3 The third line of the address returned
Address4 The fourth line of the address returned
Address5 The fifth line of the address returned
Address6 The sixth line of the address returned
Address7 The seventh line of the address returned
Address8 The eighth line of the address returned
Address9 The ninth line of the address returned
Address10 The tenth line of the address retuned
Address11 The eleventh line of the address returned
Address12 The twelfth line of the address returned
DeliveryAddress The address without locality and postal code hierarchies
DeliveryAddress1 The first line of the delivery address returned
DeliveryAddress2 The second line of the delivery address returned
DeliveryAddress3 The third line of the delivery address returned
DeliveryAddress4 The fourth line of the delivery address returned
DeliveryAddress5 The fifth line of the delivery address returned
DeliveryAddress6 The sixth line of the delivery address returned
DeliveryAddress7 The seventh line of the delivery address returned
DeliveryAddress8 The eighth line of the delivery address returned
DeliveryAddress9 The ninth line of the delivery address returned
DeliveryAddress10 The tenth line of the delivery address retuned
DeliveryAddress11 The eleventh line of the delivery address returned
DeliveryAddress12 The twelfth line of the delivery address returned
CountryName The name of the country
ISO3166_2 The two character ISO code for the country
ISO3166_3 The three character ISO code for the country
ISO3166_N The three digit ISO number of the country
SuperAdministrativeArea The Region of the address returned
AdministrativeArea The Administrative Area of the address returned
SubAdministrativeArea The SubAdministrative area of the address returned
Locality The most common area value, also known as City or Canton
DependentLocality The area smaller than locality (if necessary for the mailing address)
DoubleDependentLocality The area smaller than dependent locality (if necessary for the mailing address)
Thoroughfare The full named street that corresponds to the address
DependentThoroughfare A second throughfare associated with the address
Building The name of the building attached to the address
Premise The house number of the address
SubBuilding The subdivided information within a single premise like suite or apartment
PostalCode The full postal code
PostalCodePrimary The primary postal code
PostalCodeSecondary The secondary postal code
Organization The organization at the address (where available)
PostBox The post office box value if it exists
Unmatched Unmatched input (currently not used)
GeneralDelivery The General Delivery for the address
DeliveryInstallation The DeliveryInstallation for the address
Route The Route information for the address
AdditionalContent Additonal content for the address
CountrySubdivisionCode The ISO 3166-2 Subdivision Code for the address
MAK The Melissa Address Key for the address
BaseMAK The Base Melissa Address Key for the address
Latitude The latitude of the output address
Longitude The longitude of the output address
DistanceFromPoint The distance from the point given in the filtering input (Select Countries Only)

U.S. Response (Base Level)

Output Name Description
Version The current revision number of Global Express Entry
ResultCode The Result Code indicating whether the complete, partial, or null set was returned
ErrorString The Error String returned with the response

U.S. Record Level

Output Name Description
AddressLine1 Address Line 1 for the address
City The City for the address
CityAccepted USPS Accepted Vanity City Names for the Address
CityNotAccepted Non-accepted vanity City Names for the address
State State the address is in
PostalCode PostalCode of the address
CountrySubdivisionCode The ISO 3166-2 Subdivision Code for the address
AddressKey The address key of the address
SuiteName The type of suite of the address if present
SuiteCount The number or suites at the address
SuiteList The array of suite or apartment numbers at the address
PlusFour The array of plus4's corresponding to the suite numbers at the address
MAK The Melissa Address Key for the address
BaseMAK The Base Melissa Address Key for the address.

Interpreting Results

Global Express Entry Free Form returns 3 result codes to indicate whether the set of addresses in the output is complete, if the User should narrow down the results by adding more characters, or if there was no match for the partial address given as input.

Code Description Recommendation
XS01 Complete result set returned Good
XS02 Partial result set returned Increase maxrecords in web page or have the user enter more keystrokes
XS03 No results returned Have the user correct the input

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 at Global Express Entry Result Code Details.