Redirect visitors to contextual URLs based on their origin country or continent with ultra-low latency.
Geographic routing optimizes user experience and conversion rates by serving localized content (language, currency, catalog) by country or continent from a single shared link.
Rules evaluation happens directly at Cloudflare Edge nodes during DNS resolution and TLS handshake, ensuring average redirection times under 15 milliseconds without backend server round-trips.
Dynamic routing and geo targeting are exclusive to paid plans (Pro, Business, and Enterprise). Free tier links redirect unconditionally to the primary destination URL.
Core architectural pillars ensuring high performance, isolation, and security.
Ready-to-use TypeScript code snippets and configuration examples for your integrations.
Attach country-based redirection rules to an existing link:
Direct HTTP request methods, parameters schema, authentication, and responses.
Configures or updates country-specific destination rules and global fallback URL for a given short link.
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Required | The short link ID or slug alias. | global-promo |
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| fallbackUrl | string (url) | Required | Default URL used when visitor origin country has no matching rule. | https://store.com/global |
| rules | object[] | Required | Array of country mapping rules. | [{"country": "US", "targetUrl": "https://store.com/us"}, {"country": "DE", "targetUrl": "https://store.com/de"}] |
| rules[].country | string (ISO 3166-1 alpha-2) | Required | Two-letter uppercase country code. | US |
| rules[].targetUrl | string (url) | Required | Target URL for visitors from this country. | https://store.com/us/fall-sale |
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | INVALID_COUNTRY_CODE | Country code must be a valid 2-letter uppercase ISO 3166-1 alpha-2 string. |
| 403 | PLAN_UPGRADE_REQUIRED | Dynamic routing and geo targeting require an active paid subscription (Pro, Business, or Enterprise). |
| 404 | LINK_NOT_FOUND | No link found matching the provided slug or ID. |
Structure returned after updating geographic routing rules:
Expert tips to maximize performance, resilience, and link security.
Ensure your fallback URL is always functional and globally accessible.
To test your rules in staging without a VPN, pass the X-Override-Country: US HTTP header in your test requests.
Regularly review your unrouted countries in the real-time telemetry dashboard to add high-converting regions.
