> For the complete documentation index, see [llms.txt](https://docs.maker.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maker.co/features/location-based-personalization.md).
# Location-based Personalization
***
### When to use location personalization
Location-based personalization shines when you want to show different content based on where your visitor is. Common use cases include:
* Store location pages that highlight the nearest location
* Pages that adjust content for regional preferences
* Pricing or messaging that changes by market
* Any content that benefits from being location-aware
***
### How to set up location-based personalization
We offer two approaches: Pick the one that fits, as the approach you take depends on how much of your project needs to change based on location.
#### Approach 1: Simple personalization (city and country only)
If you only need to surface a visitor's city or country in one part of your project, just prompt it in Maker, and you're done. It takes literally one step.
Here's what happens behind the scenes: our system detects where your visitor is and passes that city and country information to your project. You can surface it as text, use it in a headline, or reference it however you need.
**How to do it:**
1. Open your Maker project
2. In the prompt box, mention that you want to display the visitor's city and country
3. That's it. When you prompt, Makeer will set it up for you automatically
Publish the project and the embed code (starting with `embed.maker.new`) includes this location data by default, so it works on your site right away.
**Example prompt:**
> Display the visitor's city and country in the footer
>
> In the hero copy, replace {location} with the users current city
***
#### Approach 2: Advanced personalization (multiple variants by location)
If you need different versions of your page for different locations, you'll create variants first, then set up rules that show the right variant based on where the visitor is.
Think of it like this: You design one "default" project, then create variations of it for each location you want to target. Each variant can be completely custom. Then you tell our system which variant to show to visitors in each city.
**Step 1: Create your base project and variants**
Start with a version that works for one location (or a default). Then create variants for the other locations you want to support.
For example, if you're running a store locator for multiple cities, create the default variant and ask Maker, either via a prompt or using our [Variants feature](/features/variants-and-create-experiences.md), to create the multiple variants.
* Default variant: New York (default)
* Variant 2: Los Angeles
* Variant 3: London
* Variant 4: Paris
* Variant 5: Singapore
Each variant can have completely different content, headings, or layouts. It's up to you.
**Step 2: Use Maker to set up rules**
Once you have your variants, prompt Maker to create the rules that connect each variant to its location. You can prompt something like:
Maker creates the rules automatically based on your variants.
**Step 3: Publish**
Make sure to publish the page and use the embed code provided.
{% embed url="" %}
***
### Use a Maker Skill
You can also use the **Location variants** Skill to create per-city variants so different content is shown to visitors based on their detected city. Use when you need completely different page experiences for different locations, like showing store info for local visitors or region-specific content.
*Skill descriptions on the cards are previews only. The full instructions are written for Maker to read and apply, so you don't need to see the complete text to get the benefit.*
***
### How location detection works
Our system uses CDN-provided location data to figure out where your visitor is. Here's what that means in practice:
* We detect the nearest major city to where a visitor is located
* For someone in Manhattan, we'll recognize them as "New York" (the nearest major city)
* For someone in a small town outside a major city, we fall back to the closest large city we can identify
* We pass both city and country data to your project
**A note on precision:** Because this uses CDN data, it's accurate at the city level for major cities, not down to neighborhoods or specific addresses. If you need more granular control, you can also pass location data as a query parameter (like `?city=Manhattan`), and that will override the auto-detected location.
***
### Testing your location variants
When you create location variants, you'll want to test them from different locations. Here are a few ways:
**Option 1: Use a VPN** If you connect to a VPN in a different city, your location will appear to be in that city when you load the page.
**Option 2: Use query parameters** Add a query parameter to your URL to manually set the location for testing:
```
yoursite.com/page?city=Mumbai
```
This overrides the auto-detected location, so you can test each variant without needing a VPN.
**Option 3: Ask your team** Have team members in different locations test the page from their actual locations. They'll see the variant appropriate for their city.
***
### Limitations and things to know
* **CDN coverage:** Our location detection works best for major cities. Small towns and rural areas might fall back to the nearest major city.
* **Radius coverage:** There's a radius around major cities. For someone in Mountain View, we'll recognize them as 'San Francisco' (the nearest major city). This is by design, but if you want finer control, use query parameters.
* **One-time setup:** Adding location support to your project is a one-time effort. Once it's live, it works.
### Embed code requirements
If this is a new project, then the right embed code will be created. If this is an older project that you are working on, make sure you publish the project and verify that the embed code uses the new location-aware embed code. Look for code that starts with:
```
embed.maker.new
```
### FAQs
What's the difference between simple personalization and variants?
Simple personalization is when you just want to display a visitor's city or country somewhere on your page. You mention it in your prompt, and we set it up automatically. Variants are for when you want completely different versions of your page for different locations. You create multiple versions, then we show the right one based on where someone is visiting from.
Do I need developer help to set this up?
Nope. For simple personalization, you just prompt it in Maker. For variants, you create the different versions in Maker, then prompt the Maker to connect them to locations. No code required.
How accurate is the location detection?
We detect visitors down to the major city level pretty accurately. For smaller towns or suburbs, we fall back to the nearest major city. For example, if someone is in a suburb outside San Francisco, they'll be detected as San Francisco. It's accurate enough for most use cases, but not neighborhood-level precise.
Can I personalize by country as well as city?
Yes, both city and country data are available. You can personalize just by country, just by city, or both together. Your Maker prompt can specify whichever level of detail you need.
How do I test location variants from my own location?
You have a few options. You can use a VPN to connect from a different city, or you can add a query parameter to your URL to manually set the location (like `yoursite.com/page?city=Mumbai`). The query parameter is the easiest for testing.
What if my visitor is using a VPN?
If someone has a VPN on, the location detection will show the city they're VPN'd into, not their actual location. That's just how location data works on the web. For most visitors without VPNs, you'll get accurate detection.
How many location variants can I create?
As many as you need. We've seen customers create variants for anywhere from 3 cities to 15+ depending on their needs. The setup is the same regardless of how many you create.
Will location personalization slow down my page?
No, location detection happens in the background. It doesn't add noticeable load time to your page.
How does the system know where my visitor is?
We use CDN location data, which is based on the visitor's IP address. It's accurate at the city level for major cities, but not precise enough for neighborhoods or specific addresses.
What if I want to personalize based on regions or states instead of cities?
You can still do it. Just create your variants for whatever geographic division makes sense for your business, and prompt Maker to set up the rules accordingly.
Can I combine location data with other personalization?
Yes, you can create any variant and use the location-based personalization to show the correct page to the end user.
What's the difference between having city and country available versus other location data?
We focus on city and country because those are the most useful for personalization. Things like street-level address detection are too imprecise with IP-based location data to be reliable, so we stick with what actually works.
What happens if location detection doesn't work for some visitors?
In rare cases where location data isn't available, your project will show the default variant you set. It's a graceful fallback so visitors always see something, even if we can't pinpoint their location.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.maker.co/features/location-based-personalization.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.