Express Entry:Global Getting Started
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 Key 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.
The requested fields are: format, id, ff, country, and maxrecords.
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.