Edge Handlers API overview

This feature is in early access BETA.

This guide provides information to get started with the Netlify Edge Handlers JavaScript API. Check out the Edge Handlers API reference documentation for details.

# Fetch

The Fetch API enables sending requests to external endpoints to gather additional data. It works like a browser’s Fetch API, and you can use it to retrieve any kind of data.

Here’s an example using the Fetch API to retrieve data from a URL:

export function onRequest(event) {
  event.replaceResponse(() =>
    fetch("https://api.github.com/emojis", {
      headers: { "User-Agent": "Netlify" },
    })
  );
}

You can also use the Fetch API to get the original request:

export function onRequest(event) {
  event.replaceResponse(({ request }) => fetch(request));
}

For more information, visit the Edge Handlers Fetch API reference.

# Geolocation

The Geolocation API adds location information in the headers of every request that an Edge Handler receives. The geolocation data is available in the request event received in the Edge Handler invocation as well as in the request headers.

You can access the information from the request object by using the origin access method. This method exposes additional country, subdivision, and city access methods. Each of these methods provides access to the area name and to the ISO 3166 code for country and subdivision.

Here’s an example that logs each one of these properties for an incoming request:

export function onRequest(event) {
  console.log(`Request served from ${event.requestMeta.zone}`);

  const origin = event.requestMeta.origin;
  if (origin.country) {
    const { name, code } = origin.country;
    console.log(`country: ${name} (${code || "missing code"})`);
  }

  if (origin.subdivision) {
    const { name, code } = origin.subdivision;
    console.log(`subdivision: ${name} (${code || "missing code"})`);
  }

  if (origin.city) {
    console.log(`city: ${origin.city.name}`);
  }
}

You can access location information from the request headers by using the following keys:

  • X-NF-Country-Name: Name of the country, in English, where the request is coming from. For example, Spain.
  • X-NF-Country-Code: ISO 3166 code of the country where the request is coming from. For example, ES.
  • X-NF-Subdivision-Name: Name of the area or region, in English, where the request is coming from. For example, California.
  • X-NF-Subdivision-Code: ISO 3166 code of the region where the request is coming from. For example, US-CA for California.
  • X-NF-City-Name: Name of the city, in English, where the request is coming from. For example, Seville.
  • X-NF-Availability-Zone: IATA location identifier for the metropolitan area where the Edge Handler is being executed. For example, NYC.

Here’s an example using a header of the Geolocation API to customize a response:

export function onRequest(event) {
  const area = event.requestMeta.headers.get("X-NF-Subdivision-Code");
  if (area === "US-CA") {
    event.replaceResponse(
      new Response("Sorry, not available in California", { status: 404 })
    );
  }
}

For more information, visit the Edge Handlers Geolocation API reference.

# User Context

When an incoming request includes an authentication token from Netlify Identity or an external provider, the Edge Handler will automatically verify the token signature and give you access to its claims and roles directly from the userContext object in the incoming event. This information helps you make informed decisions to grant access to your visitors directly from the handler.

Here’s an example using the userContext object to redirect visitors to a login page based on the token’s role information:

export function onRequest(event) {
  if (!event.userContext?.is("admin")) {
    event.replaceResponse(
      new Response("Access unauthorized", {
        status: 301,
        headers: { Location: "/login" },
      })
    );
  }
}

For more information, visit the Edge Handlers User Context API reference.