CX Works

CX Works brings the most relevant leading practices to you.
It is a single portal of curated, field-tested and SAP-verified expertise for SAP Customer Experience solutions

Enable Location-based Marketing with Geocoding Using Google Maps

12 min read

Enable Location-based Marketing with Geocoding Using Google Maps

Enriching your contact and interaction data with location information can be powerful when used correctly. It can increase the meaningfulness of your communication with your customers. The process of converting an address into geographical coordinates (latitude/longitude) is called geocoding, and vice versa (reverse geocoding).
Numerous services provide functionalities to convert addresses to geographical coordinates and back. The available geographical coordinates can be used in SAP Marketing Cloud for segmenting location-based target groups. This article describes a simple use case for building an integration to geocode and reverse geocode, using Google Maps’ geocoding capabilities.

Table of Contents

Using Geolocation in SAP Marketing Cloud Segmentation

Segment contacts based on their geographical data and create location-based target groups.


Simplified process flows for using Google Maps' geocoding capabilities.


This blog post only covers (reverse) geocoding for single addresses (not bulk or mass processing). The tests we've conducted stay within the Standard Usage Limits of the Google Maps Geocoding API limitations. Please review Google Maps Geocoding API Usage Limits documentation, before using the API.


Configuration: Google Maps Geocoding API 

As you set up the Google Application, create an API key to enable access to call the Google Maps Geocoding API. We recommend you restrict access to the API key usage because the API key comes with the request URL. The IP-range that applies to your cluster depends on your SAP Integration Suite's maintenance location. You can find that information in the SAP Help documentation for SAP Business Technology Platform:

SAP Business Technology Platform - Regions

Google API Manager

Please, get familiar with using Google Maps API.

The service used in this blog post was not designed to respond to user input, in real time.

Documentation: Developer Guide - What is Geocoding?


Configuration: SAP Marketing Cloud

For this scenario, inbound is the only configured communication.

Configure SAP Marketing Cloud Inbound Communication.
To import data using the OData Service for Master Data integration configure an Inbound Communication Channel.

  • Create a Communication System
    • Define a name for the Communication System.
    • Define the Authentication Method for Inbound Communication.
  • Create a Communication Arrangement Inbound Scenario
    • Select the Communication System created before
    • Select the Scenario SAP_COM_0003
    • Create a Communication User (or use an existing user) and assign the user to the Communication Arrangement

Inbound Communication Arrangement

Configuration: SAP Integration Suite iFlow

The iFlow (Integration Flow) below provides information on the general approach on how to call the Google Maps Geocoding API, maps the target structure, and creates an interaction contact in SAP Marketing Cloud.

This iFlow is one of many approaches to process geocoding with Google Maps.

Part 1: Geocoding

Now, let’s review the mandatory steps to translate an address into geographical coordinates.

1. Receive Message

Your sending system sends an XML formatted payload containing customer information, including valid address information.
To relate the information to a location you will need to get the geographical location data (Longitude/Latitude).

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>premise</type>
        <formatted_address>20 N Upper Wacker Dr, Chicago, IL 60606, USA</formatted_address>
        <address_component>
            ...
        </address_component>
        <geometry>
            <location>
                <lat>41.8825640</lat>
                <lng>-87.6374246</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>41.8812150</lat>
                    <lng>-87.6387735</lng>
                </southwest>
                <northeast>
                    <lat>41.8839130</lat>
                    <lng>-87.6360756</lng>
                </northeast>
            </viewport>
            <bounds>
                <southwest>
                    <lat>41.8820520</lat>
                    <lng>-87.6377680</lng>
                </southwest>
                <northeast>
                    <lat>41.8830760</lat>
                    <lng>-87.6370811</lng>
                </northeast>
            </bounds>
        </geometry>
        <place_id>ChIJEz3RjbgsDogR5z1PbIL8Ib0</place_id>
    </result>
</GeocodeResponse>

Inbound message Payload:

<root>
	<row>
		<Id>C-100</Id>
		<IdOrigin>SAP_FILE_IMPORT</IdOrigin>
		<Timestamp>20170729122215</Timestamp>
		<TitleDescription>Mr.</TitleDescription>
		<FirstName>Ron</FirstName>
		<LastName>Scuba</LastName>
		<Street>North Lower Wacker Drive</Street>
		<HouseNumber>20</HouseNumber>
		<City>Chicago</City>
		<Region>IL</Region>
		<Country>USA</Country>
		<EMailAddress>Ron.Scuba@abcd123.com</EMailAddress>
		<EMailOptIn>Y</EMailOptIn>
		<PhoneNumber>+1 555 123123123</PhoneNumber>
		<PhoneOptin>N</PhoneOptin>
		<DateOfBirth>19480902</DateOfBirth>
	</row>
</root>

2. Enrich Message in a Separate Branch

Reviewing the inbound message payload, we noticed that no geographical coordinates are included. To enrich the inbound message with geographical coordinates, external services can be used to enrich the message with geographical coordinates.
To do so, create a second branch in which the GPS location is retained in messages exchange properties while keeping the original message payload in the first branch.
The address is then submitted to the Google Maps Geocoding API with the Google Maps API Key.
Google Maps provides parameters to filter, sort, and preselect the results.

3. Call Google Maps geocoding API

With the parameters available for retrieving the address data from Google Maps, the query you must submit to Google Map is defined in the HTTP Communication Channel.

Query: address=<HouseNumber>+<Street>,+<City>,+<Region>,<Country>&key=<API key>

Query on SAP Integration Suite: address=${property.HouseNumber}+${property.Street},+${property.City},+${property.Region},${property.Country}&key=<API key>

Google Maps provides the option to retrieve the response in JSON or XML.

Google Maps Response (XML format):


4. Merge Messages

After retrieving the response from the Google Maps API both messages need to be combined again.

Message 1: Original message payload (message received from the sender system)

Message 2: Google Maps Geocoding API response

The inbound message is routed to two different branches where one branch is just passing the message through and the other request geocoding the address to geographical coordinates. To merge both messages into back into one, a combination of the “Join” and “Gather" Integration Pattern is used. The result is wrapped with the additional XML tags, shown below.

<multimap:Messages xmlns:multimap="http://sap.com/xi/XI/SplitAndMerge">
<multimap:Message1>
...Original Sender Message Payload...
</multimap:Message1>
<multimap:Message2>
...Google Maps Response...
</multimap:Message2>
</multimap:Messages>


5. Message Mapping

In this example, the message, containing both messages, is mapped using the Message Mapping of the Cloud Integration capability within SAP Integration Suite. It would help if you made sure that the source and target XML Schema aligns with the actual inbound message and the XML Schema from the receiver. Here, we are creating a Multi-Message-Mapping where two source messages are applied, and only one target message. However, after the mapping, the message structure is still incorrect because you need a multi-message in the mapping. A simple solution is to define a filter to filter step for the part of the message you need, using standard integration patterns, before sending the message to SAP Marketing Cloud.

When mapping the fields, make sure to use the correct context. You should get familiar with how queues and contexts work with graphical mapping. (See the blogs posts referred below)


Yellow: Original Sender Message Payload (Source)
Green: Google Maps Geocoding API Response (Source)
Blue: SAP Marketing Interaction Contact (Target)

Two excellent posts describing queues and context with Graphical Mapping:

Here, we used the Compound Import Service for importing Interactions to SAP Marketing Cloud. The the available Services and APIs evolve, we recommend using the Contacts API to import Contact Information.

Quick Guide - Which API for Which Entity


6. Create Contact in SAP Marketing Cloud

To verify if the message complies with the message structure, expected by Marketing Cloud, add an XML Validator. This step validates the message structure against the Schema XML added to the XML Validator integration pattern. From here, you need to configure the Receiver Communication Channel to submit the message to our receiving system.

You can review the contact created using the Inspect Contact app on the Marketing Cloud.

On SAP Marketing Cloud, we only used standard functionality, so no customization is needed.

Part 2: Reverse Geocoding

The procedure for reverse geocoding is very similar to the geocoding process described above.

Reverse Geocoding needs to be used with caution. Geographical coordinates can have multiple physical addresses or multiple contacts can share the same physical address (e.g. apartment building).
Physical addresses retrieved through reverse geocoding are not recommended to be using for Mail campaigns but can still be useful, e.g. for segmentation.


1. Receive Message

The sending system will send an XML formatted payload, containing customer information. This time the inbound message contains geographical coordinates instead of address information.

Inbound message Payload:

<root>
  <row>
    <Id>C-100</Id>
    <IdOrigin>SAP_FILE_IMPORT</IdOrigin>
    <Timestamp>20170729122215</Timestamp>
    <FirstName>Ron</FirstName>
    <LastName>Scuba</LastName>
    <TitleDescription>Mr.</TitleDescription>
    <EMailAddress>Ron.Scuba@abcd123.com</EMailAddress>
    <EMailOptIn>Y</EMailOptIn>
    <PhoneNumber>+1 619 62234267</PhoneNumber>
    <PhoneOptin>N</PhoneOptin>
    <DateOfBirth>19480902</DateOfBirth>
    <Latitude>41.88255</Latitude>
    <Longitude>-87.637167</Longitude>
  </row>
</root>


2. Enrich Message in a Separate Branch

 This time we are going to enrich the message with a physical address from the geographical coordinates. For reverse geocoding the geographical coordinates are passed to the Google Maps API instead of the physical address information.

3. Call Google Maps Geocoding API

The query is defined in the HTTP Adapter on Cloud Integration. Please refer to the Google Maps documentation for more information: https://developers.google.com/maps/documentation/geocoding/intro

Query: latlng=${property.latitude},${property.longitude}&location_type=ROOFTOP&result_type=street_address&key=<API key>

Google Maps provides the option to retrieve the response in JSON or XML.

Google Maps Response (XML format):

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>20 N Lower Wacker Dr, Chicago, IL 60606, USA</formatted_address>
        <address_component>
            <long_name>20</long_name>
            <short_name>20</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>North Lower Wacker Drive</long_name>
            <short_name>N Lower Wacker Dr</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Chicago Loop</long_name>
            <short_name>Chicago Loop</short_name>
            <type>neighborhood</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Chicago</long_name>
            <short_name>Chicago</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Cook County</long_name>
            <short_name>Cook County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Illinois</long_name>
            <short_name>IL</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>60606</long_name>
            <short_name>60606</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>41.8825731</lat>
                <lng>-87.6374299</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>41.8812241</lat>
                    <lng>-87.6387789</lng>
                </southwest>
                <northeast>
                    <lat>41.8839221</lat>
                    <lng>-87.6360809</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJBRwtjLgsDogRPYuy9JcGjfw</place_id>
    </result>
</GeocodeResponse>


4. Merge Messages

Again, you need to merge two messages into one.

Message 1: Original message payload (message received from the sender system)

Message 2: Google Maps Geocoding API response


5. Message Mapping

The Message Mapping is very similar to the one from the geocoding example. Make sure you add  the correct XML Schema files.

Yellow: Original Sender Message Payload (Source)
Green: Google Maps Response (Source)
Blue: SAP Marketing Interaction Contact (Target)

Here, we used the Compound Import Service for importing Interactions to SAP Marketing Cloud. The the available Services and APIs evolve, we recommend using the Contacts API to import Contact Information.

Quick Guide - Which API for Which Entity


6. Create Contact in SAP Marketing Cloud

Configure the Receiver Communication Channel and submit the message to your receiving system.

Use the Inspect Contact app on Marketing Cloud to review the contact you created.
On SAP Marketing Cloud, we only used standard functionality, so no customization is needed.

In the segmentation, you can display contacts with location information.

Conclusion

Depending on your use case, you might need to provide the address data as a GPS location or full address information. The Google Maps Geocoding API provides an easy-to-use interface for geocoding and reverse geocoding.

With this, you should be able to configure a simple scenario with the Google Maps Geocoding API and create an Interaction Contact in Marketing Cloud. Setting up SAP Marketing requires a few steps that can be done within minutes. SAP Integration Suite’s easy-to-use interface will allow you to onboard quickly, so you can design and configure your  iFlow to perform complex tasks.

Overlay