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, you can 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.
  1. Log in to Business Manager.
  2. Go to Administration > Global Preferences > Feature Switches.
  3. Check Enable Shopper Context.

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:

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

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

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.

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:

THe x-geolocation response header returned is:

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.

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:

The following x-geolocation response header is returned:

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.

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:

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.

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