Is the API for the new geolocation app accessible for custom promotions?

Shopify Apps

Topic summary

Undocumented Geolocation API Discovery

A Shopify merchant discovered an undocumented endpoint (/browsing_context_suggestions.json) that returns visitor geolocation data, including country name and ISO country code. This endpoint is part of Shopify’s native Geolocation app infrastructure.

Technical Implementation:

  • The endpoint returns JSON with detected_values containing country information
  • Can be called via AJAX/fetch from client-side JavaScript without CORS issues
  • Query parameters allow filtering by currency and language settings
  • Access country data using: d.detected_values.country.handle (ISO code) or d.detected_values.country.name

Common Use Cases:

  • Display location-specific promotions or banners
  • Show country-specific delivery rates
  • Customize content without third-party services or additional apps

Key Challenges Discussed:

  • Initial lack of documentation (later officially documented by Shopify)
  • JavaScript syntax errors for non-developers
  • jQuery dependency requirements
  • CORS configuration questions
  • Confusion between expansion stores vs. single-site internationalization

Current Status:
The feature is now officially documented in Shopify’s developer documentation under Markets/Localization Discovery. Multiple users confirmed the API works successfully for custom geolocation-based content modifications.

Summarized with AI on November 16. AI used: claude-sonnet-4-5-20250929.
2

So a little poking around and you can call the following endpoint on your store.

/browsing_context_suggestions.json

This gives you a simple object below

{
  "detected_values": {
    "country_name": "United Kingdom"
  },
  "suggestions": []
}

Which you can parse and use a if/else of switch statement to show or modify elements on your site via JS.

The query string options for the endpoint that are generated by the app include the below:-

source=locale_bar_app
currency[enabled]=true
currency[exclude]=USD
language[enabled]=true
language[exclude]=en

With the response changing to:-

{
    "detected_values": {
        "country_name": "United Kingdom"
    },
    "suggestions": [
        {
            "parts": {
                "currency": {
                    "handle": "GBP",
                    "name": "British pounds",
                    "confidence": 1,
                    "options": {
                        "CAD": "CAD $",
                        "DKK": "DKK kr",
                        "EUR": "EUR €",
                        "GBP": "GBP £",
                        "SEK": "SEK kr",
                        "USD": "USD $"
                    }
                }
            },
            "confidence": 1
        }
    ]
}

Would be great if there’s some documentation out there for these options. As using this native functionality would be nicer than needing to rely on third party IP to Country solutions.

2 Likes