--- title: How can I use geolocation IP headers? description: Learn how to read geolocation headers on Vercel with Next.js or any frontend framework. url: /kb/guide/geo-ip-headers-geolocation-vercel-functions canonical_url: "https://vercel.com/kb/guide/geo-ip-headers-geolocation-vercel-functions" published: 2025-11-03 last_updated: 2025-11-10 authors: Lee Robinson related: - /docs/security/vercel-waf - /docs/security/vercel-waf/custom-rules - /docs/security/vercel-waf/rule-configuration - /docs/functions/functions-api-reference - /docs/edge-network/regions - /docs/functions/edge-functions/edge-functions-api install_vercel_plugin: npx plugins add vercel/vercel-plugin --- ## Related pages > **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below. - [API](https://vercel.com/docs/routing-middleware/api?from=related) — Learn how you can use Routing Middleware, code that executes before a request is processed on a site, to provide speed a - [Request Lifecycle](https://vercel.com/docs/fundamentals/infrastructure?from=related) — Learn how Vercel routes, secures, and serves requests from your users to your application. - [Functions](https://vercel.com/docs/functions?from=related) — Run server-side code on Vercel without managing a server. - [Node.js](https://vercel.com/docs/functions/runtimes/node-js?from=related) — Learn how to use the Node.js runtime to create functions and deploy Node.js servers on Vercel. - [How Vercel CDN works](https://vercel.com/docs/how-vercel-cdn-works?from=related) — Learn how Vercel's CDN processes requests through routing, caching, and compute layers to deliver your content with low - [How to Configure the Cache-Control Response Header in Vercel Projects](https://vercel.com/kb/guide/how-to-configure-the-cache-control-response-header-in-vercel-projects?from=related) — After reviewing this guide, you will be able to set a cache-control header of any value to be returned when a specific p - [Migrate to Vercel from Netlify](https://vercel.com/kb/guide/migrate-to-vercel-from-netlify?from=related) — Migrate your website's configuration from Netlify to Vercel - [How can I enable CORS on Vercel?](https://vercel.com/kb/guide/how-to-enable-cors?from=related) — Learn how to add CORS headers to your application on Vercel. - [Using PostHog with the Next.js App Router and Vercel](https://vercel.com/kb/guide/posthog-nextjs-vercel-feature-flags-analytics?from=related) — Learn how to use PostHog with Next.js and Vercel to add analytics, feature flags, and more. - [How can I allowlist IP addresses for a deployment?](https://vercel.com/kb/guide/how-to-allowlist-deployment-ip-address?from=related) — You can securely connect a deployment to external services by using a stable set of IP addresses. Full cross-link map for this page: [/kb/guide/geo-ip-headers-geolocation-vercel-functions.graph.md](/kb/guide/geo-ip-headers-geolocation-vercel-functions.graph.md) Vercel enables you to read a visitor's geolocation or IP address inside of Vercel Functions or Vercel Edge Middleware, enabling you to show localized content or block malicious IPs. You can also use the Vercel [Web Application Firewall (WAF)](https://vercel.com/docs/security/vercel-waf) to block IPs from a specific geolocation by configuring a [custom rule](https://vercel.com/docs/security/vercel-waf/custom-rules#get-started) with the request [parameters](https://vercel.com/docs/security/vercel-waf/rule-configuration#parameters) of continent, state, country and city. This guide will show how to read geolocation IP headers with any framework on Vercel. > This feature does not work if you're using a proxy in front of your deployment. However, Enterprise customers can purchase and enable Trusted Proxy to override this behavior. If you're interested, please [contact us](https://vercel.com/contact/sales) for more details. ## Geolocation Headers All Vercel deployments include the following geolocation headers: - `X-Vercel-IP-Country` – The 2-letter country code of the IP sending the request. - `X-Vercel-IP-Country-Region` – The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) region code associated to the IP. - `X-Vercel-IP-City` – The city name associated to the IP. > When testing locally, the geolocation headers will not be set. You can only view geolocation information after making a deployment and reading the incoming request headers. ## Installing the geolocation package [`@vercel/functions`](https://vercel.com/docs/functions/functions-api-reference) provides the following helpers for use in Vercel Functions or Vercel Edge Middleware, built on top of the geolocation headers: - `geolocation`: Returns the location information for the incoming request. - `ipAddress`: Returns the IP address of the request from the headers. These can be used with any framework and allow you to read geo IP headers. To get started, add `@vercel/functions` to your project. ## Using the geolocation helper The `geolocation` helper returns location information for an incoming request. It takes a request object as input and returns properties such as city, country, latitude, longitude, and region ([Vercel Edge Network region](https://vercel.com/docs/edge-network/regions) that received the request). Each property is returned as a string or `undefined`. Here's an example code snippet demonstrating how to use it within the Next.js App Router and Route Handlers: ```tsx import { geolocation } from '@vercel/functions'; export function GET(request: Request) { const { city } = geolocation(request); return new Response(`

Your location is ${city}

`, { headers: { 'content-type': 'text/html' }, }); } ``` We recommend using the above for both Pages and App Router applications (both directories can exist together). When using Vercel Functions with any framework on Vercel, you can do the following: ```tsx import { geolocation } from '@vercel/functions'; export function GET(request: Request) { const { city } = geolocation(request); return new Response(`

Your location is ${city}

`, { headers: { 'content-type': 'text/html' }, }); } ``` In the above example, we import the `geolocation` helper from `@vercel/functions`. We then call it with the incoming request object and extract the city property. Finally, we return a response containing the extracted city information. ## Further Reading By leveraging the power of geo IP headers with Vercel, you can create dynamic and personalized experiences for your users based on their location. Whether it's displaying localized content or implementing custom logic based on geographic data, these helpers provide a convenient way to achieve geolocation functionality in your Vercel projects. For more details on using geo IP headers with Vercel for geolocation in Vercel Functions and Middleware, refer to [Vercel documentation](https://vercel.com/docs/functions/edge-functions/edge-functions-api#geolocation). You can also [clone and deploy an example](https://edge-functions-geolocation.vercel.sh/) to see the geo IP headers in action.