How can I use geolocation IP headers?

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.

This guide will show how to read geolocation IP headers with any framework on Vercel.

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 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/edge 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/edge 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 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:

app/api/edge-geo/route.ts
import { geolocation } from '@vercel/edge';
export const runtime = 'edge';
export function GET(request: Request) {
const { city } = geolocation(request);
return new Response(`<h1>Your location is ${city}</h1>`, {
headers: { 'content-type': 'text/html' },
});
}
Reading the city from the geo IP headers in a Vercel Edge Function.

Similar, you can use this package in the Pages Router as well, or when using Vercel Functions with any framework on Vercel (e.g. api/edge-geo.ts):

pages/api/edge-geo.ts
import { geolocation } from '@vercel/edge';
export const config = {
runtime: 'edge',
};
export default function handler(request: Request) {
const { city } = geolocation(request);
return new Response(`<h1>Your location is ${city}</h1>`, {
headers: { 'content-type': 'text/html' },
});
}
Reading the city from the geo IP headers in a Vercel Edge Function.

In the above example, we import the geolocation helper from @vercel/edge. 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 Edge Functions and Middleware, refer to Vercel documentation. You can also clone and deploy an example to see the geo IP headers in action.

Couldn't find the guide you need?