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.

Installing the geolocation package

@vercel/functions 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 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:

import { geolocation } from '@vercel/functions';
 
export function GET(request: Request) {
  const { city } = geolocation(request);
  return new Response(`<h1>Your location is ${city}</h1>`, {
    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:

import { geolocation } from '@vercel/functions';
 
export function GET(request: Request) {
  const { city } = geolocation(request);
  return new Response(`<h1>Your location is ${city}</h1>`, {
    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. You can also clone and deploy an example to see the geo IP headers in action.