Google Maps enricher

The Google Maps enricher cleanses, standardizes, and enriches international postal addresses with geocoding information.

Plugin ID

Google Maps Enricher - com.semarchy.integration.rowTransformers.googleMapsEnricher

Description

This enricher takes an postal address, enriches it, and validates it using the Google Geocoding service.

This plugin must be used in compliance with the Google Maps/Google Earth APIs Terms of Service.

This enricher uses the Google Geocoding service, which must be accessible from the Semarchy xDM application at the following URL: http://maps.googleapis.com/maps/api/geocode/json?<parameters>. Make sure to make this URL accessible through your firewalls.

This plugin is thread-safe and supports parallel execution.

Plugin parameters

The following table lists the plugin parameters.

Parameter name Mandatory Type Description

Parameter name	Mandatory	Type	Description
Client ID or API Key	No	String	Either an API key (for Standard API usage) or the client ID (for Premium Usage), both provided by Google. The client ID should begin with the `gme-` prefix. When providing a client ID, the signature (private key) is required.
Channel	No	String	A specific channel name to allow tracking usage for this plugin in the Google Maps usage reports.
Default Language	No	String	The code of the default language used for the returned results (e.g., for the same address, "Rue Mathieu Misery" would appear in French and "Mathieu Misery Street" in English). This code can be overridden by the Language plugin input. For more information, see the list of supported domain languages.
Private Key	No	String	The cryptographic signature key provided by Google with the client ID.
Request per Second	No	Integer	The maximum number of requests per second made by the enricher to remain within the limits of the API (default: `50`).

Client ID or API Key

String

Either an API key (for Standard API usage) or the client ID (for Premium Usage), both provided by Google. The client ID should begin with the gme- prefix. When providing a client ID, the signature (private key) is required.

Channel

String

A specific channel name to allow tracking usage for this plugin in the Google Maps usage reports.

Default Language

String

The code of the default language used for the returned results (e.g., for the same address, "Rue Mathieu Misery" would appear in French and "Mathieu Misery Street" in English). This code can be overridden by the Language plugin input. For more information, see the list of supported domain languages.

Private Key

String

The cryptographic signature key provided by Google with the client ID.

Request per Second

Integer

The maximum number of requests per second made by the enricher to remain within the limits of the API (default: 50).

You can use the Google Maps service with one of the following authentication methods:

With an API key, with the Standard Usage Limits and a pay-as-you-go plan above the limits.
With a client ID and a signature (private key) with a Google Maps Premium Plan.

Keyless access to this API is not supported by Google.

Plugin inputs

The following table lists the plugin inputs.

Input name	Mandatory	Type	Description
Address Line	Yes	String	The address line to process. If the address is composed of multiple lines, then these lines must be provided as a comma-separated list of address lines.
Postal Code	No	String	The postal code of the address.
City	No	String	The city of the address.
Country	No	String	The country of the address.
Language	No	String	The code of the language for the returned result for this record. This language overrides the Default Language parameter. For more information, see the list of supported domain languages.

Input name

Mandatory

Type

Description

Address Line

Yes

String

The address line to process. If the address is composed of multiple lines, then these lines must be provided as a comma-separated list of address lines.

Postal Code

String

The postal code of the address.

City

String

The city of the address.

Country

String

The country of the address.

Language

String

The code of the language for the returned result for this record. This language overrides the Default Language parameter. For more information, see the list of supported domain languages.

The state, region or province information can be passed in the City input, concatenated with the city name (e.g., Address.City || ' ' || Address.State).

The entire address, including the Address Line, Postal Code, City and Country values can be passed to the plugin as a single concatenated string in the Address Line input. If the source data contains the address in a single string, then you can pass this string directly in the Address Line input.

Plugin outputs

The following table lists the plugin outputs. Outputs marked with a * appear in a full and a short form in the output list.

Output name Type Description

Address Types

String

A comma-separated list of address types (for more information, see the official Google documentation).

Administrative Area Level 1*

String

The first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all countries exhibit these administrative levels.

Administrative Area Level 2*

String

The second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all countries exhibit these administrative levels.

Administrative Area Level 3*

String

The third-order civil entity below the country level. Not all countries exhibit these administrative levels.

Airport

String

An airport.

This output is deprecated.

Country*

String

The national political entity.

East Bound Longitude

String

The bounding box eastern limit.

Floor*

String

The floor of a building address.

Formatted Address

String

A human-readable version of the geocoded address.

Intersection

String

A major intersection, usually of two major roads.

This output is deprecated.

Latitude

String

The altitude of the address.

Locality*

String

The incorporated city or town political entity.

Longitude

String

The longitude of the address.

Natural Feature*

String

A prominent natural feature.

Neighborhood*

String

A named neighborhood.

North Bound Latitude

String

The bounding box northern limit.

Park*

String

A named park.

Place ID

String

A unique identifier for a place in the Google Places database and on Google Maps.

Point of Interest*

String

A named point of interest.

Post Box*

String

A specific postal box.

Postal Code*

String

A postal code as used to address postal mail within the country.

Postal Town

String

A grouping of geographic areas, such as locality and sublocality, used for mailing addresses in some countries.

Premise*

String

A named location, usually a building or collection of buildings with a common name.

Quality

Integer

The value of an Address Quality element that defines the granularity of the location described by an address. Should return a value that expresses this quality between 0 and 100 (100 being the best quality).

Room*

String

The room of a building address.

Route*

String

A named route (e.g., US 401).

South Bound Latitude

String

The bounding box southern limit.

Status

String

The status of the request. OK indicates that no error occurred and the address was geocoded. ZERO_RESULTS indicates that no error occurred but the address was not geocoded. For a list of status and error codes, see the API documentation.

Street Address

String

A precise street address.

This output is deprecated.

Street Number*

String

A precise street number.

Sub-Locality*

String

The first-order civil entity below a locality.

Sub-Premise*

String

The first-order entity below a named location, usually a singular building within a collection of buildings with a common name.

West Bound Longitude

String

The bounding box western limit.