What is the Country Matcher?
The Country matcher allows you to create rules that match requests based on the visitor's geographic location. This matcher uses GeoIP lookup to determine the country of origin for each request, enabling you to customize content, implement regional restrictions, or apply country-specific settings.
How Country Matcher Works
The Country matcher evaluates the country of origin for the incoming request using GeoIP technology. Each visitor's IP address is automatically mapped to a country, and this information is used to determine if the rule should be applied.
Country codes follow the ISO 3166-1 alpha-2 standard, which uses two-letter codes to represent countries (e.g., "US" for United States, "GB" for United Kingdom, "JP" for Japan).
Available Operators
The Country matcher supports these comparison operators:
Operator | Description | Example |
| Country matches one of the specified codes |
|
| Country does not match any of the specified codes |
|
| Country is known (any valid country) | Matches any request where the country could be determined |
| Country could not be determined | Matches when GeoIP lookup fails or country information is unavailable |
API Reference
When working with Rules through the API, Country matchers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.
{
"type": "country",
"operator": "is",
"country_codes": ["US", "CA", "MX"]
}
In API requests, this matcher would be included in the matchers array of a rule object:
{
"name": "North America Content Rule",
"active": true,
"matchers": [
{
"type": "country",
"operator": "is",
"country_codes": ["US", "CA", "MX"]
}
],
"handlers": [
// handlers would go here
]
}
For complete API documentation on rules, including how to create and update rules programmatically, refer to our API Documentation.
Example 1: Matching Visitors from Specific Countries
This matcher will match requests from visitors in North America (United States, Canada, and Mexico):
In the UI:
In the API:
{
"type": "country",
"operator": "is",
"country_codes": ["US", "CA", "MX"]
}
Example 2: Excluding Visitors from Certain Countries
This matcher will match requests from visitors anywhere except China and Russia:
In the UI:
In the API:
{
"type": "country",
"operator": "is_not",
"country_codes": ["CN", "RU"]
}
Example 3: Handling Unknown Locations
This matcher will match requests where the country cannot be determined:
In the UI:
In the API:
{
"type": "country",
"operator": "is_unknown"
}
Example 4: Matching Any Known Location
This matcher will match requests from any known country:
In the UI:
In the API:
{
"type": "country",
"operator": "has_any_value"
}
Common Use Cases
Here are some popular ways to use the Country matcher:
Geo-Restricted Content
Limit access to content based on geographic location:
Create a rule with a Country matcher using
is_notoperator for countries where content is restrictedAdd a Static Response handler to return a message explaining why the content is unavailable
Regional Pricing and Currency
Display different pricing or currency based on visitor location:
Create a rule with a Country matcher using
isoperator for specific regionsAdd handlers to rewrite the request to region-specific pages or set headers for your application to use
Compliance with Regional Laws
Implement different privacy notices or cookie policies based on location:
Create a rule with a Country matcher for EU countries (for GDPR) or California (for CCPA)
Add handlers to modify the response with the appropriate privacy notices or cookie controls
Content Localization
Serve localized content based on geographic region:
Create a rule with a Country matcher for language regions
Add handlers to rewrite requests to localized versions or set language preference headers
Handling Proxies and VPNs
Implement special handling for requests with indeterminate locations:
Create a rule with a Country matcher using the
is_unknownoperatorAdd handlers to implement additional verification or specific content for these cases
Combining with Other Matchers
The Country matcher becomes especially powerful when combined with other matchers:
Country + Path: Apply regional restrictions only to certain sections of your site
Country + Method: Check location only for specific HTTP methods
Country + Header: Combine geographic location with browser or device information
Remember that when multiple matchers are used in a rule, ALL must match for the rule to be applied (AND logic).
Best Practices
Use the Country matcher for coarse geographic targeting (country-level only)
Be aware that GeoIP lookups are not 100% accurate and can change over time
Consider privacy regulations when implementing geographic targeting
Provide clear messaging to users when content is restricted by region
For users behind VPNs or proxies, country detection may return unexpected results
Cache responses appropriately when using country-based rules to optimize performance
Consider implementing a fallback or override mechanism for genuine users who might be incorrectly blocked
Troubleshooting
If your Country matcher isn't working as expected:
Verify country codes are in the correct ISO 3166-1 alpha-2 format (two uppercase letters)
Check that you've chosen the correct operator for your use case
Test your rules using a VPN to simulate traffic from different countries
Remember that some users may be using proxies or VPNs that mask their true location
If users are unexpectedly being matched by the
is_unknownoperator, they might be using privacy tools
The Country matcher provides a powerful way to customize content and functionality based on geographic location. By leveraging this matcher, you can implement regional restrictions, localization, and compliance with local regulations without modifying your application code.
Until next time, keep building!
Need more help? Reach out via the Intercom chat widget and we'll be right with you!