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 geo IP headers with any framework on Vercel's frontend cloud using the @vercel/edge package.

Installing the geolocation package

@vercel/edge provides the following helpers for use in Edge Functions or Middleware:

• 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:

import { geolocation } from '@vercel/edge';
 
export const runtime = 'edge';
 
export function GET(request: Request) {
  const { city } = geolocation(request);
  // You can also get the city using dot notation on the function
  // const city = geolocation(request).city;
  return new Response(`<h1>Your location is ${city}</h1>`, {
    headers: { 'content-type': 'text/html' },
  });
}

Similar, you can use this package in the Pages Router as well, or when using Vercel Functions with any framework on Vercel:

import { geolocation } from '@vercel/edge';
 
export const config = {
  runtime: 'edge',
};
 
export default function handler(request: Request) {
  const { city } = geolocation(request);
  // You can also get the city using dot notation on the function
  // const city = geolocation(request).city;
  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/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.