Personalize by Visitor Location

Last updated October 23, 2026

Show each visitor content that fits where they are. Ploy passes location headers to your site on each visitor request, such as the visitor's country, state or region, and city. Your site can use them to change a headline, show local numbers, pick a currency, or point people to the nearest office.

You don't need to write the code. Ask Ploy's Agent what to personalize, and it builds the page to read the headers and choose the right content.

Limits

• Location headers work on server-rendered pages and on your site's API routes. A page that is built once when you publish (a prerendered page) cannot read them, because the same copy is sent to every visitor. Pages Ploy builds are server-rendered unless they were set up to be prerendered. When you request personalization, ask Ploy's Agent to make sure the page is server-rendered.
• Location comes from the visitor's IP address, so it is an estimate. Visitors on a VPN, a corporate network, a mobile carrier, or a privacy relay can show up in a different city, region, or country. Never use location for anything that must be exact, such as tax, legal eligibility, or access control.
• A header can be missing or empty when the location is unknown. Always have a default version of the content.
• Location headers are not sent to an existing site that Ploy forwards traffic to with a routing rule. Only pages Ploy serves itself receive them.
• When you run your site on your own computer with the Ploy CLI, these headers are usually not present, so you see the default content. Test location content on Preview.

Available location headers

These are the location headers your site receives on each request. The example values are for a visitor in San Francisco.

The one most sites start with is cf-region-code. In the United States it is the two-letter state code, such as CA for California or TX for Texas. In other countries it is the local region code, such as ON for Ontario in Canada.

A few things to know about the values:

• cf-ipcountry is XX when the country is unknown and T1 for visitors using Tor.
• cf-metro-code is mainly available for visitors in the United States.
• City and region names can include accented letters, such as Montréal.

Personalize a page with Ploy's Agent

Tell Ploy's Agent which page to personalize, which header to use, and what should change for each location. Also say what visitors should see when their location is unknown.

You can keep the content for each location in a PloyDB table, with one row per region. Then you can update the content for a region like a spreadsheet, without another code change.

Ploy's Agent plans the change and builds the page to read the header on each visit. Review it on Preview before you publish.

Test your location content

• Open your Preview link and check that the content matches your location.
• To see another region's version, connect through a VPN set to that region and reload the page.
• Check the default version too. It is what visitors see when their location is unknown.
• After you publish, check the content again on your live site, including your custom domain if you use one.

Good practice

• Keep a default. Every personalized section needs content for visitors whose location is missing or not in your list.
• Keep personalized pages out of shared caches. A cached copy can show one visitor's version to everyone. Ask Ploy's Agent to make sure personalized pages are not cached.
• Think about search engines. Search crawlers see the version for their own location, often the United States. Keep the important content for search on the default version.
• Cover it in your privacy notice. Location headers are based on IP address. If your site saves them, for example with a form submission or in a PloyDB table, describe that in your privacy notice.

What's Next?

• Store the content. Read Database to learn how PloyDB tables work.
• Measure results. Use Analytics to see how visitors respond to the personalized page.
• Publish. Follow Publishing & Deploys to review on Preview and go live.