Geo Redirects
Automatically redirect visitors based on location
What are Geo Redirects?
Geo redirects automatically send visitors to a different URL based on their geographic location. This is the most common form of geo-targeting, used by businesses that have separate websites or landing pages for different countries or regions.
For example, you might redirect visitors from Germany to example.de and visitors from France to example.fr, while everyone else stays on example.com.
How It Works
Visitor loads your page
The geoswap.js script loads on your page and sends the visitor's request to the GeoSwap edge network.
Location is determined at the edge
Cloudflare Workers determine the visitor's country, region, and city using edge-level geolocation. No third-party API calls are needed.
Rules are evaluated
The Worker checks your redirect rules (stored in Redis for speed) and determines whether a redirect should happen. Rules are checked top to bottom, and the first match wins.
GeoRedirect executes client-side
If a rule matches, the geoswap.js script performs the redirect. The visitor sees a near-instant navigation to the correct URL.
Setup Guide
Step 1: Install the GeoSwap script
Add the GeoSwap script to your website. See the Installation Guide for platform-specific instructions.
Add to <head>html
<script>window.geoswap=window.geoswap||{q:[],track:function(){this.q.push(arguments)}};</script>
<script src="https://cdn.geoswap.co/geoswap.js" data-project="YOUR_PROJECT_ID" defer></script>Step 2: Create a redirect rule
In the GeoSwap dashboard, navigate to Redirects and click New Geo Redirect.
Page targeting
The pages where the redirect can fire: all pages, a list of exact URLs, or a URL pattern. To run only on one of your domains, use a pattern like ^https?://(www\.)?example\.com/. See Page Targeting for more patterns.
Target countries
Select one or more countries. Visitors from these countries will be redirected. Use explicit matching (select the countries you want to redirect) rather than exclusion rules for best SEO safety.
Destination
Each rule pairs a segment with a destination, and you choose how that destination works:
- Specific URL sends visitors to one fixed page, like
https://example.de/welcome. - Swap domain keeps visitors on the same page but moves them to another domain. With
https://example.in, a visitor on example.com/products/lamp?color=red lands on example.in/products/lamp?color=red. Add a path to put them under a folder:https://example.in/ensends them to example.in/en/products/lamp.
You can mix both in one redirect, for example India on Swap domain and the UK on a Specific URL. Rules are checked top to bottom, and the first one that matches the visitor wins.
Step 3: Configure options
Option
Description
Redirect mode
Automatic sends visitors right away. Popup asks them first, and Notification Bar shows a banner they can click. While the popup or bar is waiting for an answer, the page loads normally but GeoSwap holds its other actions (content swaps, bars, popups, scripts, currency, consent banner). If the visitor stays, those apply right away.
Pass query string to destination
On by default. Keeps tracking parameters like ?utm_source=ad when the visitor is redirected.
Append origin URL to destination
Adds the page the visitor came from as an origin_url parameter, so the destination site can tell where they started.
Add custom URL parameters
Adds your own parameters to every redirect, such as utm_source=geoswap, so you can track redirected visits.
Only redirect on first visit
Sets a cookie so each visitor is redirected once. If they come back to the original page, they can stay there.
Bypass referrers and IPs
Under Advanced Options. Skip the redirect for visitors arriving from certain sites, or from IP addresses like your office, so partners and your team can still reach the original page.
SEO Safety
Googlebot is never redirected
When you use explicit country matching (e.g., "redirect visitors from Germany"), Googlebot does not match any country and sees your original page. This is by design. See the SEO Guide for details.
Avoid "not equal to" rules
Rules like "redirect everyone NOT in the US" will match Googlebot (whose IP resolves to no identifiable country), causing it to be redirected away from your page. Always use explicit country targeting instead. GeoSwap will warn you in the dashboard if you create a rule that could affect search engine crawlers.
Hreflang Tags
When a redirect sends countries to language or country versions of a page, GeoSwap works out the matching hreflang tags for you. These tags tell search engines which version belongs to which audience, so the right one shows up in local results. Copy them from Geo Tools → Hreflang in the dashboard and add them to the <head> of your page. GeoSwap doesn't insert them for you.
Tags are generated for redirects set to Specific URLs whose rules target countries. Swap domain rules are skipped for now, because each page would need its own alternate URL.
Generated hreflang tagshtml
<!-- Generated by GeoSwap (Geo Tools → Hreflang) -->
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="de" href="https://example.de/" />
<link rel="alternate" hreflang="fr" href="https://example.fr/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />You can also use the Hreflang Generator tool in the dashboard to preview and customize the output.
Testing Your Redirects
You do not need a VPN to test geo redirects. GeoSwap provides two ways to simulate a different location:
Dashboard test panel
Each redirect rule has a "Test" button that lets you simulate any country and see exactly what would happen.
Simulate Rules
Use the Rule Simulator tool in your dashboard to test geo-targeting from any country. Pick a country, device, and page to see exactly which rule fires — no VPN needed.
Best Practices
Use explicit country matching (select specific countries), not exclusion rules.
Test with Simulate Rules or a preview link before you go live, so you see exactly where each country lands.
Moving visitors between your own domains (example.com to example.de)? Use Swap domain so they land on the same page instead of the homepage.
Running the same script on several sites? Target the rule with a full-address pattern so it only fires on the site you mean.
Add labels to organize rules when you have many redirects (e.g., by region or campaign).
Review the SEO Check tool in the dashboard after creating rules to catch potential issues.
Next up
Manage redirects at scale with CSV import and edge execution.