Google Geocoding

Turn an address supplied during registration or checkout into latitude and longitude. The coordinates become Darwinium attributes that you can use in subsequent analysis, for example when comparing a declared address with other location information.

Geocoding describes an address. It does not establish where the browser is located or whether the customer owns that address.

Before you start

Enable the Google Geocoding API for your Google project and obtain a key with the required access. Store it as a named secret, such as google_geocoding_key. Install Google Geocoding, import google_geocoding.snippet and add its model operation to the step receiving the address.

Map the address and select its contexts

For this illustrative registration request:

{
  "address": {
    "line1": "1600 Amphitheatre Parkway",
    "line2": "",
    "city": "Mountain View"
  }
}

Configure these request-body mappings:

Then configure the operation:

The context arguments select both the input address and the output location. If your shipping address lives under a different identity or address context, choose that exact pair instead.

Prepare a reliable request

The supplied template constructs an address from street1, street2 and city, calls Google's Geocoding endpoint and uses a 2,000 ms timeout. It declares LOCAL.JOURNEY; add the dependency on LOCAL.REQUEST when your address comes from the current request.

Darwinium's Call URL handling percent-encodes runtime values inserted into the URL. Supply the original address values in your mappings; do not pre-encode them. The template joins its three address fields with spaces. Include state, postal code and country in a custom copy when your data needs them for disambiguation. Google's Geocoding request guide describes supported parameters and response statuses.

Inspect and use the coordinates

The template selects the first result and maps its location to:

identity['ACCOUNT'].address['HOME'].geocoding.latitude
identity['ACCOUNT'].address['HOME'].geocoding.longitude

Those paths follow the contexts you selected. Make any consuming rule or model depend on the geocoding operation. Check that both coordinates exist before using them.

The supplied response mapping does not retain Google's status, alternative matches or location precision. For a flow that needs to distinguish an unknown address from a failed call, add $.status to custom.general_purpose['geocoding_status'] in the response JSONPath mappings. Review the result's precision before treating it as an exact address match.

Test the address cases your application accepts

Deploy to a test target and submit a known address. Inspect the mapped source address, response status if added, and both coordinates in Investigations. Then try an address containing punctuation, an incomplete address and one with no match. A missing result must remain distinguishable from valid coordinates; do not substitute zero latitude and longitude as a successful lookup.