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 parameter 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

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 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 sent. Null or empty values are not returned.

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

If you set a location manually, it is saved as context for subsequent requests. This overrides any context saved using clientIp.

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

When evaluateContextWithClientIp is set to true, the geoLocation provided in the payload takes precedence over the location resolved from the clientIp. For the previous 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.

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:

Previous geolocation values are not retained in PATCH calls. When you want 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 location attribute in the request body. The location attribute contains:

  • countryCode
  • city
  • postalCode
  • metroCode
  • 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 Code: request.geolocation.countryCode
  • Latitude: request.geolocation.latitude
  • Longitude: request.geolocation.longitude
  • Metro Code: request.geolocation.metroCode
  • Postal Code: request.geolocation.postalCode
  • Region Code: request.geolocation.regionCode