Express Entry:Global Getting Started

← Global Express Entry

Using Express Entry Global

Express Entry Global is a REST (Representational State Transfer) based Web service that can be used to easily auto-populate address fields with verified address data. The REST query is made up of five elements: The base URI, the license or token string with the ‘id’ keyword, the maximum number of matches with ‘maxrecords’, the format desired with ‘format,’ and the actual search terms, which depend on the service. Together, these form the REST request sent to the server, which then returns the response in your choice of XML or JSON.

Endpoints

Express Entry Global has the following endpoints:

• GlobalExpressAddress
• GlobalExpressLocalityAdministrativeArea
• GlobalExpressFreeForm
• GlobalExpressPostalCode
• GlobalExpressThoroughfare

For a full list of endpoints, see Service URLs and Germany Service URLs.

GlobalExpressAddress

The GlobalExpressAddress endpoint is consumed to retrieve results containing all of the available address elements of an address record: FormattedAddress, AddressLine1-8, CountryISO3166_1_ Alpha2, CountryISO3166_1_Alpha3, CountryISO3166_1_Numeric, SubNationalArea, PremisesNumber, AdministrativeArea, SubadministrativeArea, locality, dependentlocality, doubledependentlocality, thoroughfare, dependentthoroughfare, building, postalcode, and postbox.

The requested fields are: format={XML,JSON}, id={ident, authorization key, or token}, address1={address1}, country={country}, and maxrecords={maxrecords}. Address2, address3, locality, administrativearea, and postalcode are optional fields.

A typical use of the GlobalExpressAddress web service is preceded by a call to the GlobalExpressPostalCode service. The Postal code is sent to the GlobalExpressPostalCode service to retrieve the locality name, and then the locality name is used to retrieve the administrative area name and to form the line1 query to the GlobalExpressAddress service request. This is referred to as ‘Fielded Input.’

GlobalExpressLocalityAdministrativeArea

The GlobalExpressLocalityAdministrativeArea endpoint is provided as a means of retrieving administrative area information using the locality name.

The requested fields are: format, id, locality, country, and maxrecords. Postalcode and administrativearea are optional fields.

GlobalExpressFreeForm

The GlobalExpressFreeForm endpoint is provided as a means of free-form searching address elements. If the search term is 7 characters or less, a “Line 1” search is performed. If the search term exceeds 7 characters, subsequent searches will use the allwords option. An allwords-style search also occurs when the “Line 1” search returns zero results.

The requested fields are: format, id, ff, country, and maxrecords. Address2, address3, locality, administrativearea, and postalcode are optional fields.

GlobalExpressPostalCode

GlobalExpressPostalCode is provided as a convenient method for quickly retrieving locality and administrative area information using the postal code as the input. A subsequent call to GlobalExpressAddress benefits greatly by using the verified locality and administrative area information.

The requested fields are: format, id, postalcode, country, and maxrecords.

GlobalExpressThoroughfare

The GlobalExpressThoroughfare endpoint is provided as a means of retrieving thoroughfare information using the Postal code and the first characters of the thoroughfare name. This endpoint requires a minimum of three characters in the ‘thoroughfare’ field to start the search.

The requested fields are: Format, ID, PostalCode, Thoroughfare, Maxrecords, and Country.

The REST Protocol

The Express Entry Global Service uses the REST protocol, which uses an HTTP query string to pass a request with selected options. An HTTPS query works the same as an HTTP query.

Using REST may require that you encode certain characters using the proper URL entities before adding them to a URL. Some characters like slashes and ampersands, if they exist as literals in the original data, must be replaced by special codes so they do not conflict with parts of the REST query.

For a list of replacement codes for the most common characters, see REST Protocol.

Also, it is necessary to use the replacement codes when sending the Melissa Data License Key, or an error of “SE01: Undefined Authorization Check Result” may result. PHP and .NET have functions that convert characters in strings automatically to the URL escape codes described in the table above.

Request Format

The REST Protocol has a specific format for all requests. The basic format is:

http://[Melissa Data Service]/web/[Request Type]?[RequestedFields]

An example:

http://expressentry.melissadata.net/web/GlobalExpressFreeForm?format=XML&id=[CustomerID]&FF=25&country=Germany&maxrecords=10

This example uses the REST protocol with the Express Entry Global Service to access Melissa Data’s databases to make a Get call with a format request for XML and 10 records returned.

JavaScript Implementation

The Global Express Entry Service has a convenient JavaScript implementation that allows you to easily add auto-fill form completion to many websites and Web-connected software. Please see Global JavaScript Sample Code for details.