Shopper Geolocation

Geolocation plays a crucial role in providing personalized experiences based on shopper location. Use this guide to integrate Shopper Context API geolocation features with your storefront for enhanced shopper experiences.

With B2C Commerce version 24.7, work with geolocation information in the following ways:

Look up a shopper’s location using the client’s IP address.
Look up a shopper’s location using the client’s IP address and use that information to set context for subsequent requests.
Manually provide a location and use that information in subsequent requests.

When you use SCAPI to retrieve geolocation information, the client’s IP address is used to retrieve geolocation information from the B2C Commerce platform, and the IP lookup is based on your database information. For details, see Geolocation Lookup for IP Addresses.
An association with a location impacts future requests. For example, you have a dynamic customer group for which membership includes request.geolocation.city == 'San Francisco'. For the purposes of group membership evaluation, this geolocation location applies to subsequent requests for this shopper. For details, see Customer Segmentation Via Geolocation.

Note

Enable Shopper Context

Log in to Business Manager.
Click App Launcher and then select Administration > Global Preferences > Feature Switches.
Check Enable Shopper Context.

Retrieve Geolocation with Client IP Address

The SCAPI geolocation service does not support Anycast-related IP addresses. Anycast allows the same IP in multiple locations, and, therefore, can’t resolve to one single location.

Important

Using SCAPI, geolocation information is retrieved using the client’s IP address to look up geolocation information in the B2C Commerce platform.

Include the clientIp attribute with a Shopper Context PATCH or PUT request, for example:

1curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
2	    --method 'PUT' \
3	    --header 'Authorization: Bearer $TOKEN' \
4	    --header 'Content-Type: application/json' \
5	    --data '{ "clientIp": "13.108.0.0" }'

The following keys are provided in the HTTP response header x-geolocation, and are delimited with semicolons (;):

CountryCode
Country
City
PostalCode
MetroCode
Region
RegionCode
Latitude
Longitude

1x-geolocation: CountryCode: US; Country: United States; City: San Francisco; PostalCode: 94105; MetroCode: 820; Region: San Francisco; RegionCode: CA; Latitude: 37.7749; Longitude: -122.4194

Consume the geolocation HTTP response header in a case insensitive way, because it can be returned as x-geolocation or X-Geolocation.

Note

Retrieve and Use Geolocation from Client IP

Retrieving geolocation with clientIp returns information, but does not impact subsequent requests. To use the location provided by clientIp on subsequent requests, you must specify the evaluateContextWithClientIp query parameter:

If evaluateContextWithClientIp is set to true:

the clientIP is saved and is used with subsequent requests.

If evaluateContextWithClientIp is set to false:

the clientIP is not saved and is not used with subsequent requests.

In both cases, the x-geolocation response header is returned. Null or empty values are not returned.

Retrieve Geolocation with geoLocation Attribute and Set Context

You can also use the geoLocation attribute to set a specific context geolocation. You can collect a user’s location via native browser functionality (navigator.geolocation) or via manual user input, and send these coordinates to the Shopper Context API for site personalization.

You can manually set any combination of the following optional parameters:

countryCode
country
city
postalCode
metroCode
region
regionCode
latitude
longitude

The following Shopper Context example request provides the city and countryCode parameters in the geoLocation attribute to set the geolocation information:

1{
2   "clientIp": "12.12.12.1",
3    "geoLocation": {
4      "city": "Boston",
5      "countryCode": "US"
6    }
7}

THe x-geolocation response header returned is:

1x-geolocation: CountryCode: US; City: Boston;

If you set a location using the geoLocation attribute in the request body, it is saved as context for subsequent requests. If both geoLocation and clientIp are set in the context, the location set with geoLocation takes precedence over the location resolved from the clientIp.

Important

For example, let’s assume the following promotion configuration:

For New York, USA: 20% discount on women’s tops.
For Boston, USA: 15% discount on women’s tops.

In the following Shopper Context request, both clientIp and geoLocation attributes are provided. In this case, the geoLocation value takes precedence and the response header x-geolocation returns the location based on the geoLocation attribute in the request:

1curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
2	    --method 'PUT' \
3	    --header 'Authorization: Bearer $TOKEN' \
4	    --header 'Content-Type: application/json' \
5	    --data '{ "clientIp": "12.12.12.1",
6                "geoLocation": {
7                    "countryCode": "US",
8                    "country": "United States of America",
9                    "city": "Boston",
10                    "postalCode": "01730",
11                    "metroCode": "M234",
12                    "region": "NA",
13                    "regionCode": "12345",
14                    "latitude": 10.11,
15                    "longitude": 198.34
16                }
17              }'

The following x-geolocation response header is returned:

1x-geolocation: CountryCode: US; Country: United States of America; City: Boston; PostalCode: 01730; MetroCode: M234; Region: NA; RegionCode: 12345; Latitude: 10.11; Longitude: 198.34

Suppose the clientIp 12.12.12.1 resolves to New York, USA, but because the geoLocation in the payload specifies Boston, US, the context is evaluated based on Boston-specific promotions, resulting in a 15% discount on women’s tops.

Prompt the User for Geolocation

In this case, you provide a prompt for the user to enter geolocation information, which you can then send to the Shopper Context API, for example:

Provide Latitude and Longitude

1curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
2    --method 'PUT' \
3    --header 'Authorization: Bearer $TOKEN' \
4    --header 'Content-Type: application/json' \
5    --data '{ "geoLocation": { "latitude": 37.7749, "longitude": -122.4194 } }'

Provide Other Location Data

1curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
2    --method 'PUT' \
3    --header 'Authorization: Bearer $TOKEN' \
4    --header 'Content-Type: application/json' \
5    --data '{ "geoLocation": { "countryCode": "US", "city": "San Francisco" } }'

Update Geolocation For Use in Subsequent Requests

When the geoLocation attribute is updated in Shopper Context PATCH calls, the entire existing geolocation value is replaced, not individual property values. To make a change to the geolocation, you must send all required properties, because geolocation properties work together.

You can set a new location context using the geoLocation attribute in the request body. The geoLocation attribute contains:

countryCode
country
city
postalCode
metroCode
region
regionCode
latitude
longitude

Null values are not returned.

Geolocation with Hooks

From a Script API perspective, dw.system.Request.getGeoLocation` returns the following geolocation information, which is useful when using hooks:

City: request.geolocation.city
Country Name: request.geolocation.countryName
Country Code: request.geolocation.countryCode
Latitude: request.geolocation.latitude
Longitude: request.geolocation.longitude
Metro Code: request.geolocation.metroCode
Postal Code: request.geolocation.postalCode
Region Name: request.geolocation.regionName
Region Code: request.geolocation.regionCode