IP geolocation

Arcjet provides IP geolocation information in two places:

• Decisions after calling protect() include IP address analysis fields depending on your pricing plan. You can use this to customize responses. See the SDK reference for details e.g. Next.js.
• Filter rules have access to IP address analysis. You can use this to block traffic.

Available fields

Filters	Decision	Free	Starter	Business
ip.src.accuracy_radius	ip.accuracyRadius	🚫	✅	✅
ip.src.city	ip.city	🚫	✅	✅
ip.src.continent.name	ip.continentName	🚫	✅	✅
ip.src.continent	ip.continent	🚫	✅	✅
ip.src.country.name	ip.countryName	✅	✅	✅
ip.src.country	ip.country	✅	✅	✅
ip.src.lat	ip.latitude	🚫	✅	✅
ip.src.lon	ip.longitude	🚫	✅	✅
ip.src.postal_code	ip.postalCode	🚫	✅	✅
ip.src.region	ip.region	🚫	✅	✅
ip.src.timezone.name	ip.timezone	🚫	✅	✅

Caution

IP geolocation can be notoriously inaccurate, especially for mobile devices, satellite internet providers, and even just normal users. Likewise with the specific fields like city and region, which can be very inaccurate. Country is usually accurate, but there are often cases where IP addresses are mis-located. These fields are provided for convenience e.g. suggesting a user location, but should not be relied upon by themselves.

Checking for data

The IP location fields may be undefined, but you can use various methods to check their availability:

// ... imports, client configuration, etc
// See https://docs.arcjet.com/get-started
const decision = await aj.protect(req);

if (decision.ip.hasCity() && decision.ip.city === "San Francisco") {
  // Return a custom response for San Francisco
}

if (decision.ip.hasRegion() && decision.ip.region === "California") {
  // Return a custom response for California
}

if (decision.ip.hasCountry() && decision.ip.country === "US") {
  // Return a custom response for the United States
}

if (decision.ip.hasContinent() && decision.ip.continent === "NA") {
  // Return a custom response for North America
}

Examples

Block all countries except US

Filter rules can be used to block traffic based on IP geolocation:

// …
rules: [
  filter({
    allow: ['ip.src.country eq "US"'],
    mode: "LIVE",
  })
],

// …

const decision = await aj.protect(req);

if (decision.isDenied()) {
  // Return 403 Forbidden
}

Customize response for US

The ip field on a decision can be used to customize the response based on IP geolocation:

// …
const decision = await aj.protect(req);

if (decision.isDenied()) {
  // Handle your other configured rules here.
}

// Otherwise, customize for US:
if (decision.ip.country === "US") {
  return new Response("Hello, US visitor!");
}

Block all regions except California

Filter rules can be used to block traffic based on IP geolocation:

// …
rules: [
  filter({
    allow: ['ip.src.country eq "US" and ip.src.region eq "California"'],
    mode: "LIVE",
  })
],

// …

const decision = await aj.protect(req);

if (decision.isDenied()) {
  // Return 403 Forbidden
}

Customize response for California

The ip field on a decision can be used to customize the response based on IP geolocation:

// …
const decision = await aj.protect(req);

if (decision.isDenied()) {
  // Handle your other configured rules here.
}

// Otherwise, customize for California:
if (decision.ip.country === "US" && decision.ip.region === "California") {
  return new Response("Go California!");
}