Location on every request, without an API call.
Server-side tags routinely need to know where a visitor is. Getting there usually means calling a geo API from inside your container, paying per lookup and adding latency to every event. This module resolves location at the gateway and delivers it as four headers.
203.0.113.42resolved locallyHeaders are empty when an address cannot be resolved, your tags branch on a blank value rather than acting on a guess.
Address in, location out
Not available yet
This module is built and documented, but the underlying data plane is still being rolled out across our clusters. It will appear in your console the moment it goes live.
Location is expensive in the wrong place
Resolving geography from inside a container means a network call on the critical path of every event, a vendor contract, and an IP address you have to keep around long enough to send.
Every lookup is a network round trip
An external call inside your tag path adds latency to each event and introduces a dependency that can fail or rate-limit you at the worst moment.
It forces you to keep the IP
To resolve location in your container you must first receive the address there, which is precisely what a privacy-led setup is trying to avoid.
Per-lookup pricing scales badly
Geo APIs bill per request. On a high-traffic site that becomes a real line item for data you could have resolved once, at the edge.
How it works
The gateway resolves the client address against a local geo database and appends four headers before the request reaches your container.
Resolved locally
The lookup runs against a database held at the gateway. There is no outbound call and no third party in the request path.
Four headers
X-Geo-Country carries an ISO 3166-1 alpha-2 code, X-Geo-Region an ISO 3166-2 subdivision code, X-Geo-City the English city name, and X-Geo-Postal-Code the postal code.
Resolved before anonymisation
Location is derived from the real address before the Anonymizer rewrites the IP headers. Enable both and your tags get coarse location while your container never sees an address.
Empty rather than wrong
When an address cannot be resolved the headers are empty, so your tags can branch on a blank value instead of acting on a guess.
What you get
Standardised codes
Country and region arrive as ISO codes rather than free text, so they can be joined and filtered without normalisation.
No per-lookup cost
There is no metered API behind this. Location arrives on every request at no additional charge.
No latency added
A local database lookup at the gateway costs microseconds, against tens of milliseconds for a remote call.
Pairs with the Anonymizer
Coarse location and no IP address is the combination most privacy reviews are looking for, and these two modules produce it together.
Specification
- X-Geo-Country
- ISO 3166-1 alpha-2, for example NL
- X-Geo-Region
- ISO 3166-2 subdivision, for example NH
- X-Geo-City
- City name in English
- X-Geo-Postal-Code
- Postal code where available
- Settings
- None, the header set is fixed
When to use it
You need geography for conversion APIs
Meta and other conversion APIs accept location fields that improve match quality. Passing them from a header is cheaper than resolving them per event.
You route tags by market
Fire different vendors, or different consent logic, per country without an extra client-side lookup that a blocker can prevent.
You want regional reporting without IPs
Combined with the Anonymizer, your reporting keeps location while your container never receives an address to begin with.
Questions about GEO Headers
When will this be available?
The module is built and the header contract is final. We are rolling out the geo data plane across our clusters, and it will appear in your console as soon as that is complete on the cluster hosting your container.
How accurate is city and postal-code data?
Country accuracy is very high. City is generally reliable in dense urban areas and less so elsewhere, and postal code should be treated as a hint rather than a fact. This is inherent to IP-based geolocation, not specific to us.
Does it work together with the Anonymizer?
Yes, and that is the recommended pairing. Location is resolved from the real address before the Anonymizer rewrites the headers, so your tags get geography and your container never receives an IP address.
Other modules
Modules stack. Enable as many as you need. They compose into one configuration in front of your container.
Ready to switch it on?
Every module is included with your container at no extra cost. Create a container, open the modules panel, and toggle.