DEV Community: ABDULLAH AFZAL

Card Testing Fraud: How the $1 Charge Storm Works and How to Stop It

ABDULLAH AFZAL — Wed, 15 Jul 2026 11:39:42 +0000

Card testing fraud turns your donation form into a free validator for stolen cards. Someone fires hundreds of tiny charges through it, watches which ones approve, and walks away with a verified list to resell or cash out somewhere else. You keep the chargebacks, the fees, and a payment processor that now thinks you are the risky one.

Donation forms are especially attractive targets because many accept arbitrarily low amounts with little friction. No cart, no shipping address, often no minimum. A donor can give $3.50 or $1.00, so a script giving $1.00 five hundred times does not look obviously wrong until the disputes land. The result can look like a $1 charge storm: a sudden spike of tiny authorizations and declines.

TL;DR

Card testing means submitting stolen card details through payment, authorization, or card-setup flows to determine which credentials are valid. Small payments are common, but a visible charge is not always required.
The attacker studies the authorization result and any exposed decline details. An approval confirms that the card can transact, while some decline responses can still confirm that the card number or other supplied details are valid; the money is incidental.
Donation forms are prime targets because they accept arbitrarily low amounts with little friction.
No single control stops it. You need layers: form controls, request-rate controls, and your payment processor's risk engine.
Your processor’s card-testing protections and risk engine are essential transaction-level defenses. Application controls should stop as much automated testing as possible before it reaches the payment rails.
IP reputation is a useful triage signal (is this a datacenter, a known proxy, a VPN?), not a wall. It is one input to a score, and it is evadable.
Do not rely on a single-IP or country block as your primary defense. Both can create false positives and do little against distributed traffic.

Card testing is an automated attack that abuses the low friction of a donation form to check stolen cards. Stopping it is a layering problem, not a single-tool problem: reduce the bot volume up front, let your processor's risk engine judge what remains, and use IP signals to decide who gets extra friction rather than who gets a door slammed on them.

What a card-testing attack actually is

Fraudsters buy stolen card numbers in bulk, but an untested list is less valuable because many of its cards may already be canceled, expired, frozen, or otherwise unusable. Testing sorts the live ones from the dead ones. The attacker submits each card through a payment, authorization, or card-setup flow and reads the response: an approval confirms a usable card, while a detailed decline can still reveal which part of the credential set is valid or incorrect. Stripe describes this plainly in its guide to card testing: the goal is validation, and the transaction amount barely matters.

That is why a $1.00 donation is an attractive testing method. The attacker is not trying to steal your $1.00. They are using your form as a credential-validation oracle, and a working card gets cashed out later at a merchant that sells something resellable.

Why donation forms are the perfect target

A checkout page often has more friction built in: a cart, a fixed product, sometimes an account, and billing or shipping details. Where supported, AVS can compare the billing address or postal code with the information held by the card issuer. A donation form strips most of that away on purpose, because friction kills donations. The same design that helps real donors helps the bot.

WooCommerce says it directly in its card-testing guidance: avoid pay-what-you-want or donation products with no minimum, because fraudsters use small arbitrary amounts that a cardholder may never notice. If transaction monitoring is weak, a low-value spike may go unnoticed until cardholders begin reporting the charges. Individual payments may also be small enough that cardholders do not report them immediately.

Anatomy of the $1 charge storm

The attack often has a recognizable pattern, although more sophisticated campaigns deliberately distribute their traffic to weaken these signals.

The card list and the bot

The attacker starts with a list, often generated or bought, sometimes built by guessing card numbers within a known BIN range (the first digits that identify the issuing bank). They point an automated script at your form. It runs from wherever compute is cheap and disposable: a rented cloud box, a pool of commercial proxies, sometimes a botnet of compromised residential machines so the traffic looks like real people.

The validation run

Then it fires. Dozens or hundreds of submissions in a short window, each a small donation, each a different card. The bot does not care about your thank-you page. It cares about the API response behind it. Approvals get flagged as usable cards. Declines are inspected for details that may reveal whether the card number, expiration date, CVC, or other supplied information was valid. If your form supports guest donations and does not challenge anything, the whole run can finish before anyone logs in.

In your logs it has a signature: a burst of attempts clustered in minutes, the same one or two donation amounts repeated, a high decline rate mixed with a few approvals, many distinct payment methods, sometimes concentrated within a small set of networks, devices, accounts, or sessions. If you graph transactions per minute, the storm is a spike relative to the form’s normal transaction baseline.

What happens after

The live cards move on to a real cash-out somewhere else, and your side of it may begin days or weeks later, when cardholders report the transactions and disputes start arriving.

What it actually costs you

If it were just noise, you could ignore it. It is not.

Each unauthorized test payment that becomes a dispute can add reversal costs, dispute fees, and operational work far beyond the original transaction amount. A flood of $1.00 tests can therefore cost far more than it ever donated. JPMorgan's merchant guidance on card testing makes the sharper point: the real damage is upstream. A high rate of small declines and disputes pushes your authorization decline rate up and can trigger additional scrutiny from your acquirer or payment partners, which can mean review, held funds, higher processing costs, or in a bad case losing the account. Stripe's own card-testing documentation warns that testing activity can degrade how the network sees you.

There is a quieter cost too. Cardholders may contact your organization after noticing unfamiliar charity charges, your support inbox fills up, and your reputation takes a hit.

The defense stack, and where each layer stops the attack

The mental model that helps most: an attack can be stopped at three points, and JPMorgan frames the goal well, which is to stop it before it reaches the acquirer. The earlier you intervene, the cheaper it is.

At the form

This is where you cut raw bot volume. A challenge on suspicious sessions (a CAPTCHA or an invisible bot check) can stop many basic automated scripts. A honeypot field that humans never see but bots fill in is close to free. One useful donation-specific control is a sensible minimum amount. It raises the cost of successful tests, but the threshold should reflect your normal donation patterns and should not be treated as a complete defense. Stripe's prevention guidance leads with the same three: restrict access to the form, add a CAPTCHA, and rate limit.

The gotcha with CAPTCHA: it is not a wall by itself. Solving services and more capable bots can bypass it, while CAPTCHA itself can add friction and reduce completion rates. Use it on risky sessions, not on everyone.

At the request

Here you cap how fast anything can hit the endpoint. Combine conservative IP and subnet velocity limits with session, account, email, device, and processor-level signals. Avoid hard subnet limits that could block users behind shared carrier or corporate networks. Cap attempts per session, account, email address, and processor-provided payment-method fingerprint or identifier. Do not store or log raw card numbers for rate limiting. If ten cards get tried from one network in thirty seconds, that is not a donor changing their mind.

At the processor

This is the transaction-level backstop. Stripe’s recommended integrations include automated card-testing protections such as rate limiters, risk models, and CAPTCHA triggers. These protections are separate from Radar’s fraudulent-dispute controls, although they use overlapping risk factors. Your processor can also evaluate payment, issuer, and network signals that your application cannot see. Use its recommended integration, collect CVC and billing information where supported, evaluate AVS as one signal, and apply risk-based 3DS where appropriate.

The IP layer, and why most advice about it is wrong

Almost every "how to stop card testing" list includes two IP tips: block the attacker's IP, and block transactions from outside your country. Neither is sufficient as a primary card-testing defense, and broad country rules can create false positives.

Blocking a single IP does little against a bot that rotates through a proxy pool or a residential botnet; you will be playing whack-a-mole against a new address every few seconds. Broad country blocking can also punish legitimate donors, especially when the organization accepts international support. A diaspora nonprofit takes real donations from exactly the countries a blunt geo-block would cut off. And plenty of legitimate traffic looks "foreign" or "anonymous" when it is not: someone donating through a corporate VPN that exits in another country, or an iPhone user on iCloud Private Relay, or Chrome's IP Protection. Treat those as attackers and you have quietly turned away real money.

Think of a supporter in Berlin who donates every year through their employer's VPN, which exits in Amsterdam. A country block or an “anonymous, deny” rule could lose that donation and never tells you why.

The signals that actually predict card testing

IP data is useful when you stop using it as a blocklist and start using it as a risk input. The signals that correlate with card testing are not "which country," they are "what kind of network":

Is the IP a datacenter or hosting provider? Hosting infrastructure is unusual for an ordinary donor’s browser session and can justify additional scrutiny, but it is not conclusive evidence of fraud. Card-testing bots can originate from rented cloud or hosting infrastructure.
Is it a known commercial proxy or VPN, and with what confidence? A high-confidence match to a datacenter proxy service is a strong signal; a low-confidence VPN guess is not.
Is it a residential proxy? This is the hardest case, because the traffic looks like a home connection. Residential-proxy detection is valuable because ordinary proxy checks may classify the connection as normal residential traffic.
Is it a relay (iCloud Private Relay, Chrome IP Protection)? A relay should not raise suspicion by itself. Treat it as neutral and continue evaluating the remaining signals. Relays are used by ordinary people.
Is there a velocity or geo anomaly? Many cards from one ASN in a minute, or a single session hopping continents, is the pattern to score on.

Several services expose some combination of these signals: IPQS, MaxMind minFraud, proxycheck.io, and IPGeolocation among them. Pick by whether they give you residential-proxy detection, provider attribution, and a confidence score, not just a raw boolean, because "it is a proxy" is less actionable than "it is associated with Zyte Proxy, with confidence 80 and a reported last-seen date". For the examples here I am using ipgeolocation.io's IP Security API because its response carries the provider names and confidence scores I want to score on, and a trial is available for testing the integration before using it in production.

A lookup against the dedicated /v3/security endpoint returns the full picture. Here is the real documented response for 2.56.188.34, which is a useful documented example of a high-risk response:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

That is what you want to score on: a threat_score of 80, a named proxy (Zyte Proxy) with a confidence of 80 and a reported proxy_last_seen date, a hosting flag with the provider (Packethub S.A.), and is_known_attacker set. A country-only rule would not explain or distinguish any of those network-risk signals. Note the security lookup costs 2 credits per call, so cache and rate-limit your own lookups too.

Turning a signal into a decision

The point is not to block on any single flag. It is to fold the score into your existing risk logic and decide how much friction a session earns. High score, block or hold. Middle score, add a challenge or a 3-D Secure step-up. Low score, let it through. And a relay is not a strike against anyone.

// Node 18+.
// The IP check is one input; payment-provider controls still evaluate the transaction.

const IPGEO_KEY = process.env.IPGEO_API_KEY;

if (!IPGEO_KEY) {
  throw new Error("IPGEO_API_KEY is required");
}

async function assessIp(ip) {
  const url = new URL("https://api.ipgeolocation.io/v3/security");
  url.searchParams.set("apiKey", IPGEO_KEY);
  url.searchParams.set("ip", ip);

  try {
    const res = await fetch(url, {
      signal: AbortSignal.timeout(1500)
    });

    if (!res.ok) {
      throw new Error(`security lookup returned HTTP ${res.status}`);
    }

    const sec = (await res.json())?.security ?? {};
    const score = Number(sec.threat_score ?? 0);

    // Illustrative thresholds only.
    // Tune them using legitimate-traffic and fraud outcomes.
    if (score >= 80 || sec.is_known_attacker) {
      return { action: "block", reason: "high risk", score };
    }

    const highConfidenceProxy =
      sec.is_proxy &&
      !sec.is_relay &&
      Number(sec.proxy_confidence_score ?? 0) >= 80;

    if (score >= 45 || sec.is_cloud_provider || highConfidenceProxy) {
      return {
        action: "challenge",
        reason: "needs friction",
        score
      };
    }

    return {
      action: "allow",
      reason: sec.is_relay
        ? "relay without additional risk signals"
        : "low risk",
      score
    };
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    console.warn(`IP assessment skipped for ${ip}: ${message}`);

    // Fail open for this enrichment layer only.
    // The payment processor still evaluates the transaction.
    return {
      action: "allow",
      reason: "lookup unavailable"
    };
  }
}

Two things that trip people up here. First, get the client IP right. Behind a proxy or CDN, configure Express’s trust proxy setting to match your actual infrastructure, then use req.ip. Do not parse the raw X-Forwarded-For header yourself or blindly trust every proxy hop. Second, decide your failure mode on purpose. For a donation flow I fail open, because rejecting real donors when a third-party API blips is worse than letting one risky session reach a processor that is already scoring it. A login or a payout might fail closed instead. State the choice; do not let it be an accident.

And the honest ceiling: none of this is a wall. A residential proxy or a real-device botnet can make a bot look like a home broadband donor, and IP signals will shrug. That is expected. The IP layer buys you cheap triage, so the obvious junk gets blocked or challenged before it ever reaches your processor, and the processor's model handles the harder cases. Anyone selling IP reputation as a complete card-testing fix is overselling it.

Putting it together: a resilient donation form

Walk two sessions through the finished stack.

A real donor from Berlin on their corporate VPN hits the form. The IP looks like a VPN but the threat score is low and it is not a hosting range, so they get a CAPTCHA at worst, pass it, give $25.00, CVC and billing-address checks pass, done. Mildly annoying, not blocked.

A testing bot from a rented server hits the same form. It trips the velocity controls, and the IP lookup returns a high threat score with cloud-hosting and known-attacker signals, so the application blocks the request. Any attempts that still reach the payment processor are evaluated by its card-testing and fraud controls. The layers reduce the volume and impact of the attack before it becomes a flood.

Same form, very different outcomes, because the layers each did one job.

A few things people get wrong

Broad country blocking can feel decisive but often creates avoidable false positives. You lose legitimate international donors and a rotating botnet barely notices. Score on network type and behavior instead of geography.

CAPTCHA alone is not a solution. It stops lazy scripts and gets solved or bypassed by better ones, and a hard challenge on every donor costs you real gifts. Reserve it for risky sessions.

"Just block the IP" does not scale against address rotation. Rate limit by subnet and fingerprint, and lean on your processor for the transaction-level call.

And IP data is not enough on its own, which is the whole point of this article. It is one honest layer. The minimum amount, the request-rate caps, and the processor's risk engine are doing the heavy lifting; the IP signal just tells you who deserves a second look.

Where to start

Consider a sensible minimum that reflects your normal donation patterns, combine per-IP and per-session velocity controls, and use the card-testing protections recommended by your processor. Then add an IP risk check to decide who gets a challenge versus a clean path, and fail open for this enrichment layer so a timeout does not reject a donor by itself.

How to Detect and Block Price Scrapers by IP

ABDULLAH AFZAL — Thu, 09 Jul 2026 19:10:36 +0000

A competitor's bot can pull your entire fare table or product catalog in the time it takes a real customer to pick a seat. It hits the same route search or category page every few seconds, reads your prices, and quietly undercuts you on a comparison site an hour later. Blocking it is harder than it sounds, because the bot you want to stop does not look like one request from one machine. It looks like a thousand requests from a thousand residential IPs.

This is a guide to the cheapest, fastest layer of that defense: scoring every incoming request by its IP before it touches your catalog. You will build middleware that flags datacenter traffic, VPNs, and residential proxies, assigns each request a risk score, and decides whether to serve, slow, challenge, or block. It runs in Node, and it is honest about the one thing IP scoring cannot do on its own.

TL;DR

Price and fare scrapers rotate through datacenter and residential IPs, so no single signal catches them. Treat detection as layers.

The IP layer is first because it is cheap and it kills the lazy majority: bulk scrapers running from AWS, Hetzner, and commercial proxy pools.

Score each request with a 0-100 threat value plus specific flags (is_residential_proxy, is_cloud_provider, is_vpn), then tier your response instead of hard-blocking.

Cache the verdict per IP. Scoring the same address on every request is a waste of budget and latency.

Residential proxies that look like real ISP customers are where IP scoring runs out. That is a job for the behavioral layer above it, not a reason to skip the IP layer.

Datacenter and proxy detection stops the bulk scrapers immediately. Residential-proxy and VPN flags plus a risk score let you make graded decisions on the harder traffic. What you will not get is a magic boolean that ends scraping forever, and any tool that promises one is selling you something. By the end you will have a working IP-scoring layer and a clear picture of where the next layer has to take over.

Why price and fare scrapers are hard to stop

What the traffic actually looks like

Picture two real cases. A metasearch competitor wants your airline's fares, so it runs a bot that searches one popular route, say JFK to LHR, every thirty seconds, all day, from a rotating pool of IPs. Each individual request looks like a shopper checking a flight. In aggregate it is a machine reading your entire price surface. Now picture a flash sale on a retail site: an inventory-hoarding bot dumps every discounted SKU into carts to make them unavailable, then resells the reservation. Snowplow, which sees bot patterns across more than two million sites, describes the marketplace version as short-session crawlers that hit a single listing and disappear, which is exactly the shape that slips past rules built for slow human browsing.

The common thread is IP diversity. Modern scrapers do not hammer you from one address. They rent access to datacenter ranges and, increasingly, residential proxy networks that route requests through real consumer devices. DataDome, whose whole business is stopping this, puts it plainly: simple IP-based rate limiting fails against scrapers using residential proxies and rotation. That sentence is the reason this article is about scoring IPs, not banning them.

Why a single signal fails

Each obvious defense has an obvious counter, and scraper operators know all of them.

Rate limit per IP, and they rotate IPs. User-agent filtering catches the scraper that announces itself as python-requests, and misses the one that copies a real Chrome string, which is most of them. A static blocklist of known-bad IPs is stale the day after you build it. Even the biggest bot-management vendors agree on this point: HUMAN Security's framing is that no single method catches every bot, and each technique exists to cover the gaps in the others. That is not a disclaimer. It is the design principle.

The layered model

So you stack layers, cheapest and broadest first, most expensive and most precise last:

IP intelligence. Score the source address. Catches bulk datacenter and commercial-proxy scrapers for almost nothing. This article.
Rate limiting. Assume rotation and key limits on something better than a bare IP.
Behavioral signals. Request cadence, headers, interaction patterns. This is where residential-proxy scrapers that survived layer one get caught.
Honeypots. Traps a human never triggers and a naive crawler does.

The point of leading with IP is economics. A datacenter check costs one API call and a few milliseconds, and it removes the large, lazy majority of scraper traffic before any of your more expensive analysis runs. You spend your compute budget on the traffic that survives the cheap filter.

Layer 1: score the IP before you do anything else

What IP intelligence catches, and what it misses

IP scoring is good at three things. It spots datacenter and cloud origins, because a checkout request from an AWS or Hetzner range is almost never a real shopper. It spots known commercial VPNs and proxies, because those exit nodes get enumerated and catalogued. And it spots residential proxies, the hardest category, when the provider has been identified through behavioral profiling and honeypot data.

What it misses: a brand-new residential proxy exit that nobody has flagged yet, and a low-and-slow scraper running from a clean home connection at human speed. Those exist, they are a minority of scraper traffic by volume, and they are the reason layers two and three are not optional. Being clear about this up front is the difference between a defense you can reason about and a false sense of security.

The fields that matter

A useful IP intelligence response is not a single yes/no. It is a set of specific flags plus a risk score, and the specificity is the point. Here is the security block for 2.56.188.34, an IP that happens to be flagged across several categories at once, returned from ipgeolocation.io's include=security lookup:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

Read what that gives you beyond "bad or not." is_residential_proxy is separate from is_vpn, so you can treat a NordVPN user (often a privacy-conscious real person) differently from traffic riding a residential proxy network (much more likely to be scraping or fraud). proxy_provider_names names the operator, so "Zyte Proxy" (a commercial scraping service) can trigger a harder rule than an unknown one. is_relay is broken out on its own, which matters because iCloud Private Relay is not a threat and blocking it means blocking a chunk of ordinary Apple users. And the confidence scores let you set your own bar: act on a 90 differently than a 40.

The provider attribution and confidence scores are the fields most detection APIs skip. A bare is_vpn: true forces you to guess. is_vpn: true, vpn_provider_names: ["Nord VPN"], vpn_confidence_score: 80 lets you write a rule you can defend.

Threat-score decisioning

The threat_score is a 0-100 aggregate of the individual signals. Do not wire it as a binary. The whole reason to have a graded score is to take graded action, which matters enormously when most flagged IPs on a busy site carry low-to-moderate risk and a hard block on all of them will catch real customers.

A sane starting policy, which you then tune against your own traffic:

Threat score	What it usually means	Action
0-19	No meaningful risk signal	Allow, no friction
20-44	Something worth watching	Allow, log, maybe soft rate-limit
45-79	Elevated: proxy or VPN with decent confidence	Challenge (CAPTCHA or step-up)
80-100	Datacenter proxy, known attacker, stacked signals	Block or send to manual review

The travel angle makes the tiering concrete. A logged-in customer on a corporate VPN scoring in the 40s should hit a challenge on checkout, not a wall, because blocking them loses a booking. A request from a commercial scraping proxy scoring 80 on your fare-search endpoint gets nothing. Same score field, different action, because the response is tuned to what a false block actually costs on that route.

Build it: IP-scoring middleware

Enough theory. The setup is one API call per uncached IP. Grab a key from ipgeolocation.io's IP security API; the free tier covers geolocation, but the security flags and threat score are on the paid plans, and the security module adds credits per lookup (a base lookup is 1 credit, include=security brings the request to 3), so caching is not optional at any real volume. I am using it here because it returns the datacenter, VPN, proxy, residential-proxy, and threat-score fields in one response, which keeps the example short. ipinfo, IP2Location, and IPQualityScore return overlapping data; the middleware pattern below is the same whichever you pick, so swap the client if you already have one in your stack.

See the response first

Before writing any code, confirm what you get back. One curl call, keeping the response trimmed to the security object:

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=2.56.188.34&include=security&fields=security'

include=security turns on the security module, fields=security trims everything else so you are not paying attention to location data you do not need here. Check the X-Credits-Charged response header on the first call so the per-request cost is never a surprise on your bill.

The Express middleware

Here is the core: middleware that scores the client IP and attaches a verdict to the request. Every downstream handler can then read req.ipRisk and decide what to do.

// ip-risk.js
// Scores the client IP via ipgeolocation.io and attaches a verdict to req.
// Requires Node 18+ (global fetch). Set IPGEO_API_KEY in your environment.

const API_KEY = process.env.IPGEO_API_KEY;
if (!API_KEY) {
  // Fail loudly at startup, not silently on the first request.
  throw new Error("IPGEO_API_KEY is not set");
}

const ENDPOINT = "https://api.ipgeolocation.io/v3/ipgeo";

// Map a security object to an action. Tune these bands against your own traffic.
function decideAction(security) {
  if (!security) return "allow"; // No data: fail open, decide upstream.

  const score = typeof security.threat_score === "number" ? security.threat_score : 0;

  // Hard signals that justify a block regardless of the aggregate score.
  if (security.is_cloud_provider || security.is_known_attacker) return "block";

  if (score >= 80) return "block";
  if (score >= 45) return "challenge";
  if (score >= 20) return "monitor";
  return "allow";
}

async function scoreIp(ip) {
  const url = `${ENDPOINT}?apiKey=${API_KEY}&ip=${encodeURIComponent(ip)}&include=security&fields=security,asn`;

  // Time out fast. A slow lookup should never hold up a checkout page.
  const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
  if (!res.ok) {
    throw new Error(`ipgeo lookup failed: ${res.status}`);
  }
  const body = await res.json();
  return {
      security: body?.security ?? null,
      asn: body?.asn ?? null,
  }; // Optional chaining: the object may be absent.
}

async function ipRisk(req, res, next) {
  const ip = clientIp(req);
  try {
    const scored = await scoreIp(ip);
req.ipRisk = {
  ip,
  security: scored.security,
  asn: scored.asn,
  action: decideAction(scored.security),
};
  } catch (err) {
    // Fail OPEN: if the risk service is down, do not take the whole site down
    // with it. Log, allow, and let a later layer catch anything egregious.
    console.error(`IP risk scoring failed for ${ip}:`, err.message);
    req.ipRisk = { ip, security: null, action: "allow" };
  }
  next();
}

module.exports = { ipRisk, decideAction };

Two decisions in there are worth calling out because getting them wrong is common. The lookup times out at 1500ms so a slow third-party call cannot stall a page a customer is waiting on. And the catch block fails open: if the scoring service is unreachable, the request is allowed rather than blocked. On a checkout path, failing closed would mean an outage at your provider becomes an outage at your store, which is almost never the trade you want. If you are protecting something where the opposite is true (an internal admin route, say), flip that default deliberately and comment why.

Getting the client IP right

clientIp() above is not a throwaway. Behind a load balancer or CDN, req.socket.remoteAddress is your proxy, not the visitor, so you have to read the forwarded header, and you have to trust it only from your own infrastructure.

// The header is trivially spoofable by the client. Only trust it when the
// request actually came through a proxy you control. In Express, configure
// app.set('trust proxy', ...) to match your infra, then use req.ip.
function clientIp(req) {
  // req.ip respects your 'trust proxy' setting. Prefer it over parsing headers by hand.
  if (req.ip) return req.ip;

  const fwd = req.headers["x-forwarded-for"];
  if (typeof fwd === "string" && fwd.length > 0) {
    // Left-most entry is the original client when the chain is trusted.
    return fwd.split(",")[0].trim();
  }
  return req.socket?.remoteAddress ?? "0.0.0.0";
}

If you skip the trust proxy configuration, one of two things breaks: you either score your own load balancer's IP on every request (and see uniform, useless verdicts), or you trust a header an attacker can set to 8.8.8.8 to look clean. Configure it once to match your actual proxy chain and read req.ip.

Cache the verdict

An IP's risk profile does not change between two requests a second apart, so scoring it twice is wasted money and latency. Cache the verdict with a sane TTL. Redis if you have it, an in-process LRU if you do not.

// cache.js — thin Redis-backed cache for IP verdicts.
const { createClient } = require("redis");

const client = createClient({ url: process.env.REDIS_URL });
client.on("error", (err) => console.error("Redis error:", err.message));
client.connect().catch((err) => console.error("Redis connect failed:", err.message));

const TTL_SECONDS = 60 * 60 * 6; // 6 hours. Long enough to save calls, short enough to stay fresh.

async function getCached(ip) {
  try {
    const raw = await client.get(`iprisk:${ip}`);
    return raw ? JSON.parse(raw) : null;
  } catch (err) {
    // Cache failure must not break scoring. Return a miss and move on.
    console.error(`cache read failed for ${ip}:`, err.message);
    return null;
  }
}

async function setCached(ip, verdict) {
  try {
    await client.set(`iprisk:${ip}`, JSON.stringify(verdict), { EX: TTL_SECONDS });
  } catch (err) {
    console.error(`cache write failed for ${ip}:`, err.message);
  }
}

module.exports = { getCached, setCached, client };

Drop the cache into the middleware by checking it before the API call and writing after. A six-hour TTL is a reasonable default for scraper defense; if you are scoring for something more time-sensitive, shorten it. The important part is that a cache outage degrades to a cache miss and a fresh lookup, never to a crash.

Layer 2: rate limiting that assumes IP rotation

IP scoring thins the herd. It does not stop the scraper that rotates through a hundred clean-looking residential IPs at a slow, human-plausible rate. That is what rate limiting is for, and the mistake most teams make is keying it on the bare IP, which is exactly the thing the scraper is rotating.

Key on something with more signal. The IP's ASN (its owning network) is a good coarse key, because a scraper rotating a hundred IPs inside one hosting provider's ASN still shares that ASN. A session token or fingerprint is better where you have one. In practice you combine them, and you feed the IP verdict from layer one into the decision so a request that already scored "monitor" gets a tighter limit than a clean one.

// A minimal sliding-window limiter keyed on ASN + path, tightened by IP risk.
// Uses the same Redis client; swap for a library like rate-limiter-flexible in production.
const { client } = require("./cache");

async function bumpWindow(key, windowSeconds) {
  const count = await client.incr(key);
  if (count === 1) {
    await client.expire(key, windowSeconds);
  }
  return count;
}

async function rateLimit(req, res, next) {
  const asn = req.ipRisk?.asn?.as_number ?? "unknown"; // coarse key that survives IP rotation
  const key = `rl:${asn}:${req.path}`;

  // Tighten the ceiling for already-suspicious traffic.
  const suspicious = ["monitor", "challenge"].includes(req.ipRisk?.action);
  const limit = suspicious ? 20 : 120; // requests per window
  const windowSeconds = 60;

  try {
    const count = await bumpWindow(key, windowSeconds); // INCR + EXPIRE, see note
    if (count > limit) {
      res.setHeader("Retry-After", windowSeconds);
      return res.status(429).json({ error: "rate limit exceeded" });
    }
  } catch (err) {
    // Limiter backed by Redis; if it is down, do not block legitimate traffic.
    console.error("rate limit check failed:", err.message);
  }
  next();
}
module.exports = { rateLimit };

Pitfall: ASN keying is coarse on purpose, and it can catch real users who share a large mobile carrier's ASN. Keep the clean-traffic ceiling generous, and reserve the tight limit for traffic the IP layer already flagged. The combination is what makes it safe.

Note that the raw security response nests the ASN under the asn object on a full lookup rather than inside security; if you trimmed the response with fields=security as shown earlier, widen it to include asn when you need the network for keying.

Layer 3: behavioral and honeypot signals

This is the layer that catches what IP scoring cannot: the patient scraper on a clean residential connection. The signals here are about behavior, not origin.

The cheap behavioral tells are request cadence (a client requesting a hundred product pages in perfect thirty-second intervals is not a person), missing or inconsistent headers (no Referer, an Accept header no real browser sends), and headless-browser markers. None of these is conclusive alone, which is the recurring theme of the whole article, but stacked with a middling IP score they add up to a confident verdict.

A honeypot is the highest-signal, lowest-effort trap in the set. Put a link on the page that is invisible to humans and irresistible to a naive crawler, and anything that follows it has outed itself.

// Render a decoy link that humans never see but a link-following bot will hit.
// Do NOT hide it with display:none — headless Chrome refuses clicks on those.
// Use opacity and off-screen positioning so it is still in the DOM and clickable.
function honeypotMarkup() {
  return `<a href="/api/catalog-export"
             aria-hidden="true" tabindex="-1"
             style="position:absolute;left:-9999px;opacity:0">
            View full catalog
          </a>`;
}

// Any hit on the decoy route is automated by definition. Record and act.
function honeypotTrap(req, res) {
  const ip = req.ipRisk?.ip ?? req.ip;
  console.warn(`Honeypot triggered by ${ip} (${req.headers["user-agent"]})`);
  // Add the IP to your own blocklist / feed it back into scoring here.
  res.status(404).end(); // 404, not 403: do not tell the bot it found a trap.
}

Two details earn their comments. Hiding the link with display:none backfires because headless Chrome will not click those, so the trap uses opacity:0 and off-screen positioning to stay clickable. And the trap returns a 404, not a 403, because a 403 tells the operator they hit a honeypot and should adjust; a 404 looks like a dead link and teaches them nothing.

Putting the layers together

Wired in order, the layers form a single decision. IP scoring runs first and cheaply, rate limiting keys on network and tightens for flagged traffic, behavioral checks and the honeypot catch what got through.

const express = require("express");
const { ipRisk } = require("./ip-risk");
const { rateLimit } = require("./rate-limit");

const app = express();
app.set("trust proxy", 1); // match this to your real proxy depth

app.use(ipRisk);      // layer 1: attach req.ipRisk
app.use(rateLimit);   // layer 2: ASN-keyed, risk-aware

// layer 1 enforcement on the endpoints scrapers actually want
app.get("/api/fares", (req, res, next) => {
  const action = req.ipRisk?.action ?? "allow";
  if (action === "block") return res.status(404).end(); // 404 leaks less than 403
  if (action === "challenge") return res.status(403).json({ challenge: "captcha" });
  next(); // allow + monitor fall through; "monitor" is already logged
}, serveFares);

function serveFares(req, res) {
  res.json({ route: "JFK-LHR", fares: [/* ... */] });
}

What you log here decides whether you can tune later. Record the IP, the score, the individual flags, the action taken, and the endpoint, for every non-allow decision. After a week you will see which score bands catch real scrapers on which routes, and you will move your thresholds off the starting defaults to fit your own traffic. Detection without logging is a guess you can never check.

Where this stops working

Be clear-eyed about the limits, because pretending they do not exist is how you get a false sense of safety.

Residential proxies that route through genuine ISP customers are the hard ceiling. When a scraper's exit IP belongs to a real Comcast subscriber and has not been flagged yet, the IP layer sees an ordinary residential address. That traffic is caught, if at all, by behavior: cadence, session shape, the honeypot. The IP score narrows the field; it does not close it.

False positives are the other side of the coin, and on a revenue path they cost you directly. Corporate VPNs, university networks, and iCloud Private Relay all carry real customers who will trip a naive rule. This is why the flags are broken out and why you tier by score instead of blocking on any anonymizer signal. Treat is_relay gently. Do not put a hard block on a VPN flag alone.

And do not block the good bots. Googlebot and Bingbot need in, or you disappear from search. Verify legitimate crawlers (reverse DNS on the claimed identity, not the user-agent string, which is trivially forged) and allowlist them ahead of any of this.

When the scraping is sophisticated, persistent, and expensive enough to be worth an arms race, that is the point where a dedicated bot-management platform earns its cost. The IP layer you just built is the right first move for most travel and e-commerce sites, and it is often enough on its own for the bulk, lazy scraping that makes up the majority of the problem. It is a floor, not a ceiling.

A few extra notes

robots.txt is not enforcement. It is a request that polite crawlers honor and scrapers ignore. Keep it accurate for Googlebot; do not mistake it for a control.

Logging IPs has compliance weight. Under GDPR an IP address is personal data. If you are storing verdicts and IPs, have a retention policy and a reason, and keep the window short.

IPv6 changes the blocklist math. A single IPv6 subscriber can have a /64 (that is 18 quintillion addresses), so blocking individual v6 addresses is pointless. Score and rate-limit on the prefix, not the full address.

Self-hosted is an option at scale. If per-request lookups become a latency or budget problem, the same detection data ships as a downloadable database you query locally. Worth it once you are past a few million lookups a month or you need air-gapped scoring.

Start with the IP layer on your fare-search and category endpoints, because that is where the scrapers go and where the cheap filter buys you the most. Add rate limiting the same day; it is a few lines and it covers the rotation case. Get behavioral detection in once you have a week of logs telling you what the IP layer missed. If I were doing this from scratch on a busy catalog, I would wire scoring and the honeypot on day one and treat everything past that as tuning.

Automated Ticket Routing by Timezone (with Code)

ABDULLAH AFZAL — Thu, 09 Jul 2026 18:44:53 +0000

Automated ticket routing usually means sorting by topic or skill. This one sorts by clock: send each ticket to a support region that's actually staffed right now.

The hard part isn't the routing. It's knowing who's online, and "online" is really two things stacked together: what time it is in each region, and the hours you actually staff there. The first you can get exactly right from an API. The second you define. Put them together and you get follow-the-sun support without running a night shift in every office.

By the end you'll have a small, DST-safe router in TypeScript. You model your support hubs, pull each hub's current local time, pick a region that's open, and fall back sanely when none of them are.

TL;DR

"Route to whoever's online" = match a ticket to a hub that's inside its coverage window, computed from that hub's real local time.
An API gives you the DST-correct current time per timezone. Your config gives you the staffed hours. Neither one alone is enough.
Hardcoding UTC offsets breaks twice a year when daylight saving flips. Let the timezone data carry the offset.
Compare the hub's local wall-clock string against your window. Don't rebuild Date objects from offset strings; that's where the bugs live.
Always have a fallback hub for the hours nobody's open, so a ticket never lands nowhere.

Follow-the-sun routing sounds like an ops problem, and the strategy side of it is. But the piece nobody writes down is the implementation: the timezone math, the coverage windows, and the "it's 3am everywhere" edge case. That's what this builds.

What "route to whoever's online" actually needs

Strip it down and every follow-the-sun router answers one question per ticket: which of my hubs is open right now, and if more than one, which should take it?

"Open right now" depends on the hub's local time, not yours or your server's. A hub in Sydney and a hub in Berlin are nine or ten hours apart, and that gap shifts when either side changes for daylight saving. So the router needs the current local time in each hub, and it needs it to already account for DST. That last part is the whole reason to lean on a timezone service instead of a lookup table.

One thing worth saying plainly, because it's easy to oversell: an API can't tell you an agent is at their desk. It tells you it's 10:37 in Berlin and DST is off. Whether someone is working at 10:37 is your coverage policy, and if you want true presence you wire in your own on-call or status system. This tutorial routes on coverage windows, which is what most teams actually mean by "online."

Why the naive version breaks

The tempting first cut is a hardcoded offset. It looks fine in April and quietly misroutes every summer.

// The tempting version. It has a bug that shows up twice a year.
function isBerlinOpen() {
  const utcHour = new Date().getUTCHours();
  const berlinHour = (utcHour + 1) % 24; // Berlin is UTC+1... except in summer
  return berlinHour >= 9 && berlinHour < 18;
}

For roughly half the year Berlin is UTC+2, not +1. So from late March to late October this function is an hour off, and tickets get sent to an office that's still closed or skipped when it's actually staffed. Multiply that across five hubs and two DST calendars that don't switch on the same weekend, and the bug is basically undebuggable from the outside.

Server-local time has the same problem in a nicer outfit. Your box runs UTC in one region and local time in another, and new Date() means different things in each. Timezone libraries like Luxon or Intl.DateTimeFormat solve the math, but then you own keeping the IANA tz database current, and it does change through the year. The point isn't that any of these can't work. It's that the offset and the DST state are the error-prone part, so the cleanest move is to fetch them already resolved and never do the arithmetic yourself.

Pick a source for the timezone data

You've got two honest options. Compute it in-process from the IANA tz database with a library like Luxon or date-fns-tz, or call an API such as IPGeolocation, ipinfo, or ip-api that returns the current time and DST state for a zone directly. In-process is zero network latency but puts tz-data updates on you. An API call adds a hop but hands you the resolved offset, the DST flag, and the next transition.

I'll use IPGeolocation here because one call to its Timezone API returns a hub's local time, its DST status, and when DST next flips, and it's on the free tier, which keeps this example short. Create a free key, set it as IPGEO_API_KEY, and you're ready. Here's the request for one zone:

curl -X GET 'https://api.ipgeolocation.io/v3/timezone?apiKey=API_KEY&tz=America/New_York'

The response carries the full timezone picture. This is the complete object, not a trimmed one, because the DST fields are the part that matters:

{
  "time_zone": {
    "name": "America/New_York",
    "offset": -5,
    "offset_with_dst": -5,
    "date": "2026-03-07",
    "date_time": "2026-03-07 04:37:39",
    "date_time_txt": "Saturday, March 07, 2026 04:37:39",
    "date_time_wti": "Sat, 07 Mar 2026 04:37:39 -0500",
    "date_time_ymd": "2026-03-07T04:37:39-0500",
    "current_time": "2026-03-07 04:37:39.746-0500",
    "current_time_unix": 1772876259.746,
    "time_24": "04:37:39",
    "time_12": "04:37:39 AM",
    "week": 10,
    "month": 3,
    "year": 2026,
    "year_abbr": "26",
    "current_tz_abbreviation": "EST",
    "current_tz_full_name": "Eastern Standard Time",
    "standard_tz_abbreviation": "EST",
    "standard_tz_full_name": "Eastern Standard Time",
    "is_dst": false,
    "dst_savings": 0,
    "dst_exists": true,
    "dst_tz_abbreviation": "EDT",
    "dst_tz_full_name": "Eastern Daylight Time",
    "dst_start": { "utc_time": "2026-03-08 TIME 07:00", "duration": "+1.00H", "gap": true, "date_time_after": "2026-03-08 TIME 03:00", "date_time_before": "2026-03-08 TIME 02:00", "overlap": false },
    "dst_end": { "utc_time": "2026-11-01 TIME 06:00", "duration": "-1.00H", "gap": false, "date_time_after": "2026-11-01 TIME 01:00", "date_time_before": "2026-11-01 TIME 02:00", "overlap": true }
  }
}

Look at dst_start: it's 2026-03-08, the day after this response. When that moment passes, is_dst flips to true and offset_with_dst becomes -4 on its own. You don't track that; the API does. For routing, the two fields I care about are time_24 (the local wall-clock time as a string) and date_time_txt (whose first token is the local weekday). I'll read the offset arithmetic off nobody.

Pitfall: don't build a Date from date_time_ymd. Its offset is formatted -0500 with no colon, which some JS engines parse and others reject. Comparing the time_24 string sidesteps timezone parsing entirely, so that's what the router uses.

Here's the client. It validates the key at startup and caches per zone, because a hub's clock only moves by the minute and you don't want a lookup per ticket at peak.

// timezone.ts - one dedicated call per zone, cached by the minute.
const API_KEY = process.env.IPGEO_API_KEY;
if (!API_KEY) {
  // Fail fast at boot, not on the first ticket at 2am.
  throw new Error("Missing IPGEO_API_KEY");
}

const BASE = "https://api.ipgeolocation.io/v3/timezone";
const TTL_MS = 30_000; // tickets arriving in the same 30s share one lookup
const cache = new Map<string, { at: number; data: TimeZone }>();

export interface TimeZone {
  name: string;
  time_24: string;        // "HH:mm:ss", local wall clock
  date: string;           // "YYYY-MM-DD", local date
  date_time_txt: string;  // "Saturday, March 07, 2026 09:37:39"
  is_dst: boolean;
  offset_with_dst: number;
}

export async function getZoneTime(tz: string): Promise<TimeZone> {
  const hit = cache.get(tz);
  if (hit && Date.now() - hit.at < TTL_MS) return hit.data;

  const url = `${BASE}?apiKey=${API_KEY}&tz=${encodeURIComponent(tz)}`;
  const res = await fetch(url, { signal: AbortSignal.timeout(1500) }); // Node 18+ has fetch
  if (!res.ok) throw new Error(`timezone lookup failed for ${tz}: ${res.status}`);

  const z = (await res.json())?.time_zone;
  if (!z?.time_24 || !z?.date_time_txt) throw new Error(`unexpected payload for ${tz}`);

  cache.set(tz, { at: Date.now(), data: z });
  return z;
}

The AbortSignal.timeout(1500) matters more than it looks. Ticket creation shouldn't hang for a slow lookup, so cap it and let the caller decide what to do on failure.

Model your support hubs

Coverage belongs in config, not buried in the routing logic. A hub is an IANA zone, a set of staffed hours per weekday, a holiday list, a priority for tiebreaks, and optionally the languages it covers.

// hubs.ts - edit this file, not the router, when coverage changes.
export interface Hub {
  id: string;
  tz: string;                                        // IANA zone, passed straight to the API
  priority: number;                                  // lower wins when several hubs are open
  languages: string[];                               // prefer a hub that speaks the customer's language
  holidays: Set<string>;                             // "YYYY-MM-DD" in the hub's local date
  hours: Record<string, { open: string; close: string } | null>; // null = closed that weekday
}

const workdays = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"];
const nineToSix = Object.fromEntries(workdays.map((d) => [d, { open: "09:00", close: "18:00" }]));

export const HUBS: Hub[] = [
  { id: "emea", tz: "Europe/Berlin",     priority: 1, languages: ["de", "en"],
    holidays: new Set(["2026-10-03"]), hours: nineToSix },
  { id: "amer", tz: "America/New_York",  priority: 1, languages: ["en", "es"],
    holidays: new Set(["2026-07-03"]), hours: nineToSix },
  { id: "apac", tz: "Australia/Sydney",  priority: 2, languages: ["en"],
    holidays: new Set(["2026-01-26"]), hours: nineToSix },
];

export const FALLBACK_HUB_ID = "amer"; // whoever carries the pager when the world's asleep

Note that hours keys are full weekday names, because that's what the API's date_time_txt gives us and matching strings beats mapping day numbers back and forth. Days you don't staff are simply absent, which reads as closed.

The ticket routing decision

Three steps: figure out which hubs are open, pick the best open one, and handle the case where none are.

Deciding if one hub is open

For a hub, pull its local time, read its local weekday, check today's window, and rule out holidays. The window check handles normal daytime hours and overnight coverage like 22:00 to 06:00, including the early-morning carryover from the previous local day.

// router.ts
import { HUBS, FALLBACK_HUB_ID, Hub } from "./hubs";
import { getZoneTime } from "./timezone";

const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];

const toMinutes = (hhmm: string) => {
  const [h, m] = hhmm.split(":").map(Number);
  return h * 60 + m;
};

function previousWeekday(day: string) {
  const i = WEEKDAYS.indexOf(day);
  return WEEKDAYS[(i + 6) % 7];
}

function previousLocalDate(yyyyMmDd: string) {
  const d = new Date(`${yyyyMmDd}T00:00:00Z`);
  d.setUTCDate(d.getUTCDate() - 1);
  return d.toISOString().slice(0, 10);
}

function sameDayWindow(nowHHMMSS: string, w: { open: string; close: string }) {
  const now = toMinutes(nowHHMMSS.slice(0, 5));
  const open = toMinutes(w.open);
  const close = toMinutes(w.close);

  // Normal window: 09:00-18:00.
  // Overnight window: only the start side belongs to this weekday, e.g. 22:00-23:59.
  return open <= close ? now >= open && now < close : now >= open;
}

function previousDayOvernightWindow(nowHHMMSS: string, w: { open: string; close: string }) {
  const now = toMinutes(nowHHMMSS.slice(0, 5));
  const open = toMinutes(w.open);
  const close = toMinutes(w.close);

  // Previous day's overnight carryover, e.g. Friday 22:00-06:00 still open Saturday 02:00.
  return open > close && now < close;
}

async function isOpenNow(hub: Hub): Promise<boolean | "unknown"> {
  try {
    const z = await getZoneTime(hub.tz);
    const weekday = z.date_time_txt.split(",")[0].trim();
    const window = hub.hours[weekday];

    if (window && !hub.holidays.has(z.date) && sameDayWindow(z.time_24, window)) {
      return true;
    }

    const prevWeekday = previousWeekday(weekday);
    const prevWindow = hub.hours[prevWeekday];
    const prevDate = previousLocalDate(z.date);

    if (
      prevWindow &&
      !hub.holidays.has(prevDate) &&
      previousDayOvernightWindow(z.time_24, prevWindow)
    ) {
      return true;
    }

    return false;
  } catch {
    return "unknown";
  }
}

The "unknown" return is deliberate. A failed lookup is not the same as a closed office, and collapsing the two is how you either drop tickets or spam a hub that's asleep.

Picking among the open hubs

When several hubs are open, prefer one that speaks the customer's language, then fall back to priority, then a stable tiebreak so the same ticket always lands the same way.

export interface Routing { hubId: string; reason: string; }

export async function routeTicket(customerLangs: string[] = []): Promise<Routing> {
  const statuses = await Promise.all(
    HUBS.map(async (h) => ({ hub: h, open: await isOpenNow(h) }))
  );

  const openHubs = statuses.filter((s) => s.open === true).map((s) => s.hub);

  if (openHubs.length > 0) {
    openHubs.sort((a, b) => {
      const langA = a.languages.some((l) => customerLangs.includes(l)) ? 0 : 1;
      const langB = b.languages.some((l) => customerLangs.includes(l)) ? 0 : 1;
      return langA - langB || a.priority - b.priority || a.id.localeCompare(b.id);
    });
    return { hubId: openHubs[0].id, reason: "open, best language and priority match" };
  }

  // Nobody's open, or we couldn't tell. Route to the on-call hub, never to nowhere.
  return { hubId: FALLBACK_HUB_ID, reason: "no hub open, sent to on-call fallback" };
}

The fallback, and fail-open vs fail-closed

This is the decision most versions skip. If no hub is open, or every lookup failed, the router still returns a destination: the fallback hub. For support, failing toward a human is the right call. Dropping a ticket because an API timed out is worse than sending it to your on-call team a little early. If you'd rather hold it until a region opens, you can compute the next-to-open hub from the same timezone data instead of using a fixed fallback, but I'd only add that once the simple version is running.

Tip: log the reason on every routed ticket. When someone asks why a 2am ticket went to New York, the answer is right there in the record.

Know the customer's local time too

Routing decides who handles the ticket. Knowing the customer's local time decides how the agent treats it. A billing question at 2pm their time is different from one that came in at 3am, and showing the agent that context is a small touch that changes tone.

The same endpoint takes an IP and returns the requester's location alongside the timezone block, so you get their city, country, and local time in one call.

// enrich.ts - tell the agent what time it is where the customer is.
const API_KEY = process.env.IPGEO_API_KEY!;
const BASE = "https://api.ipgeolocation.io/v3/timezone";
const toHour = (t: string) => Number(t.slice(0, 2));

export async function customerLocalTime(ip: string) {
  try {
    const url = `${BASE}?apiKey=${API_KEY}&ip=${encodeURIComponent(ip)}`;
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) return null;                 // enrichment is non-critical, so degrade quietly
    const body = await res.json();
    const z = body?.time_zone;
    if (!z?.time_24) return null;
    return {
      city: body?.location?.city ?? "unknown",
      country: body?.location?.country_code2 ?? "??",
      zone: z.name,
      localTime: z.time_24,
      isNight: toHour(z.time_24) < 8 || toHour(z.time_24) >= 22,
    };
  } catch {
    return null; // never block ticket creation on an enrichment call
  }
}

Enrichment returns null on any failure instead of throwing, because a missing "local time" note should never stop a ticket from being created.

Pitfall: if you're reading the requester's IP from an inbound HTTP request rather than a webhook payload, don't trust req.socket.remoteAddress behind a proxy or load balancer. Set app.set('trust proxy', true) and read req.ip, or take the left-most public address from X-Forwarded-For. And don't route anything security-sensitive on a client-supplied IP, since it's trivial to spoof.

Wire it into a helpdesk

Most teams aren't routing in a vacuum; they're routing inside Zendesk, Freshdesk, or something similar. The pattern is the same everywhere: a trigger fires on ticket creation, POSTs to your service, and your service sets the group or region on the ticket. Here's a minimal Express endpoint for the Zendesk case.

// webhook.ts - a Zendesk trigger POSTs here on ticket creation.
import express from "express";
import { routeTicket } from "./router";
import { customerLocalTime } from "./enrich";

const app = express();
app.use(express.json());

// Map your regions to real Zendesk group IDs (Admin > People > Groups).
const GROUP_IDS: Record<string, number> = { emea: 360001, amer: 360002, apac: 360003 };

app.post("/zendesk/route", async (req, res) => {
  const ticketId = req.body?.ticket?.id;
  const ip = req.body?.ticket?.requester_ip;          // include this in the trigger payload
  const langs = req.body?.ticket?.requester_langs ?? [];
  if (!ticketId) return res.status(400).json({ error: "missing ticket id" });

  const { hubId, reason } = await routeTicket(langs);
  const info = ip ? await customerLocalTime(ip) : null;

  try {
    await assignZendeskGroup(ticketId, GROUP_IDS[hubId], info);
    res.json({ ok: true, routedTo: hubId, reason });
  } catch (err) {
    console.error("assignment failed", err);        // let Zendesk's default trigger catch it
    res.status(502).json({ error: "assignment failed" });
  }
});

The handler routes, enriches, and assigns, and if assignment fails it returns a 502 so your Zendesk fallback trigger can still catch the ticket. The assignment call itself is a plain ticket update:

async function assignZendeskGroup(ticketId: number, groupId: number, info: unknown) {
  const res = await fetch(
    `https://${process.env.ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/${ticketId}.json`,
    {
      method: "PUT",
      signal: AbortSignal.timeout(2000),
      headers: {
        "Content-Type": "application/json",
        Authorization: `Basic ${process.env.ZENDESK_AUTH}`, // base64 of email/token:...
      },
      body: JSON.stringify({
        ticket: {
          group_id: groupId,
          comment: info
            ? { public: false, body: `Customer local time: ${JSON.stringify(info)}` }
            : undefined,
        },
      }),
    }
  );
  if (!res.ok) throw new Error(`zendesk update failed: ${res.status}`);
}

Heads up: the trigger and webhook wiring lives in Zendesk's admin, and their payload shape and API version can shift, so check their current docs before you ship. If you can't get the end-user IP into the payload, key the enrichment off the requester's stored locale or organization region instead.

A few extra notes

Overnight coverage and on-call rotations fit the same model. An overnight hub is just a window where open is later than close, and the router handles both the start side and the early-morning carryover from the previous local day. A rotation is a hub whose hours you regenerate from your scheduling tool rather than hardcode.

The two DST changeover weekends a year are the moments to watch. Because the router reads is_dst and the local time straight from the API, it follows each region across its own switch automatically, even when the US and EU don't flip on the same date. If you were doing offset math by hand, those two weekends are exactly when you'd get paged.

IPv6 works the same as IPv4 for the enrichment call; pass the address to the ip parameter and read the same fields back. And at higher ticket volume, watch your lookup count: the per-zone cache keeps you to roughly one call per zone per minute, but if you run several instances, move that cache to Redis so they share it instead of each hammering the endpoint.

Closing

Start with two hubs and a fallback, get the open/closed check right, then add language routing and more regions once it holds. If I were building this from scratch, I'd put the fallback and the per-zone cache in on day one; both are easy to skip and annoying to add back after a 3am ticket disappears. When your volume climbs, mind the rate limits and cache accordingly.

Show the Cookie Consent Banner Only to Visitors Who Legally Need It

ABDULLAH AFZAL — Wed, 24 Jun 2026 13:53:28 +0000

A cookie consent banner is a legal requirement in some places and optional in others, yet most sites show the same one to every visitor on the planet. The EU and UK want opt-in before any non-essential cookie fires. The US wants notice and an opt-out, not a wall. A lot of traffic needs no banner at all.

This is a guide to detecting a visitor's jurisdiction from their IP and showing the consent experience that actually applies: a strict opt-in banner for Europe, an opt-out notice for US states, nothing where it isn't required. It is not legal advice. It is the engineering around a line your lawyer should draw.

TL;DR

The EEA and the UK require opt-in consent before non-essential cookies run. The US requires notice and an opt-out. Much of the rest of the world requires neither.
One IP field, is_eu, does most of the routing. It covers EU member states only, so add the UK and the EEA states (Iceland, Liechtenstein, Norway) yourself.
Geo-targeting the banner is a UX and conversion decision, not a compliance shortcut. The law still applies wherever the visitor actually is.
IP geolocation is probabilistic. VPNs, proxies, and travelers break it, so fail toward showing consent when you are not sure.
The EU's Digital Omnibus may simplify all of this, but as of June 2026 it is a proposal, not law. In short: read the visitor's country and an EU flag from their IP, route them to one of three consent experiences, and gate your non-essential scripts behind that decision. When the lookup is uncertain, show the opt-in banner anyway. The code below is the same classifier wired into curl, the browser, and an Express server.

Who actually needs a cookie consent banner?

If you have wondered whether you need a cookie banner at all, the honest answer is that it depends on where your visitor is sitting. The cookie banner requirements come down to three regimes that cover most of your traffic, and the cookies that trip the rules are always the non-essential ones: analytics, advertising, A/B testing, heatmaps, cross-site pixels. Session cookies, CSRF tokens, the load-balancer cookie, and the cookie that remembers a consent choice are strictly necessary and never need permission.

The EU and EEA: opt-in before non-essential cookies

In Europe, the rule is consent first. Article 5(3) of the ePrivacy Directive says you can only store or read information on someone's device once they have given consent, with a narrow exemption for what is strictly necessary to deliver the service they asked for. The GDPR then sets the bar for what counts as consent: a freely given, specific, informed, unambiguous opt-in. No pre-ticked boxes, no "by continuing you agree."

This applies across the whole European Economic Area, not just the 27 EU member states. The EEA adds three more countries through the EEA Agreement: Iceland, Liechtenstein, and Norway. They enforce the same opt-in standard. That detail matters for the code, because the obvious is_eu check misses all three.

The UK: still opt-in, on its own track

The UK left the EU but kept the rule. Consent for non-essential cookies comes from the Privacy and Electronic Communications Regulations (PECR), with the UK GDPR supplying the consent standard. The ICO finalized its guidance on storage and access technologies in April 2026, and it expects an "Accept all" and a "Reject all" option with equal prominence, with non-essential scripts blocked until the user opts in.

The practical catch for developers: the UK is not in the EU, so a naive "is this visitor in the EU?" check returns false for British traffic and silently skips a banner the UK still requires. The Data (Use and Access) Act 2025 carved out a few narrow low-risk exceptions, but analytics and advertising are not among them.

The US: notice and opt-out, not a banner

No US state law mandates a cookie banner. The model is the opposite of Europe's: collect first, give notice, and let people opt out. Under the CCPA and CPRA, enforced by California's Attorney General, a business that sells or shares personal information has to post a clear "Do Not Sell or Share My Personal Information" link (or a "Your Privacy Choices" control) and stop on request.

There is one piece you do have to honor automatically. A Global Privacy Control signal, sent as the Sec-GPC: 1 request header, counts as a valid opt-out under California law, and businesses must respect it. So the US branch of your logic is not "show a banner," it is "show a privacy-choices link and read the GPC header."

Roughly a dozen states now have their own consumer privacy laws (California, Virginia, Colorado, Connecticut, Utah, Texas, Florida, and more), and the stricter California regulations took effect on January 1, 2026, with explicit bans on dark patterns in the opt-out flow. They differ in detail, but none of them turns into a European-style consent wall.

Here is the whole decision in one table:

Region	Consent model	What to show	IP signal
EEA (EU-27 + Iceland, Liechtenstein, Norway)	Opt-in before non-essential cookies	Opt-in banner; block scripts until consent	`is_eu === true`, plus `IS`/`LI`/`NO` by country code
United Kingdom	Opt-in (UK GDPR + PECR)	Opt-in banner, equal-prominence reject	`country_code2 === 'GB'`
United States	Notice + opt-out	"Your Privacy Choices" link; honor GPC	`country_code2 === 'US'` (use `state_code` for nuance)
Most other countries	Usually none	No banner (confirm per market)	anything else

If your site runs on WordPress or Shopify, a consent platform like Cookiebot or CookieYes will geo-target the banner for you as a paid feature, and that is a reasonable buy. The rest of this guide is for everyone building it themselves.

Why one global banner is the wrong default

A single global banner is the lazy default that manages to annoy the people who do not need it and under-serve the ones who do. Show a GDPR cookie banner to US visitors and you cost yourself conversions on traffic that never required a click, while training those users to slap "Accept" on every banner out of habit. Skip the banner in Europe and you are setting tracking cookies without consent, which is what the ICO's letter campaigns and the larger CNIL fines have been about.

The defensible move is to match the experience to the jurisdiction, and when you genuinely cannot tell where someone is, default to the stricter option. That is the whole strategy. The rest is reading an IP and being honest about how much you can trust it.

Detecting the visitor's jurisdiction from their IP

You need three things from an IP: the country, the US state (for later nuance), and a flag for whether the country is in the EU. Any IP geolocation API gives you this. IPGeolocation, ipinfo, ip-api, MaxMind GeoIP2, IPLocate, and IP2Location all return country and region. I'll use ipgeolocation.io for the examples because its free tier returns an is_eu boolean alongside the country and state code in one call, which keeps the routing logic short. You can grab a free API key and follow along; the free tier covers 1,000 lookups a day.

The one field that does most of the work: is_eu

A single lookup against the /v3/ipgeo endpoint returns everything the free tier offers. Here is the real response for 8.8.8.8 (Google's public DNS, which geolocates to the US), so you can see what one call gives you:

curl "https://api.ipgeolocation.io/v3/ipgeo?apiKey=$IPGEO_API_KEY&ip=8.8.8.8"

{
  "ip": "8.8.8.8",
  "location": {
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "state_prov": "California",
    "state_code": "US-CA",
    "city": "Mountain View",
    "zipcode": "94043-1351",
    "latitude": "37.42240",
    "longitude": "-122.08421",
    "is_eu": false
  },
  "country_metadata": {
    "calling_code": "+1",
    "tld": ".us",
    "languages": ["en-US", "es-US", "haw", "fr"]
  },
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
  "asn": { "as_number": "AS15169", "country": "US", "organization": "Google LLC" },
  "time_zone": { "name": "America/Los_Angeles", "current_time": "2026-03-03 03:22:55.618-0800" }
}

That is the full free-tier shape (location, country metadata, currency, ASN, and timezone in one response), but the consent logic only needs the location object. Trim the payload with fields and pull the confidence rating with include=geo_accuracy:

curl "https://api.ipgeolocation.io/v3/ipgeo?apiKey=$IPGEO_API_KEY&ip=91.128.103.196&fields=location&include=geo_accuracy"

{
  "ip": "91.128.103.196",
  "location": {
    "country_code2": "SE",
    "country_name": "Sweden",
    "state_code": "SE-AB",
    "city": "Stockholm",
    "accuracy_radius": "9.148",
    "confidence": "high",
    "is_eu": true
  }
}

Sweden comes back with is_eu: true; the US came back false. That boolean is the cheapest signal you have. The trap is treating it as the whole answer. is_eu reflects EU membership, so it is false for the UK and for the EEA states Norway, Iceland, and Liechtenstein, all of which still require opt-in. So the rule is: trust is_eu for the EU, and add the other four countries by hand.

One value to watch: confidence comes back as a string, and the casing is inconsistent across responses (high, High, low). Lowercase it before you compare, or a === 'low' check will quietly miss half the cases.

A jurisdiction classifier

Here is the function that turns a location object into a decision. It is pure (no network, no globals), which is why the same code drops into the browser and the server unchanged.

// UK + the EEA-EFTA states. Same opt-in rule as the EU, but is_eu doesn't flag them.
const GDPR_OPTIN_NON_EU = new Set(['GB', 'IS', 'LI', 'NO']);

// Returns 'gdpr-optin' | 'us-optout' | 'none', or null when we can't tell.
function classifyJurisdiction(location) {
  // No location object means the lookup gave us nothing usable.
  // Hand back null and let the caller fail toward consent.
  if (!location || typeof location !== 'object') return null;

  const country = location.country_code2 ?? null;

  // is_eu covers EU member states. The EEA (Norway, Iceland, Liechtenstein)
  // and the post-Brexit UK enforce the same opt-in rule, so add them explicitly.
  if (location.is_eu === true || (country && GDPR_OPTIN_NON_EU.has(country))) {
    return 'gdpr-optin';
  }

  // US: notice + opt-out, not a banner. state_code (e.g. "US-CA") is here
  // if you later need to special-case a state.
  if (country === 'US') return 'us-optout';

  // Everywhere else: usually no banner. Confirm against the markets you serve.
  return 'none';
}

The null return is deliberate. A missing country is not the same as "no banner needed," and the difference is the whole point of the next sections.

Showing the banner conditionally

Two places to make the call: in the browser after the page loads, or on the server before it renders. The server-side version is better because the banner ships in the initial HTML with no flash, but the client-side version is fewer moving parts. Both reuse the classifier above.

Client-side: gate the banner in the browser

On load, look up the caller's IP (omit the ip parameter and the API uses the request's own address), classify, and show the right UI:

async function detectConsentRegime() {
  // This key ships to the browser. Restrict it to your domain with the API's
  // request-origin (CORS) allowlist, or proxy the call through your own backend.
  const KEY = window.IPGEO_PUBLIC_KEY;

  try {
    const res = await fetch(
      `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${KEY}&fields=location&include=geo_accuracy`,
      { signal: AbortSignal.timeout(1500) } // don't hang the page on a slow lookup
    );

    // 423 (private/bogon IP), 429 (rate limit), 5xx: don't guess, fail toward consent.
    if (!res.ok) return 'gdpr-optin';

    const data = await res.json();
    const location = data?.location;
    const confidence = (location?.confidence ?? '').toLowerCase();
    const regime = classifyJurisdiction(location);

    // Unknown country or low-confidence geo: show the stricter banner.
    if (regime === null || confidence === 'low') return 'gdpr-optin';
    return regime;
  } catch (err) {
    console.error('Geo lookup failed, defaulting to consent:', err);
    return 'gdpr-optin';
  }
}

detectConsentRegime().then((regime) => {
  if (regime === 'gdpr-optin') {
    showOptInBanner();        // load analytics/ads ONLY after the user accepts
  } else if (regime === 'us-optout') {
    showPrivacyChoices();     // "Your Privacy Choices" link; also honor GPC (below)
  }
  // 'none': load nothing extra, show no banner
});

Showing the banner is the easy half. The non-essential scripts (analytics, ads, pixels) must not run until you have consent in opt-in regions. A geo-gate that hides the banner but still fires Google Analytics on page load is the kind of mistake that looks fine in the UI and silently protects nothing. Keep your tracking calls inside the accept handler, not in the page's initial load.

Server-side: decide before the page renders

The same logic as Express middleware. The one thing people get wrong here is the client IP: behind a proxy, load balancer, or CDN, req.ip is the proxy's address unless you tell Express to trust it.

const express = require('express'); // Node 18+ for built-in fetch; else import undici/node-fetch
const app = express();

// Trust your proxy/CDN so req.ip is the real client, not the edge.
// Set this to your actual infrastructure; never blindly trust X-Forwarded-For.
app.set('trust proxy', 1);

async function lookupRegime(ip) {
  const KEY = process.env.IPGEO_API_KEY; // never hardcode the key server-side
  const url =
    `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${KEY}&ip=${ip}` +
    `&fields=location&include=geo_accuracy`;

  const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
  if (!res.ok) return 'gdpr-optin'; // 423 for private/localhost IPs in dev, 429, 5xx

  const data = await res.json();
  const location = data?.location;
  const confidence = (location?.confidence ?? '').toLowerCase();
  const regime = classifyJurisdiction(location);
  return (regime === null || confidence === 'low') ? 'gdpr-optin' : regime;
}

async function consentRegime(req, res, next) {
  try {
    req.consentRegime = await lookupRegime(req.ip);
  } catch (err) {
    console.error('Consent lookup failed, defaulting to consent:', err);
    req.consentRegime = 'gdpr-optin'; // fail toward consent, never away from it
  }
  // A GPC signal is a valid opt-out request under US state law. Honor it.
  req.gpcOptOut = req.headers['sec-gpc'] === '1';
  next();
}

app.use(consentRegime);

app.get('/', (req, res) => {
  res.send(renderPage({ regime: req.consentRegime, gpcOptOut: req.gpcOptOut }));
});

Now the banner is baked into the first byte of HTML, and US visitors who arrive with Sec-GPC: 1 get treated as already opted out before a single tracking script loads.

Make it production-safe

The naive version calls the API on every request and trusts the answer completely. Two changes fix the cost and the correctness.

Cache the lookup

The mapping from an IP to a jurisdiction barely changes, so caching the decision (not the whole response) for hours is free accuracy. A 6-hour TTL turns a busy site's thousands of requests into a handful of lookups, and your 1,000-a-day free tier stops being a constraint.

const TTL_MS = 6 * 60 * 60 * 1000; // IP-to-jurisdiction is stable for hours
const cache = new Map();            // swap for Redis across multiple instances

function getCachedRegime(ip) {
  const hit = cache.get(ip);
  if (hit && hit.expires > Date.now()) return hit.regime;
  cache.delete(ip); // expired
  return null;
}

async function regimeForIp(ip) {
  const cached = getCachedRegime(ip);
  if (cached) return cached;
  const regime = await lookupRegime(ip);
  cache.set(ip, { regime, expires: Date.now() + TTL_MS });
  return regime;
}

Point the middleware at regimeForIp(req.ip) instead of lookupRegime(req.ip) and you are done. On more than one server instance, use Redis with the same key and TTL.

Fail toward consent, not away from it

Every error path in the code above returns gdpr-optin, and that is intentional. When you cannot reach the API, the request times out, the geo confidence is low, or the country is unknown, the safe default is to show the stricter banner.

The reason is that the two failure modes are not symmetric. Showing an opt-in banner to someone who did not strictly need one costs a click. Hiding it from a European visitor and setting tracking cookies without consent is the violation regulators actually fine. When in doubt, eat the click.

VPNs, proxies, and travelers

This is where the title earns its asterisk. Country-level IP geolocation is strong (ipgeolocation.io reports 95%+ country-level accuracy), but it is a probability, not a fact. A German on a US corporate VPN looks American. A Londoner on holiday in Spain looks Spanish. iCloud Private Relay, datacenter proxies, and carrier-grade NAT all blur the picture.

So "show the banner only to visitors who legally need it" is really "show it to the visitors who appear to need it, and fail toward showing it when the signal is weak." For logged-in users you have a better signal than their current IP: the account's country or billing region. Use that to override the IP guess for known users, and let the confidence field downgrade you to the opt-in banner for everyone else. None of this makes IP a legal determination of jurisdiction. It makes the consent experience usually right and safe when it is wrong.

What's changing: the EU Digital Omnibus

If you have read that cookie banners are going away, that comes from the European Commission's Digital Omnibus proposal, published on November 19, 2025. It would fold the cookie rules out of the ePrivacy Directive and into the GDPR (new Articles 88a and 88b), require a single-click reject with equal prominence, stop sites from re-asking for six months after a refusal, push consent toward browser-level machine-readable signals that sites must honor, and exempt plain first-party audience measurement so basic visitor counting would not need a banner at all.

It is a proposal, not law. As of June 2026 the GDPR and the ePrivacy Directive are fully in force, unchanged. The Parliament and Council are still working through it, adoption is expected mid-to-late 2026 at the earliest, the cookie changes would only apply six months after that, and the browser-signal mechanism is years out. The EDPB and EDPS have issued a joint opinion backing the goal while flagging concerns about weakening protections. The UK, on its own track, will not move in lockstep regardless.

What that means today: build the routing now, because the divergence between regimes is widening, not shrinking. If the low-risk exemption does land, plain analytics may drop out of the banner inside the EU, and the classifier is exactly where you would encode that, one branch at a time.

Drop the classifier into your stack, gate your non-essential scripts behind it, and default to the opt-in banner whenever the lookup is unsure. When you outgrow the free tier's 1,000 lookups a day, cache harder before you reach for a paid plan. And keep a lawyer in the loop: the routing is sound engineering, but the line between "required" and "optional" is theirs to draw, not your IP database's.

Stop the Chargeback Before It Ships: IP vs Billing Country

ABDULLAH AFZAL — Wed, 17 Jun 2026 11:00:31 +0000

Every checkout already collects two facts that should line up: the billing-address country, and the country IP geolocation puts the buyer in. Comparing them is one of the cheapest fraud checks you can run, and most checkouts never do.

By the end of this you'll have a pre-auth function in Node, Python, and PHP that reads the buyer's IP country and threat signals in one call, compares the country to the billing address, and returns allow, add friction, review, or block. It's one signal in a layered defense, not a silver bullet, and the article is honest about where it helps and where it doesn't.

TL;DR

A buyer's IP country and billing country usually agree. A mismatch is a long-standing signal for stolen-card, card-not-present fraud.
One call to an IP geolocation and security API returns location.country_code2 plus a threat_score from 0 to 100 and flags for proxy, VPN, Tor, and residential proxy.
A mismatch on its own is weak. Travelers, expats, and corporate VPNs trip it constantly. Combine it with the threat and anonymizer signals before you act.
Map the combination to a decision: allow, add friction (3DS), route to manual review, or block. Never hard-block on country alone.
This catches third-party fraud, not friendly chargebacks, and it sits alongside AVS and 3-D Secure rather than replacing them.
Working code in curl, Node, Python, and PHP, with timeouts, lookup-failure handling, and the X-Forwarded-For gotcha.

The check is cheap and fast: one lookup, a country comparison, and a small scoring function. The hard part isn't the code. It's tuning the thresholds so you flag real fraud without bouncing the customer who's flying home from a work trip.

What this check catches, and what it doesn't

A stolen card used from another country is the textbook case. The card details are real, the billing address is the cardholder's, but the person at the keyboard is somewhere else entirely. Their IP geolocates to one country while the billing address says another. That gap is the signal. Card-not-present is where card fraud concentrates, and by the Nilson Report's 2024 figures the US alone leads the world in dollars lost to CNP fraud.

What it does not catch is friendly fraud, also called first-party fraud, where the real cardholder makes the purchase and later disputes it. The cardholder’s own IP and billing address may match perfectly, because it is genuinely them. No IP check will flag that. If your chargebacks are mostly "item not received" disputes from real customers, this is the wrong tool and you want delivery proof and better dispute handling instead.

It's also not the same thing as two checks people confuse it with. AVS (Address Verification Service) asks whether the billing address the shopper typed matches the address the issuing bank has on file. Shipping-versus-billing mismatch asks whether the package is going somewhere other than the billing address. IP-country-versus-billing-country is a third, independent signal, and you can compute it yourself before you ever hit the card network. It complements AVS and 3-D Secure. It doesn't replace either.

The signal, and why a match isn't enough

Here's the part that trips people up. A country match does not mean the order is clean, and a country mismatch does not mean it's fraud.

Take a real flagged IP, 2.56.188.34. Geolocation puts it in the United States, in Dallas. If a fraudster routes through it and enters a US billing address, the countries match. A naive ip_country === billing_country check waves it straight through. But that IP is a proxy and a VPN exit with a threat_score of 80, and it's flagged as a known attacker. The country lined up. The IP was still poison.

That's why the country comparison is necessary but not sufficient. You read the country and the anonymity signals together, in one call, and you let the combination decide. A mismatch backed by a proxy or a high threat score is a real flag. A lone mismatch from a clean residential IP is probably someone traveling.

Get the country and threat data in one call

You want two things per order: the country the IP resolves to, and the risk signals for that IP. The IP geolocation endpoint returns both when you add include=security, so you don't pay for two round trips. I'll use ipgeolocation.io's IP Security API for the examples because the security object ships a threat_score, a dedicated is_residential_proxy flag, and provider names with confidence scores, which is more than the boolean-only services give you. The same approach works with any API that returns an IP country plus risk flags.

Trim the response to just the fields you need with fields:

curl -s "https://api.ipgeolocation.io/v3/ipgeo?apiKey=$IPGEO_API_KEY&ip=2.56.188.34&include=security&fields=location.country_code2,security"

The response for that IP, in full:

{
  "ip": "2.56.188.34",
  "location": {
    "country_code2": "US"
  },
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

location.country_code2 is the ISO 3166-1 alpha-2 code, the same two-letter format your checkout already stores for the billing country (US, GB, DE). That's what makes the comparison a one-liner. The security object is the rest of the picture: a 0 to 100 threat_score, boolean flags for each anonymity type, and, when there's a match, the provider name and a confidence score. proxy_provider_names of ["Zyte Proxy"] with proxy_confidence_score 80 is a lot more actionable than a bare "this is a proxy."

Cost note: the combined lookup costs 3 credits per IP (1 for the base lookup, 2 for security). If you ever need the risk signals without the location, there's a dedicated /v3/security endpoint that costs 2. For this check you want both, so the combined call is the right one. Private, bogon, and malformed IPs aren't billed at all.

Build the pre-auth check

The lookup is the same logic in every language: build the request, set a tight timeout, read country_code2 and security, and fail soft if anything goes wrong. A checkout can't hang on a slow network call, and it shouldn't crash an order because a fraud signal was briefly unreachable.

Node.js

// risk-lookup.js. Node 18+ has global fetch; on older Node, import node-fetch.
const IPGEO_API_KEY = process.env.IPGEO_API_KEY; // load from env, never hardcode a key

async function lookupRisk(ip) {
  const url = new URL("https://api.ipgeolocation.io/v3/ipgeo");
  url.searchParams.set("apiKey", IPGEO_API_KEY ?? "");
  url.searchParams.set("ip", ip);
  url.searchParams.set("include", "security");                       // adds the security object (+2 credits)
  url.searchParams.set("fields", "location.country_code2,security"); // keep the payload small

  try {
    // The API answers in well under 100ms; 1.5s is a generous ceiling before we give up.
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) throw new Error(`status ${res.status}`);

    const data = await res.json();
    return {
      ipCountry: data?.location?.country_code2 ?? null, // ISO alpha-2, e.g. "US"
      security: data?.security ?? null,
      ok: true,
    };
  } catch (err) {
    // Signal "unknown" so the caller can route the order to review instead of blocking a paying customer.
    console.error(`IP risk lookup failed for ${ip}:`, err.message);
    return { ipCountry: null, security: null, ok: false };
  }
}

The function never throws. On a timeout or a bad status it returns ok: false, and the decision layer treats that as "couldn't check" rather than "block." That choice matters more than it looks, and the caching section comes back to it.

Python

import os
import requests  # pip install requests

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")  # load from env, never hardcode a key

def lookup_risk(ip: str) -> dict:
    params = {
        "apiKey": IPGEO_API_KEY or "",
        "ip": ip,
        "include": "security",                        # adds the security object (+2 credits)
        "fields": "location.country_code2,security",  # keep the payload small
    }
    try:
        # (connect, read) timeouts. A checkout cannot wait on a slow lookup.
        resp = requests.get(
            "https://api.ipgeolocation.io/v3/ipgeo",
            params=params,
            timeout=(1.0, 1.5),
        )
        resp.raise_for_status()
        data = resp.json()
        location = data.get("location") or {}
        return {
            "ip_country": location.get("country_code2"),  # ISO alpha-2, e.g. "US"
            "security": data.get("security"),
            "ok": True,
        }
    except requests.RequestException as err:
        print(f"IP risk lookup failed for {ip}: {err}")
        return {"ip_country": None, "security": None, "ok": False}

PHP

<?php
// risk_lookup.php. Uses cURL, no dependencies.

function lookup_risk(string $ip): array {
    $apiKey = getenv('IPGEO_API_KEY'); // load from env, never hardcode a key
    $query = http_build_query([
        'apiKey'  => $apiKey ?: '',
        'ip'      => $ip,
        'include' => 'security',                        // adds the security object (+2 credits)
        'fields'  => 'location.country_code2,security', // keep the payload small
    ]);

    $ch = curl_init("https://api.ipgeolocation.io/v3/ipgeo?{$query}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT_MS     => 1500, // a checkout cannot wait on a slow lookup
    ]);

    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error  = curl_error($ch);
    curl_close($ch);

    if ($body === false || $status !== 200) {
        error_log("IP risk lookup failed for {$ip}: " . ($error ?: "status {$status}"));
        return ['ip_country' => null, 'security' => null, 'ok' => false];
    }

    $data = json_decode($body, true);

    if (!is_array($data)) {
        error_log("IP risk lookup failed for {$ip}: invalid JSON response");
        return ['ip_country' => null, 'security' => null, 'ok' => false];
    }
    return [
        'ip_country' => $data['location']['country_code2'] ?? null, // ISO alpha-2, e.g. "US"
        'security'   => $data['security'] ?? null,
        'ok'         => true,
    ];
}

All three normalize failure the same way and guard every nested read (?., .get(), ??), because a partial response shouldn't throw a TypeError in the middle of an order.

Turn the signals into a decision

This is where the check earns its keep. The country comparison is one line; the judgment is the rest. It's plain logic with no network calls, so it stays the same across languages. Here it is in Node:

// decide-order.js
// ipgeolocation.io's documented threat_score bands:
// 1-19 low, 20-44 needs context, 45-79 elevated, 80-100 block or review.

function decideOrder({ ipCountry, security, billingCountry, ok }) {
  const reasons = [];

  // Lookup failed: don't reject a paying customer over outage. Route it to review.
  if (!ok || !security) return { decision: "review", reasons: ["ip_risk_unavailable"] };

  const score = security.threat_score ?? 0;
  const billing = (billingCountry || "").toUpperCase(); // normalize to ISO alpha-2
  const anonymized = Boolean(security.is_proxy || security.is_vpn || security.is_residential_proxy || security.is_tor);
  const mismatch = Boolean(ipCountry && billing && ipCountry !== billing);

  if (mismatch) reasons.push(`ip_${ipCountry}_vs_billing_${billing}`);
  if (anonymized) reasons.push("anonymized_ip");

  // Hard stop: a flagged attacker, or a top-band threat score (80-100).
  if (security.is_known_attacker || score >= 80) {
    reasons.push(security.is_known_attacker ? "known_attacker" : "threat_score_high");
    return { decision: "block", reasons };
  }
  // Manual review: a mismatch backed by an anonymized IP, or an elevated score (45-79).
  if (score >= 45) reasons.push("threat_score_elevated");
  if ((mismatch && anonymized) || score >= 45) return { decision: "review", reasons };
  // Light friction (e.g. a 3DS step-up): a lone mismatch, or a mid-band score (20-44).
  if (score >= 20) reasons.push("threat_score_needs_context");
  if (mismatch || score >= 20) return { decision: "friction", reasons };

  return { decision: "allow", reasons };
}

The reasons array is the part you'll thank yourself for later. When an order lands in review, you want to know it was ["ip_GB_vs_billing_US", "anonymized_ip"] and not guess. Log it with the order.

The same logic in Python:

# decide_order.py. Pure logic, no network calls.
# Same threat_score bands: 1-19 low, 20-44 needs context, 45-79 elevated, 80-100 block or review.

def decide_order(ip_country, security, billing_country, ok):
    # Lookup failed: don't reject a paying customer over our outage. Fail open to a soft check.
    if not ok or not security:
        return {"decision": "review", "reasons": ["ip_risk_unavailable"]}

    reasons = []
    score = security.get("threat_score") or 0
    billing = (billing_country or "").upper()  # normalize to ISO alpha-2
    anonymized = bool(
        security.get("is_proxy") or security.get("is_vpn")
        or security.get("is_residential_proxy") or security.get("is_tor")
    )
    mismatch = bool(ip_country and billing and ip_country != billing)

    if mismatch:
        reasons.append(f"ip_{ip_country}_vs_billing_{billing}")
    if anonymized:
        reasons.append("anonymized_ip")

    # Hard stop: a flagged attacker, or a top-band threat score (80-100).
    if security.get("is_known_attacker") or score >= 80:
        reasons.append("known_attacker" if security.get("is_known_attacker") else "threat_score_high")
        return {"decision": "block", "reasons": reasons}
    # Manual review: a mismatch backed by an anonymized IP, or an elevated score (45-79).
    if (score >= 45):
        reasons.append("threat_score_elevated");
    if (mismatch and anonymized) or score >= 45:
        return {"decision": "review", "reasons": reasons}
    # Light friction (e.g. a 3DS step-up): a lone mismatch, or a mid-band score (20-44).
    if (score >= 20):
        reasons.append("threat_score_needs_context");
    if mismatch or score >= 20:
        return {"decision": "friction", "reasons": reasons}

    return {"decision": "allow", "reasons": reasons}

And in PHP:

<?php
// decide_order.php. Pure logic, no network calls.
// Same threat_score bands: 1-19 low, 20-44 needs context, 45-79 elevated, 80-100 block or review.

function decide_order(?string $ipCountry, ?array $security, ?string $billingCountry, bool $ok): array {
    // Lookup failed: don't reject a paying customer over our outage. Fail open to a soft check.
    if (!$ok || !$security) {
        return ['decision' => 'review', 'reasons' => ['ip_risk_unavailable']];
    }

    $reasons = [];
    $score = $security['threat_score'] ?? 0;
    $billing = strtoupper($billingCountry ?? ''); // normalize to ISO alpha-2
    // empty() treats a missing key or a false flag the same way: not anonymized.
    $anonymized = !empty($security['is_proxy']) || !empty($security['is_vpn'])
        || !empty($security['is_residential_proxy']) || !empty($security['is_tor']);
    $mismatch = $ipCountry && $billing && $ipCountry !== $billing;

    if ($mismatch) {
        $reasons[] = "ip_{$ipCountry}_vs_billing_{$billing}";
    }
    if ($anonymized) {
        $reasons[] = 'anonymized_ip';
    }

    // Hard stop: a flagged attacker, or a top-band threat score (80-100).
    if (!empty($security['is_known_attacker']) || $score >= 80) {
        $reasons[] = !empty($security['is_known_attacker']) ? 'known_attacker' : 'threat_score_high';
        return ['decision' => 'block', 'reasons' => $reasons];
    }
    // Manual review: a mismatch backed by an anonymized IP, or an elevated score (45-79).
    if ( $score >= 45) {
        $reasons[] = 'threat_score_elevated';
    }
    if (($mismatch && $anonymized) || $score >= 45) {
        return ['decision' => 'review', 'reasons' => $reasons];
    }
    // Light friction (e.g. a 3DS step-up): a lone mismatch, or a mid-band score (20-44).
    if ( $score >= 20) {
        $reasons[] = 'threat_score_needs_context';
    }
    if ($mismatch || $score >= 20) {
        return ['decision' => 'friction', 'reasons' => $reasons];
    }

    return ['decision' => 'allow', 'reasons' => $reasons];
}

All three return the same decision and reasons for the same inputs, so the walkthrough below applies whichever one you run.

Walk it through with real data. An order with a GB billing address coming from 2.56.188.34 (US, threat_score 80, known attacker) blocks on the attacker flag, and the country mismatch is right there in the reasons. Now flip the billing country to US: the countries match, but it still blocks, because the threat score and attacker flag don't care about the address. That's the case a country-only check would have shipped. A genuine order from a Swedish customer on a Swedish ISP (91.128.103.196, country SE, clean signals) with an SE billing address sails through to allow.

Here's the same logic as a table you can tune to your own chargeback rate:

Signals	Decision
Known attacker, or `threat_score` 80-100	Block
Country mismatch with an anonymized IP (proxy, VPN, residential proxy, Tor), or `threat_score` 45-79	Manual review
Country mismatch alone, or `threat_score` 20-44	Friction (3DS step-up)
Country match, `threat_score` 0-19, no flags	Allow

If you run 3-D Secure, "friction" and "review" are where you trigger it. The liability shift on a 3DS-authenticated transaction is worth far more than the few seconds it adds for a risky order.

Getting the real client IP

The whole check depends on reading the buyer's actual IP, and behind a load balancer or a CDN that's the part people get wrong. The socket address is your proxy, not the customer. The real IP is in X-Forwarded-For, but you can't trust that header blindly, because anyone can send it.

// Express: tell the framework how many proxies sit in front of you, then read req.ip.
app.set("trust proxy", 1); // 1 = one trusted hop (your LB). Set this to your real topology.

app.post("/checkout", async (req, res) => {
  const clientIp = req.ip; // resolved from X-Forwarded-For using the trust setting above
  // Never read req.headers["x-forwarded-for"] and grab the first value yourself.
  // A client can forge that header; trust only the hop your infrastructure controls.
  // ... call lookupRisk(clientIp) and decideOrder(...) here
});

Set trust proxy to match what's actually in front of your app. Trusting too many hops lets a client spoof their way to any country they like, which quietly turns your fraud check into theater.

Handling false positives

A country mismatch is noisy, and if you block on it you'll punish good customers. The most common cases, all legitimate:

A customer in Berlin who hits your checkout through their employer's VPN, which exits in Frankfurt or even another country. Clean card, real person, mismatched IP.
Anyone traveling. A US cardholder buying from a hotel in Tokyo trips the mismatch every time.
Expats and dual-residents whose card was issued in one country while they live in another.
iCloud Private Relay and similar privacy relays. The security object flags these as is_relay, separate from is_vpn, and that distinction matters. A Private Relay user is an ordinary Apple customer, not a fraudster, so don't treat a relay like a proxy.

This is why the scoring leans on the threat signals, not the mismatch alone. The Berlin customer's corporate VPN usually carries a low threat score and no attacker flag, so they land in friction at worst, not a block. If you serve a corridor of legitimate cross-border traffic (say, a lot of real orders where the IP and billing country differ for a known reason), keep an allowlist and skip the friction for it. Tune to your numbers: if your manual-review queue fills with obvious good orders, your thresholds are too tight.

When the lookup is slow or down, and caching

Two operational decisions make or break this in production.

First, if the lookup times out or errors, the code above returns ok: false, and decideOrder sends the order to review rather than blocking it. Blocking real revenue because a third-party API had a bad minute is the wrong trade for most stores. If you're in a high-fraud category and would rather hold than risk it, flip that branch to fail closed, but make it a deliberate choice.

Second, cache by IP. The same buyer often retries checkout two or three times, and that's the same IP each time. A short cache (5 to 15 minutes, keyed on the IP) cuts both latency and credits, since each lookup costs 3 credits. Redis is the obvious home for it; an in-process LRU works for a single instance.

// Tiny in-memory cache with a TTL. Use Redis across multiple instances.
const cache = new Map();
const TTL_MS = 10 * 60 * 1000; // 10 minutes

async function lookupRiskCached(ip) {
  const hit = cache.get(ip);
  if (hit && Date.now() - hit.at < TTL_MS) return hit.value; // reuse a recent result

  const value = await lookupRisk(ip);
  if (value.ok) cache.set(ip, { value, at: Date.now() }); // only cache successful lookups
  return value;
}

Note the guard: only successful results get cached. Caching an ok: false would pin a failed lookup for ten minutes and quietly degrade every retry in that window.

A few extra notes

IPv6 works the same way. The response shape is identical, and country_code2 comes back for v6 addresses too, so the code above doesn't change.

Decide on country, not city. Country-level geolocation is the dependable layer. City and below get fuzzier, especially on mobile carriers and recently reallocated ranges, so a city mismatch is too unreliable to gate a payment on.

You're not married to one provider. MaxMind GeoIP2 and its minFraud product, IPinfo, IP2Location, and IPLocate all return an IP country, and most return some VPN or proxy signal. Stripe Radar bundles a version of this if you're already on Stripe. Pick by what's in your stack, what the free tier returns, and whether you need residential-proxy detection, which is the signal most of the cheaper options skip. The IP Security API used here is on every paid plan starting at $19 a month, so it's not a separate enterprise add-on.

And keep this in proportion. The IP-country check is a cheap pre-auth signal that sits in front of AVS and 3-D Secure, not a replacement for either. It catches a real class of stolen-card fraud before the order ships. It will not catch a cardholder who disputes their own legitimate purchase.

Drop lookupRiskCached and decideOrder into your order pipeline behind whatever checks you already run, log the reasons on every non-allow decision, and watch your review queue for a week before you tighten anything. If I were starting fresh, I'd wire 3DS to the friction and review outcomes from day one, rather than bolting it on after the first wave of mismatched-country chargebacks.

Build Impossible Travel Detection Into Your Login Flow

ABDULLAH AFZAL — Thu, 04 Jun 2026 05:54:06 +0000

Impossible travel is two logins to one account from places too far apart to travel between in the time that passed. New York at 9:00, Singapore at 9:40. No passenger makes that trip, so one of those sessions is almost certainly not the account owner. You can catch it in your own login flow with an IP lookup, the Haversine formula, and a velocity check, and this walks through the whole build in Node and Python.

It earns its place because login endpoints are under constant credential pressure. In Verizon's 2025 DBIR research on credential stuffing, credential stuffing was a median 19% of all authentication attempts across the SSO logs they analyzed, and stolen credentials were the initial access vector in 22% of breaches. Impossible travel is one of the cheapest ways to catch the attempts that actually succeed.

TL;DR:

Impossible travel flags a login when distance from the previous login divided by the time between them implies a speed no human travel can reach.
The build is small: geolocate the IP to coordinates, measure great-circle distance with the Haversine formula, divide by elapsed time, compare to a threshold around 1000 km/h.
Store each user's last login location and timestamp (Redis works well) so the next login has something to compare against.
The velocity check alone fires on every corporate-VPN user and frequent flyer. Security signals (is_vpn, is_relay, is_residential_proxy, threat_score) are what separate a real anomaly from noise.
Respond in tiers (allow, log, step-up MFA, block) and fail open: a lookup timeout should never lock a user out.

Geolocation is reliable enough at the country and region level to make this work and too rough at the street level to trust there, so the thresholds stay loose. The signal you want is "these two cities are thousands of kilometers and a few minutes apart," not "the user moved across town."

What impossible travel detection actually catches

Two terms get mixed up. A typical travel is a login from an unusual place that is still physically possible, like a user who normally signs in from Berlin appearing in Toronto after a flight. Impossible travel is a login that could not have happened given the time elapsed. The first is worth a note; the second is worth interrupting the session.

As a signal it targets account takeover. When an attacker replays stolen credentials from their own machines or a proxy pool, the source location rarely lines up with where the real user has been. Rate limiting and bot defenses thin out the automated noise at the perimeter; impossible travel catches the login that got through with a correct password. It is a strong signal, not proof. A VPN, a privacy relay, or a frequent traveler can all trip it, which is why the response matters as much as the detection. Treat a hit as "this needs more scrutiny," not "this is an attacker."

The check, before any code

The logic is short. Take the user's last login (latitude, longitude, timestamp) and the current one. Measure the great-circle distance between the two points. Divide by the hours elapsed to get an implied travel speed. If that speed is higher than anything a human can manage, flag it. Then decide what to do, using the IP's security signals to tell a real anomaly apart from a VPN exit.

Get the client IP right

The whole check depends on reading the correct client IP, and behind a load balancer or CDN the socket address is the proxy, not the user. The real address sits in X-Forwarded-For. That header is also trivially spoofable if you accept it from anywhere, so only trust it from infrastructure you control.

In Express, set the trust proxy level to the number of proxies in front of you, then read req.ip:

// One proxy/CDN in front of the app. Set the real hop count for your setup.
// Trusting X-Forwarded-For blindly lets a client spoof their location.
app.set("trust proxy", 1);

// Now req.ip is the client address as reported by your trusted proxy.
const ip = req.ip;

In FastAPI, run Uvicorn with --proxy-headers and a trusted-host list, then read the forwarded client:

# Start with: uvicorn app:app --proxy-headers --forwarded-allow-ips="10.0.0.0/8"
# request.client.host is then the forwarded client IP, not the proxy.
ip = request.client.host

Pitfall: if your app is reachable directly as well as through the proxy, an attacker can hit it directly and set their own X-Forwarded-For. Lock direct access down at the network layer, or the location signal is meaningless.

Geolocate the IP to coordinates

You need latitude and longitude for the IP. Any IP geolocation provider returns this: IPGeolocation, ipinfo, ip-api, MaxMind GeoIP2, and IPLocate all do. The examples here use IPGeolocation because the free tier returns coordinates, city, and country in one call with no card required, which keeps the tutorial to one dependency. Create a free key and put it in an environment variable.

The raw call is one GET request:

curl 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=YOUR_KEY&ip=8.8.8.8'

For 8.8.8.8 that comes back with location.city of "Mountain View", location.country_name of "United States", and coordinates under location. One detail that will bite you if you miss it: the coordinates are returned as strings, so parse them before doing math.

Node, with a timeout and a fallback so a slow lookup never blocks a login:

const IPGEO_API_KEY = process.env.IPGEO_API_KEY;
if (!IPGEO_API_KEY) {
  throw new Error("IPGEO_API_KEY is not set");
}

// withSecurity adds the VPN/proxy signals (paid tier). See the false-positive section.
async function locateIp(ip, { withSecurity = false } = {}) {
  const include = withSecurity ? "&include=security" : "";
  const url = `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}${include}`;

  try {
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    // 423 means a bogon/private IP the API won't locate. Treat as "no location".
    if (!res.ok) return null;

    const data = await res.json();
    const loc = data?.location;
    if (!loc?.latitude || !loc?.longitude) return null;

    // Coordinates arrive as strings. Reject anything that isn't a finite number.
    const lat = Number.parseFloat(loc.latitude);
    const lon = Number.parseFloat(loc.longitude);
    if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;

    return {
      lat,
      lon,
      city: loc.city ?? null,
      country: loc.country_name ?? null,
      security: data.security ?? null,
    };
  } catch (err) {
    // Timeout or network error: fail open, log for review.
    console.error(`Geo lookup failed for ${ip}: ${err.message}`);
    return null;
  }
}

Python with FastAPI, same shape:

import os
import httpx

IPGEO_API_KEY = os.environ.get("IPGEOLOCATION_API_KEY")
if not IPGEO_API_KEY:
    raise RuntimeError("IPGEOLOCATION_API_KEY is not set")

async def locate_ip(ip: str, with_security: bool = False):
    params = {"apiKey": IPGEO_API_KEY, "ip": ip}
    if with_security:
        params["include"] = "security"

    try:
        async with httpx.AsyncClient(timeout=1.5) as client:
            resp = await client.get("https://api.ipgeolocation.io/v3/ipgeo", params=params)
        if resp.status_code != 200:  # 423 for bogon/private IPs
            return None

        body = resp.json()
        loc = body.get("location") or {}
        lat, lon = loc.get("latitude"), loc.get("longitude")
        if lat is None or lon is None:
            return None

        try:                       # strings in the response; reject bad values
            lat, lon = float(lat), float(lon)
        except (TypeError, ValueError):
            return None

        return {
            "lat": lat,
            "lon": lon,
            "city": loc.get("city"),
            "country": loc.get("country_name"),
            "security": body.get("security"),
        }
    except httpx.HTTPError as err:
        print(f"Geo lookup failed for {ip}: {err}")  # fail open
        return None

A word on accuracy

Country and region accuracy is high. City-level placement is rougher, and it gets worse on mobile carriers and carrier-grade NAT, where one tower or gateway can cover a wide area. So compare distance, not exact coordinates, and keep the threshold well above any plausible margin of error. You are looking for a jump between continents, not a wobble between neighborhoods.

Measure the distance with the Haversine formula

The Haversine formula gives the great-circle distance between two latitude/longitude points, which is the shortest path over the surface of a sphere. Close enough to real distance for this purpose.

function haversineKm(lat1, lon1, lat2, lon2) {
  const R = 6371; // Earth radius in km
  const toRad = (deg) => (deg * Math.PI) / 180;
  const dLat = toRad(lat2 - lat1);
  const dLon = toRad(lon2 - lon1);
  const a =
    Math.sin(dLat / 2) ** 2 +
    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
  // Clamp to 1 so floating-point error can't push asin out of its domain.
  return 2 * R * Math.asin(Math.min(1, Math.sqrt(a)));
}

from math import radians, sin, cos, asin, sqrt

def haversine_km(lat1, lon1, lat2, lon2):
    r = 6371.0  # Earth radius in km
    d_lat = radians(lat2 - lat1)
    d_lon = radians(lon2 - lon1)
    a = sin(d_lat / 2) ** 2 + cos(radians(lat1)) * cos(radians(lat2)) * sin(d_lon / 2) ** 2
    # Clamp to 1 so floating-point error can't push asin out of its domain.
    return 2 * r * asin(min(1, sqrt(a)))

New York to Singapore is about 15,300 km. Forty minutes apart, that implies a speed near 23,000 km/h, which settles the question.

Turn distance and time into a velocity check

Speed is distance over time. The threshold is the one judgment call. A commercial jet cruises near 900 km/h, so anything materially above that is not a real trip. I use 1000 km/h to leave room for the rough edges of city-level geolocation. Two guards keep it sane: ignore short distances, which are geolocation jitter rather than travel, and handle a near-zero time gap so you do not divide by zero.

const MAX_PLAUSIBLE_KMH = 1000; // above a commercial jet (~900 km/h), with margin
const MIN_DISTANCE_KM = 100;    // below this is local movement or geo jitter

function isImpossibleTravel(prev, current) {
  const km = haversineKm(prev.lat, prev.lon, current.lat, current.lon);
  if (km < MIN_DISTANCE_KM) return false;

  const hours = (current.ts - prev.ts) / 3600;
  if (hours <= 0) return true; // same second or clock skew, but the cities are far apart

  return km / hours > MAX_PLAUSIBLE_KMH;
}

MAX_PLAUSIBLE_KMH = 1000
MIN_DISTANCE_KM = 100

def is_impossible_travel(prev, current):
    km = haversine_km(prev["lat"], prev["lon"], current["lat"], current["lon"])
    if km < MIN_DISTANCE_KM:
        return False

    hours = (current["ts"] - prev["ts"]) / 3600
    if hours <= 0:
        return True

    return (km / hours) > MAX_PLAUSIBLE_KMH

The first login for a user has nothing to compare against, so it always passes. That is fine; the check starts protecting from the second login onward.

Store login history

You need the previous login's location and time. Redis fits because the lookup happens on every login and you want it fast. Store one record per user keyed by user ID, with a TTL so dormant accounts age out.

import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL);
const HISTORY_TTL = 60 * 60 * 24 * 30; // 30 days

async function getLastLogin(userId) {
  try {
    const raw = await redis.get(`login:last:${userId}`);
    return raw ? JSON.parse(raw) : null;
  } catch (err) {
    console.error(`Redis read failed: ${err.message}`);
    return null; // fail open: no history means the check is skipped, not blocked
  }
}

async function saveLastLogin(userId, record) {
  try {
    await redis.set(`login:last:${userId}`, JSON.stringify(record), "EX", HISTORY_TTL);
  } catch (err) {
    console.error(`Redis write failed: ${err.message}`);
  }
}

import json
import redis.asyncio as redis

redis_client = redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379"))
HISTORY_TTL = 60 * 60 * 24 * 30  # 30 days

async def get_last_login(user_id: str):
    try:
        raw = await redis_client.get(f"login:last:{user_id}")
        return json.loads(raw) if raw else None
    except redis.RedisError as err:
        print(f"Redis read failed: {err}")  # fail open
        return None

async def save_last_login(user_id: str, record: dict):
    try:
        await redis_client.set(f"login:last:{user_id}", json.dumps(record), ex=HISTORY_TTL)
    except redis.RedisError as err:
        print(f"Redis write failed: {err}")

Tip: no Redis in your stack? A row per user in your existing database works the same way. You only read and write one small record per login, so the storage choice barely matters until you are doing this at high volume.

Wire it into the login flow

The check runs after the password is verified and before you hand back a session. In Express, that is middleware mounted after authentication, where req.user exists.

async function checkImpossibleTravel(req, res, next) {
  const userId = req.user?.id;
  if (!userId) return next(); // nothing authenticated to check

  const current = await locateIp(req.ip);
  if (!current) return next(); // private IP or lookup failed: fail open

  const now = Math.floor(Date.now() / 1000);
  const record = { lat: current.lat, lon: current.lon, city: current.city, ts: now };

  const prev = await getLastLogin(userId);

  if (prev && isImpossibleTravel(prev, record)) {
    // Suspicious: hold the record. Do NOT move the baseline yet, or a blocked
    // attacker overwrites the user's trusted location. Persist it after step-up.
    req.loginRisk = { impossibleTravel: true, from: prev.city, to: current.city, currentLogin: record };
    return next();
  }

  // Clean login: this becomes the new trusted baseline.
  await saveLastLogin(userId, record);
  next();
}

In FastAPI, call it inside the login route once credentials check out, since middleware runs before you know who the user is:

import time

async def evaluate_login(user_id: str, ip: str):
    current = await locate_ip(ip)
    if not current:
        return None  # fail open

    record = {"lat": current["lat"], "lon": current["lon"],
              "city": current["city"], "ts": int(time.time())}

    prev = await get_last_login(user_id)

    if prev and is_impossible_travel(prev, record):
        # Suspicious: hold the record, don't move the baseline yet (see note below).
        return {"impossible_travel": True, "from": prev["city"],
                "to": current["city"], "current_login": record}

    # Clean login: this becomes the new trusted baseline.
    await save_last_login(user_id, record)
    return None

One rule makes or breaks this: only promote a login to the trusted baseline once it is actually trusted. The code above saves it right away for a clean login but holds it when the jump looks impossible. Persist the held record only after the user clears step-up authentication. Skip that and a blocked attacker overwrites the baseline, and the real user's next login then looks anomalous against the attacker's location.

// Call after the user passes step-up (correct MFA code, passkey, and so on).
async function onStepUpPassed(req) {
  const userId = req.user?.id;
  const record = req.loginRisk?.currentLogin; // the login we held back
  if (userId && record) await saveLastLogin(userId, record);
}

async def on_step_up_passed(user_id: str, risk: dict):
    record = (risk or {}).get("current_login")  # the login we held back
    if record:
        await save_last_login(user_id, record)

At this point a real account takeover from a fresh location gets flagged. So does every employee on a corporate VPN.

The false positives that will bite you

Run the velocity check on real traffic and the flags pile up from people who are not attackers:

Someone on a corporate VPN whose egress sits in another country.
An iPhone user behind iCloud Private Relay, which presents a relay IP, not their own.
A phone hopping between a mobile carrier and home WiFi, where the carrier IP geolocates hundreds of kilometers off.
A genuine frequent flyer who lands and logs in before your record updates.

Block on the raw velocity signal and you will lock these people out daily. The fix is to ask one more question about the IP: is it an anonymizing service, and how risky is it.

Suppress false positives with security signals

IPGeolocation's IP Security API returns risk signals for an IP: a threat_score from 0 to 100, plus flags for VPN, proxy, residential proxy, Tor, relay, and more, with provider names and confidence scores. It is a dedicated /v3/security endpoint, but you can fold it into the same geolocation call with include=security, which gets you coordinates and risk in one request. That is the withSecurity flag the lookup function already takes.

A full response looks like this (for the documented example IP 2.56.188.34):

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

The distinction that matters here is residential proxy versus commercial VPN. A commercial VPN or a privacy relay is overwhelmingly a real person protecting their traffic, so an impossible-travel hit from one is usually noise, especially on a device you already recognize. A residential proxy is different: those are sold to route traffic through other people's home connections specifically to look like organic users and dodge IP reputation, and they show up in credential-stuffing campaigns far more than in normal browsing. So the response leans on two things: how anonymized the IP is, and whether the device is one you have seen before.

function decideResponse(risk, security, context = {}) {
  if (!risk?.impossibleTravel) return "ALLOW";

  const s = security ?? {};
  const threatScore = Number(s.threat_score ?? 0);
  const knownDevice = Boolean(context.knownDevice);

  // Strong abuse signals win regardless of the travel jump.
  if (s.is_known_attacker || threatScore >= 80 || s.is_residential_proxy) {
    return "BLOCK";
  }
  // A commercial VPN or relay explains the jump, but attackers use them too.
  // Trust it only on a device we recognize; otherwise step up.
  if (s.is_vpn || s.is_relay || s.is_proxy) {
    return knownDevice ? "LOG" : "CHALLENGE";
  }
  // Clean IP, real geographic impossibility: step up to MFA before trusting the session.
  return "CHALLENGE";
}

def decide_response(risk, security, context=None):
    if not risk or not risk.get("impossible_travel"):
        return "ALLOW"

    context = context or {}
    s = security or {}
    threat_score = int(s.get("threat_score") or 0)
    known_device = bool(context.get("known_device"))

    if s.get("is_known_attacker") or threat_score >= 80 or s.get("is_residential_proxy"):
        return "BLOCK"
    if s.get("is_vpn") or s.get("is_relay") or s.get("is_proxy"):
        return "LOG" if known_device else "CHALLENGE"
    return "CHALLENGE"

The response now keys on both signals. A known device on a VPN or relay during an impossible-travel hit gets logged; the same hit from an unknown device gets a step-up challenge instead of a free pass. A residential proxy, a known attacker, or a threat score at the ceiling blocks regardless. A clean IP making a real geographic jump always challenges. The knownDevice flag is the tunable part: feed it from a device cookie or fingerprint (the same signal mentioned at the end of this article), and move the thresholds to match your own risk tolerance.

The lookups split along the free and paid line. For the free velocity check, call locateIp(req.ip). To get the VPN, relay, proxy, residential-proxy, and threat-score signals this section relies on, call locateIp(req.ip, { withSecurity: true }) (and locate_ip(ip, with_security=True) in Python), then pass the security object and the device context into the decision: decideResponse(risk, current.security, { knownDevice }). Security data is a paid-tier feature, so the velocity check stands on its own and you add this layer when you are ready to cut the false positives.

Respond, don't just block

Detection is the easy half. The response is where you protect users without alienating them. Four tiers cover it:

ALLOW: no anomaly. The default for almost every login.
LOG: a recognized device on a VPN, relay, or proxy. The jump is explained and the device is known, so record it and move on.
CHALLENGE: a real geographic impossibility on a clean IP, or an unknown device behind a VPN or proxy. Require a second factor before issuing the session.
BLOCK: anomaly plus strong abuse signals (residential proxy, known attacker, or a threat score at the ceiling). Refuse and alert.

And fail open. If the geolocation or security lookup times out, or Redis is down, allow the login and log the gap. A missed anomaly is a recoverable risk. A customer locked out at 2am because your IP provider had a slow minute is a support ticket and a churned account. Availability wins on the login path; run the check, but never let it become a hard dependency.

A few notes before you ship

Store and compare timestamps in UTC, or a user crossing a timezone will produce phantom anomalies. IPv6 works the same way; the geolocation call handles both address families, so no special casing. Pair the location signal with a device signal if you can: a recognized device cookie or fingerprint lets you soften the response for a known laptop on a new network, which is most of your real false positives.

And know when not to build this. If you are already on an identity platform, the feature probably ships in the box: WorkOS Radar, Microsoft Entra ID Protection, Okta, and Datadog all detect impossible travel. Configure theirs instead of rebuilding it. Build your own when you are not on one of those, when you want the signal feeding your own risk engine, or when you want full control over the thresholds and the response.

Start with the velocity check on the free geolocation tier and watch your logs for a week before you switch on any blocking. Add the security signals once you see how many of your "impossible" logins are just people on a VPN. Keep the threshold loose the whole time, and let the step-up prompt, not a hard block, carry the cases you are unsure about.

ASN Lookup for Security Engineers: From Concept to Code

ABDULLAH AFZAL — Tue, 19 May 2026 18:21:25 +0000

An ASN lookup is the fastest way to find out who actually operates the network behind an IP address. Every publicly routable IP on the internet belongs to an autonomous system, and that autonomous system number (ASN) identifies the network operator, what infrastructure they run, and who they peer with. For security engineers, this is a first-order pivot point: when an IP shows up in your logs tied to credential stuffing or port scanning, the ASN tells you whether you're looking at a residential ISP, a cloud hosting provider, or a known bulletproof hosting operation.

This tutorial covers what ASNs are, how they fit into internet routing, and then gets to the practical part: querying ASN data programmatically with curl, Python, and JavaScript so you can fold it into your investigation workflow or SIEM pipeline.

TL;DR

An ASN (Autonomous System Number) uniquely identifies a network that participates in internet routing via BGP.
As of 2025, roughly 120,000 ASNs had been allocated globally, while the number actively visible in BGP routing tables varied by dataset and vantage point.
ASNs classify into three types: stub (one upstream), multi-homed (multiple upstreams), and transit (carries traffic for others).
Security engineers use ASN data for threat attribution, network-level blocking, infrastructure mapping, and log enrichment.
Programmatic ASN lookups return the network operator, organization type (ISP, hosting, business, education), route prefixes, and peering relationships.
This tutorial includes working code for ASN lookups in curl, Python, and JavaScript using ipgeolocation.io's ASN API.

In short: IP addresses identify devices, ASNs identify the networks those devices belong to. Knowing the network behind an IP is often more actionable than knowing the IP itself.

What Is an Autonomous System (and Why Does It Have a Number)

An autonomous system (AS) is a collection of IP address ranges, called prefixes, that operate under a single routing policy managed by one organization. An ISP like Comcast, a cloud provider like AWS, and a CDN like Cloudflare each operate their own autonomous systems. Internally, an AS can run whatever routing protocols it wants (OSPF, IS-IS, EIGRP). Externally, it presents one consistent set of rules about which IP prefixes it controls and how traffic reaches them.

Each AS gets a unique number: its ASN. These are assigned by IANA through five Regional Internet Registries (RIRs): ARIN (North America), RIPE NCC (Europe, Middle East, Central Asia), APNIC (Asia-Pacific), LACNIC (Latin America), and AFRINIC (Africa). The original 16-bit format allowed 65,536 ASNs. The 32-bit format, standardized in RFC 6793, extends that to over 4.2 billion. As of 2025, roughly 120,000 ASNs had been allocated globally, while the number actively visible in BGP routing tables varied by dataset and vantage point.

Three types matter in practice:

Stub AS: connects to only one upstream provider. A small company with a single ISP connection. Most ASNs are stubs.
Multi-homed AS: connects to two or more upstreams for redundancy. A mid-size enterprise with connections to both Cogent and Lumen.
Transit AS: carries traffic between other autonomous systems. The backbone providers (AS3356 Lumen, AS2914 NTT, AS174 Cogent) that form the internet's core routing infrastructure. The glue that holds all of this together is BGP (Border Gateway Protocol). When an AS wants the internet to know about its IP prefixes, it announces them via BGP. Each announcement includes an AS-PATH: the sequence of ASNs that traffic traverses to reach the prefix. Routers use the AS-PATH to choose the best route, typically the shortest one.

A concrete example: your browser requests a page hosted in Frankfurt. Your ISP (say, AS7922 Comcast) checks its BGP table and finds that the shortest path to the destination prefix goes through AS3356 (Lumen) to AS24940 (Hetzner). Three ASNs, three AS-path hops.

Why Security Engineers Care About ASN Data

Threat Attribution Beyond the IP

An IP address can change hands hourly in cloud environments. An ASN identifies the network operator, which is far more stable. When you see a cluster of malicious requests coming from 5 different IPs, they might all resolve to the same ASN. That's not 5 separate actors; that's one network.

Suppose your WAF flags credential stuffing attempts from 185.220.101.x. You look up the ASN: AS205100, F3 Netze e.V., a Tor exit node operator in Germany. That single fact reframes the incident. You're not dealing with a compromised residential user; you're dealing with traffic deliberately routed through an anonymization network. The response changes from "investigate the user" to "rate-limit the network."

Tip: The type field in ASN data is your first filter. HOSTING and ISP ASNs produce most bot traffic. EDUCATION and BUSINESS ASNs are more likely to be legitimate. It's a rough heuristic, not a rule, but it cuts noise.

ASN-Based Blocking and Allowlisting

Individual IP blocking is a game of whack-a-mole. Attackers rotate IPs constantly. ASN-level blocking is coarser but more durable: if an autonomous system consistently sources malicious traffic, blocking it at the network level eliminates entire IP ranges at once.

A practical example: hosting providers like Hetzner (AS24940), OVHcloud (AS16276), and DigitalOcean (AS14061) are popular with both legitimate developers and attackers. You probably can't block them outright. But you can apply stricter rate limits and CAPTCHA challenges to traffic originating from hosting ASNs while letting residential ISP ASNs through with less friction. The ASN's type field (ISP vs HOSTING vs BUSINESS) enables this segmentation without maintaining manual IP lists.

Infrastructure Mapping with Network Topology

Basic ASN lookups tell you who operates a network. Topology data, upstream and downstream relationships, tells you how that network connects to the rest of the internet.

When investigating a phishing campaign, you find the domain resolves to an IP in AS64500 (a small hosting provider). Pulling the downstream data reveals that AS64500 has three downstream ASNs, two of which have shown up in threat feeds before. That's not a coincidence; it's infrastructure reuse across campaigns. The upstream data shows AS64500 buys transit from a single provider, which gives you an escalation path for abuse reports.

This kind of analysis is impossible with IP-level data alone. It requires the network topology layer that ASN data provides.

SIEM and Log Enrichment

Raw firewall logs are walls of IP addresses. Enriching each IP with its ASN, organization name, and network type transforms those logs from "1,000 IPs hit the login endpoint" into "380 of those IPs belong to three hosting providers, 50 belong to Tor exit ASNs, and the rest are residential ISPs." That's actionable intelligence.

Adding ASN data to your SIEM pipeline lets you aggregate by network operator instead of individual IP. When AS16276 (OVHcloud) shows up in 200 failed login events across 40 different IPs, that's one signal, not 40.

How to Query ASN Data Programmatically

What You Need

An API key from ipgeolocation.io
curl (for quick lookups), Python 3.8+, or Node.js 18+ Alternatives exist in this space. Team Cymru, HackerTarget, ipinfo, and MaxMind GeoLite2 all offer ASN data. This tutorial uses ipgeolocation.io's ASN endpoint because it returns ASN details plus routes, peers, upstreams, and downstreams in a single call, which is the part that matters for security analysis.

Pitfall: ASN data from the unified IP geolocation endpoint on most providers gives you the basic AS number and organization. If you need route prefixes and peering relationships, you need a dedicated ASN endpoint or a separate BGP data source.

curl

Set your API key as an environment variable first:

export IPGEO_API_KEY="your_api_key_here"

The examples below pipe output to jq for readability. Drop | jq . if you don't have it installed.

The fastest way to look up an IP's ASN:

curl -s "https://api.ipgeolocation.io/v3/asn?apiKey=${IPGEO_API_KEY}&ip=8.8.8.8" | jq .

Response:

{
  "ip": "8.8.8.8",
  "asn": {
    "as_number": "AS15169",
    "organization": "Google LLC",
    "country": "US",
    "type": "BUSINESS",
    "domain": "google.com",
    "date_allocated": "2000-03-10",
    "asn_name": "GOOGLE",
    "allocation_status": "ASSIGNED",
    "num_of_ipv4_routes": "1737",
    "num_of_ipv6_routes": "727",
    "rir": "ARIN"
  }
}

Route counts and peering relationships change over time as BGP data evolves. The values above reflect a point-in-time snapshot.

To pull network topology for a specific ASN:

curl -s "https://api.ipgeolocation.io/v3/asn?apiKey=${IPGEO_API_KEY}&asn=AS24940&include=peers,upstreams,downstreams,routes" | jq .

This returns the full picture: every IP prefix the AS announces, who it peers with, who provides its upstream transit, and who sits downstream. For AS24940 (Hetzner), the response includes announced IPv4 and IPv6 routes, plus the transit and peering relationships that connect Hetzner to the rest of the internet.

Python

Install the requests library if you haven't already:

pip install requests

import os
import requests

API_KEY = os.environ.get("IPGEO_API_KEY")
if not API_KEY:
    raise RuntimeError("Missing IPGEO_API_KEY environment variable")

BASE_URL = "https://api.ipgeolocation.io/v3/asn"

def lookup_ip_asn(ip_address):
    """Resolve an IP to its ASN and network details."""
    try:
        resp = requests.get(
            BASE_URL,
            params={"apiKey": API_KEY, "ip": ip_address},
            timeout=(2.0, 5.0),
        )
        resp.raise_for_status()
        data = resp.json()

        asn_data = data.get("asn", {})
        return {
            "ip": data.get("ip"),
            "as_number": asn_data.get("as_number"),
            "organization": asn_data.get("organization"),
            "type": asn_data.get("type"),
            "country": asn_data.get("country"),
            "rir": asn_data.get("rir"),
        }
    except requests.exceptions.Timeout:
        print(f"Timeout looking up ASN for {ip_address}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"ASN lookup failed for {ip_address}: {e}")
        return None


def get_asn_topology(as_number):
    """Pull full network topology for an ASN: routes, peers, upstreams, downstreams."""
    try:
        resp = requests.get(
            BASE_URL,
            params={
                "apiKey": API_KEY,
                "asn": as_number,
                "include": "routes,peers,upstreams,downstreams",
            },
            timeout=(2.0, 10.0),
        )
        resp.raise_for_status()
        return resp.json().get("asn", {})
    except requests.exceptions.RequestException as e:
        print(f"Topology lookup failed for {as_number}: {e}")
        return None


if __name__ == "__main__":
    # Basic IP-to-ASN lookup
    result = lookup_ip_asn("8.8.8.8")
    if result:
        print(f"{result['ip']} -> {result['as_number']} ({result['organization']}, {result['type']})")

    # Full topology for a hosting provider
    topology = get_asn_topology("AS24940")
    if topology:
        routes = topology.get("routes", [])
        peers = topology.get("peers", [])
        upstreams = topology.get("upstreams", [])
        downstreams = topology.get("downstreams", [])
        print(f"AS24940 announces {len(routes)} routes, peers with {len(peers)} ASNs")
        print(f"  Upstreams: {[u['as_number'] for u in upstreams]}")
        print(f"  Downstreams: {[d['as_number'] for d in downstreams]}")

The two functions cover the two core use cases: lookup_ip_asn for enriching individual IPs in a log pipeline, and get_asn_topology for deeper investigation when you need to understand a network's structure.

A longer timeout on the topology call (10 seconds vs 5) accounts for the larger response payload when routes and peering data are included.

JavaScript (Node.js)

const API_KEY = process.env.IPGEO_API_KEY;
if (!API_KEY) {
  throw new Error("Missing IPGEO_API_KEY environment variable");
}

const BASE_URL = "https://api.ipgeolocation.io/v3/asn";

async function lookupIpAsn(ipAddress) {
  const url = `${BASE_URL}?apiKey=${API_KEY}&ip=${encodeURIComponent(ipAddress)}`;

  try {
    const resp = await fetch(url, { signal: AbortSignal.timeout(5000) });

    if (!resp.ok) {
      console.error(`ASN lookup returned ${resp.status} for ${ipAddress}`);
      return null;
    }

    const data = await resp.json();
    const asn = data.asn ?? {};

    return {
      ip: data.ip,
      asNumber: asn.as_number,
      organization: asn.organization,
      type: asn.type,
      country: asn.country,
      rir: asn.rir,
    };
  } catch (err) {
    if (err.name === "TimeoutError") {
      console.error(`Timeout looking up ASN for ${ipAddress}`);
    } else {
      console.error(`ASN lookup failed for ${ipAddress}:`, err.message);
    }
    return null;
  }
}

async function getAsnTopology(asNumber) {
  const url = `${BASE_URL}?apiKey=${API_KEY}&asn=${encodeURIComponent(asNumber)}&include=routes,peers,upstreams,downstreams`;

  try {
    const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });

    if (!resp.ok) {
      console.error(`Topology lookup returned ${resp.status} for ${asNumber}`);
      return null;
    }

    const data = await resp.json();
    return data.asn ?? {};
  } catch (err) {
    console.error(`Topology lookup failed for ${asNumber}:`, err.message);
    return null;
  }
}

// Usage
const result = await lookupIpAsn("8.8.8.8");
if (result) {
  console.log(`${result.ip} -> ${result.asNumber} (${result.organization}, ${result.type})`);
}

const topo = await getAsnTopology("AS24940");
if (topo) {
  const routes = topo.routes ?? [];
  const peers = topo.peers ?? [];
  console.log(`AS24940 announces ${routes.length} routes, peers with ${peers.length} ASNs`);
}

Both functions mirror the Python version. AbortSignal.timeout(5000) prevents hung connections from blocking your pipeline. The ?? (nullish coalescing) operator handles missing fields without throwing.

Reading the Response: What Each Field Tells You

The basic ASN response contains eleven fields. Here's what matters for security work:

as_number: The ASN itself, formatted with the "AS" prefix (e.g., "AS15169"). This is the identifier you'll use for blocking rules, SIEM correlation, and threat feed matching.

organization: The entity registered with the RIR as the AS holder. For cloud providers, this is the provider, not the customer. AS16509 is "Amazon.com, Inc." even though the IP you're investigating belongs to a fintech startup running on AWS.

type: One of ISP, HOSTING, BUSINESS, or EDUCATION. This is your first-pass risk signal. HOSTING ASNs produce a disproportionate share of automated attacks. ISP ASNs carry mostly residential traffic. EDUCATION ASNs are universities.

country: ISO 3166-1 alpha-2 country code for the AS registration. Not necessarily where the traffic originates (a Hetzner server in Finland still shows "country": "DE" because Hetzner is registered in Germany).

rir: Which Regional Internet Registry manages the ASN. Useful for abuse reporting: RIPE NCC has different abuse processes than ARIN.

routes (with include=routes): The IP prefixes this AS announces to the internet. This is the AS's footprint. If you see malicious traffic from 5 IPs and all fall within prefixes announced by the same ASN, that confirms you're dealing with one network.

peers, upstreams, downstreams (with include=peers,upstreams,downstreams): The network's BGP relationships. Upstreams are transit providers (who the AS pays for internet access). Downstreams are customer networks. Peers are networks exchanging traffic directly. For investigation, downstreams are particularly interesting: they reveal smaller networks hiding behind a hosting provider's ASN.

Putting It Together: An Investigation Walkthrough

You pull your morning alerts and find 47 failed SSH login attempts across 3 IPs overnight: 185.220.101.34, 185.220.101.42, and 185.220.101.52. Different IPs, same /24 range, but you want to confirm this is one actor.

Step 1: Look up the ASN for any of the three IPs. They all resolve to AS205100, F3 Netze e.V., registered in Germany. The organization name and the related prefix data point to Tor-exit traffic. That reframes the incident immediately: you're not dealing with a compromised residential user, you're dealing with traffic deliberately routed through an anonymization network.

Step 2: Pull the topology with include=routes,upstreams. The routes show a small number of prefixes (the 185.220.101.0/24 range among them). The upstreams show two transit providers. A stub-like topology for what is effectively a single-purpose network.

Step 3: Check your SIEM for historical traffic from AS205100. You find it appears in 12 previous incidents over the past 90 days, all brute-force attempts. That's a pattern.

Step 4: Decision. Hard-blocking AS205100 is reasonable here because it's a single-purpose Tor exit network, and your service has no legitimate users routing through Tor exits. For a multi-purpose hosting ASN like Hetzner or DigitalOcean, you'd rate-limit instead of block.

The whole investigation took 4 API calls and 3 minutes. Without ASN data, you'd have looked up 3 IPs individually, found they're "in Germany," and missed the network-level pattern entirely.

Caching and Performance Notes

ASN assignments change infrequently. An IP's ASN changes when the IP block is sold or reallocated, which happens on the order of months or years, not hours. A 24-hour TTL on cached ASN lookups is aggressive enough for most security use cases without wasting quota on redundant calls.

For high-volume enrichment (processing millions of log entries), consider a local database instead of per-request API calls. MMDB-format ASN databases eliminate network latency entirely and support the same lookup patterns. The trade-off is update frequency: you're working with a daily snapshot instead of real-time data. For most enrichment pipelines, that's acceptable.

When the ASN API is unreachable, fail open. ASN enrichment adds context but isn't load-bearing for most security decisions. Log the unenriched event and backfill later rather than dropping traffic or blocking alerts because the lookup timed out.

A Few Extra Notes

Private ASNs exist. The ranges 64512-65534 (16-bit) and 4200000000-4294967294 (32-bit) are reserved for private use. These are used internally by organizations with complex routing but should never appear in public BGP tables. If you see a private ASN in external traffic, something is misconfigured upstream, and that's worth investigating on its own.

ASN data is one signal, not a verdict. AS16509 (Amazon AWS) hosts both legitimate SaaS products and attack infrastructure. Blocking it would break half the internet. Use ASN data to inform decisions (add friction, increase logging, require CAPTCHA), not to make them unilaterally.

The organization field can mislead. Cloud providers sublease IP ranges. The ASN registrant is Amazon, Google, or Microsoft, but the actual user of the IP is whoever rented that instance. For cloud ASNs, pair ASN data with reverse DNS, TLS certificate inspection, or company-level enrichment to get closer to the real operator.

For a deeper reference on autonomous systems, BGP routing, and ASN assignment history, the ARIN ASN guide and the ipgeolocation.io ASN guide both cover the conceptual side in more depth than this tutorial has room for.

Add IP Fraud Scoring to Your Auth Flow

ABDULLAH AFZAL — Tue, 12 May 2026 11:01:05 +0000

Credential stuffing bots hit login endpoints at thousands of requests per minute, rotating through IP addresses as they go. By the time your rate limiter reacts, the damage is done. An IP fraud score check sits before your auth logic, scores each IP from 0 to 100 and lets you decide whether to allow, challenge, or block.

This tutorial adds that check to a Node.js/Express and Python/Flask login route. You'll also get the cURL version for testing. The whole thing takes about 30 minutes to wire up.

TL;DR

An IP fraud score is a 0-100 rating aggregating VPN/proxy/Tor detection, known attacker history, bot activity, and cloud provider flags into a single number
The dedicated /v3/security endpoint returns a structured security object: threat score, VPN/proxy/Tor/relay flags, provider names ("Nord VPN", "922 Proxy"), confidence scores, and last-seen dates
Graduated thresholds: 0-19 allow, 20-44 log and flag, 45-79 force MFA, 80-100 block
Fail-open on the API check for login routes (if the scoring API is down, let users through with logging). Fail-closed for payment endpoints.
Cache results in Redis with a 5-minute TTL to avoid per-request API calls
Code below covers cURL, Node.js/Express middleware, and Python/Flask decorator

One API call before your auth logic flags risky IPs often seen in credential stuffing, residential proxy abuse, and known attacker traffic before they hit your password check. The response includes enough detail (provider names, confidence scores, timestamps) to build graduated rules, not just a binary block.

What the Security API Returns

Most IP reputation APIs give you a handful of boolean flags: is_vpn: true, is_proxy: false, done. That tells you what the IP is, but not how confident the detection is or which provider it belongs to.

The ipgeolocation.io Security API returns a structured object per lookup: threat score, anonymization flags, provider attribution, confidence scores, and last-seen timestamps. Here's what a flagged IP actually looks like:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 90,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 99,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

The difference matters for auth decisions. Knowing an IP is "a VPN" is less useful than knowing it's NordVPN with 99% confidence, last seen yesterday, and also flagged as a known attacker with a threat score of 80. The first gives you a boolean. The second gives you a policy.

is_residential_proxy is worth calling out specifically. Residential proxies route traffic through real ISP connections, so they look legitimate to basic VPN detectors. Services like 922 Proxy, Oxylabs, and Bright Data sell this access. If your fraud rules only check is_vpn and is_proxy, residential proxy traffic sails right through. The dedicated flag catches it.

Setup

You need Node.js 18+ or Python 3.8+, and an ipgeolocation.io API key with security access.

Tip: IPGeolocation, IPQS, Scamalytics, AbuseIPDB, and MaxMind minFraud all offer IP risk scoring with different pricing models, detection depth, and response shapes. I'm using ipgeolocation.io for these examples because the /v3/security endpoint returns provider attribution and confidence scores in one call, which keeps the graduated-response code clean.

Set your API key as an environment variable. Do not hardcode it.

export IPGEO_API_KEY="your_api_key_here"

Install the dependencies you'll need:

# Node.js
npm install express ioredis

# Python
pip install flask requests

Test with cURL First

Before writing middleware, call the endpoint directly to see the response shape for a known IP:

curl -s "https://api.ipgeolocation.io/v3/security?apiKey=${IPGEO_API_KEY}&ip=8.8.8.8" | python3 -m json.tool

For 8.8.8.8 (Google Public DNS), you'll get a low threat score and is_cloud_provider: true with cloud_provider_name: "Google LLC". That's a clean IP doing exactly what you'd expect.

Try it with a known proxy or Tor exit IP if you have one handy. The threat_score jump and the flag combination tells you whether your thresholds will catch what you care about.

Node.js/Express Middleware

Here's the middleware. It runs before your login handler, checks the IP against the Security API, and attaches the score to the request object so downstream handlers can act on it.

// ip-risk-middleware.js
const API_KEY = process.env.IPGEO_API_KEY;
const SECURITY_URL = 'https://api.ipgeolocation.io/v3/security';

if (!API_KEY) {
  throw new Error('Missing IPGEO_API_KEY environment variable');
}

async function ipRiskCheck(req, res, next) {
  // Trust the first X-Forwarded-For entry if behind a reverse proxy.
  // Verify your proxy sets this correctly; spoofable if not.
  const clientIp =
    req.headers['x-forwarded-for']?.split(',')[0]?.trim() ||
    req.socket.remoteAddress;

  try {
    const response = await fetch(
      `${SECURITY_URL}?apiKey=${API_KEY}&ip=${clientIp}`,
      { signal: AbortSignal.timeout(1500) } // 1.5s timeout; don't let a slow API stall login
    );

    if (!response.ok) {
      // API error: fail open for login routes, log the failure
      console.error(`IP risk API returned ${response.status} for ${clientIp}`);
      req.ipRisk = { score: 0, flags: {}, failedOpen: true };
      return next();
    }

    const data = await response.json();
    const security = data.security ?? {};
    const score = security.threat_score ?? 0;

    // Attach the full security object for downstream handlers
    req.ipRisk = {
      score,
      flags: security,
      ip: clientIp,
    };

    // Graduated response based on threat score
    if (score >= 80) {
      console.warn(`BLOCKED: IP ${clientIp} scored ${score}`, {
        vpn: security.is_vpn,
        proxy: security.is_proxy,
        attacker: security.is_known_attacker,
      });
      return res.status(403).json({ error: 'Request blocked' });
    }

    if (score >= 45) {
      // Elevated risk: force MFA regardless of account settings
      req.requireMfa = true;
    }

    next();
  } catch (err) {
    // Network timeout or fetch failure: fail open, log it
    console.error(`IP risk check failed for ${clientIp}: ${err.message}`);
    req.ipRisk = { score: 0, flags: {}, failedOpen: true };
    next();
  }
}

module.exports = { ipRiskCheck };

Wire it into your login route:

const express = require('express');
const { ipRiskCheck } = require('./ip-risk-middleware');

const app = express();
app.use(express.json());

// Apply the risk check to auth routes only.
// Running it on every route burns API quota on static assets.
app.post('/api/login', ipRiskCheck, (req, res) => {
  const { score, flags, failedOpen } = req.ipRisk;

  // Log every auth attempt with its risk score for later threshold tuning
  console.log(`Login attempt from ${req.ipRisk.ip}: score=${score}`, {
    failedOpen,
    vpn: flags.is_vpn,
    proxy: flags.is_proxy,
    residential_proxy: flags.is_residential_proxy,
    tor: flags.is_tor,
  });

  if (req.requireMfa) {
    return res.status(200).json({
      mfaRequired: true,
      reason: 'elevated_ip_risk',
    });
  }

  // Normal login flow continues here
  res.json({ success: true });
});

app.listen(3000, () => console.log('Running on :3000'));

A few things to note. AbortSignal.timeout(1500) caps the API call at 1.5 seconds. IPGeolocation.io's public status page reports low average API response times, so 1.5 seconds is intentionally conservative. Network hiccups still happen, and a stalled risk check should never block a user from logging in. The middleware fails open: if the API is unreachable, the user gets through with failedOpen: true logged so you can audit later.

If you're behind Cloudflare, Nginx, or an AWS ALB, make sure trust proxy is configured in Express (app.set('trust proxy', 1)) so Express resolves the client IP from X-Forwarded-For correctly. Without it, req.socket.remoteAddress gives you the proxy's IP, not the client's. Only trust X-Forwarded-For when your edge proxy overwrites incoming forwarded headers. Never trust a client-supplied forwarded header directly.

Python/Flask Equivalent

Same logic, different runtime. This uses a decorator pattern so you can apply it selectively to routes.

# ip_risk.py
import os
import functools
import requests
from flask import request, jsonify, g

API_KEY = os.environ.get('IPGEO_API_KEY')
SECURITY_URL = 'https://api.ipgeolocation.io/v3/security'

if not API_KEY:
    raise RuntimeError('Missing IPGEO_API_KEY environment variable')


def check_ip_risk(f):
    @functools.wraps(f)
    def decorated(*args, **kwargs):
        # Behind a reverse proxy, X-Forwarded-For holds the real client IP.
        # Take the first entry; later entries are intermediate proxies.
        client_ip = (
            request.headers.get('X-Forwarded-For', '').split(',')[0].strip()
            or request.remote_addr
        )

        try:
            resp = requests.get(
                SECURITY_URL,
                params={'apiKey': API_KEY, 'ip': client_ip},
                timeout=(1.0, 1.5),  # 1s connect, 1.5s read
            )
            resp.raise_for_status()
            data = resp.json()
            security = data.get('security', {})
            score = security.get('threat_score', 0)
        except (requests.RequestException, ValueError) as err:
            # Fail open: API down should not lock users out of login
            print(f'IP risk check failed for {client_ip}: {err}')
            g.ip_risk = {'score': 0, 'flags': {}, 'failed_open': True}
            return f(*args, **kwargs)

        g.ip_risk = {
            'score': score,
            'flags': security,
            'ip': client_ip,
            'failed_open': False,
        }

        if score >= 80:
            print(f'BLOCKED: {client_ip} scored {score}')
            return jsonify({'error': 'Request blocked'}), 403

        if score >= 45:
            g.require_mfa = True

        return f(*args, **kwargs)

    return decorated

Apply it to your login route:

from flask import Flask, g, jsonify
from ip_risk import check_ip_risk

app = Flask(__name__)


@app.route('/api/login', methods=['POST'])
@check_ip_risk
def login():
    risk = g.ip_risk

    app.logger.info(
        'Login attempt from %s: score=%d, failed_open=%s',
        risk.get('ip'),
        risk['score'],
        risk.get('failed_open'),
    )

    if getattr(g, 'require_mfa', False):
        return jsonify({'mfa_required': True, 'reason': 'elevated_ip_risk'})

    # Normal login flow
    return jsonify({'success': True})

The timeout=(1.0, 1.5) tuple sets a 1-second connection timeout and 1.5-second read timeout. Python's requests library hangs indefinitely without an explicit timeout, which is the kind of bug that doesn't surface until your login endpoint stops responding at 2 AM.

Cache Results with Redis

Calling the Security API on every single login request works fine under moderate traffic, but it's wasteful. An IP's threat score doesn't change second-to-second. A 5-minute Redis cache cuts your API usage dramatically without meaningfully delaying threat detection.

// Add to ip-risk-middleware.js
const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');

const CACHE_TTL = 300; // 5 minutes in seconds

async function getCachedRisk(ip) {
  try {
    const cached = await redis.get(`ip-risk:${ip}`);
    return cached ? JSON.parse(cached) : null;
  } catch {
    return null; // Redis down: skip cache, hit API
  }
}

async function setCachedRisk(ip, security) {
  try {
    await redis.set(
      `ip-risk:${ip}`,
      JSON.stringify(security),
      'EX',
      CACHE_TTL
    );
  } catch {
    // Cache write failure is non-critical; log and move on
  }
}

Then in the middleware, check the cache before calling the API:

// Inside ipRiskCheck, before the fetch call:
const cached = await getCachedRisk(clientIp);
if (cached) {
  req.ipRisk = { score: cached.threat_score ?? 0, flags: cached, ip: clientIp };
  // Apply the same threshold logic as the non-cached path
  if (cached.threat_score >= 80) {
    return res.status(403).json({ error: 'Request blocked' });
  }
  if (cached.threat_score >= 45) {
    req.requireMfa = true;
  }
  return next();
}
// ...existing fetch call, then after parsing:
await setCachedRisk(clientIp, security);

Five minutes is a reasonable default. If you're seeing active attacks that rotate IPs faster than that, drop it to 60 seconds. If your traffic is low enough that you're under quota anyway, skip the cache entirely and keep the code simpler.

Setting Your Fraud Score Thresholds

The threshold bands I've used above are based on what ipgeolocation.io documents:

0-19: Low risk. Clean residential IP, no flags. Allow normally.
20-44: Some signals. Maybe a datacenter IP or a consumer VPN. Log it, maybe flag for review, but don't add friction yet.
45-79: Elevated. Multiple flags firing, or a known proxy service. Force MFA. A legitimate user clears MFA in seconds. A bot doesn't.
80-100: High confidence. Known attacker, active proxy with provider attribution, or multiple overlapping anonymization signals. Block the request.

Start permissive. Deploy the middleware in log-only mode (no blocking, no MFA forcing) for a week. Look at the score distribution for your actual traffic. If 10% of your legitimate users come through corporate VPNs and score 30-40, you don't want your MFA threshold at 30. Tune based on your data, not on defaults.

For payment endpoints, flip the logic: fail-closed instead of fail-open. If the scoring API is down and you can't verify the IP, hold the transaction for manual review rather than letting it through. The risk calculus is different when money moves.

Edge Cases Worth Handling

Corporate NAT and shared IPs. A large office with 500 employees behind one public IP looks like a single entity to any IP-based system. If someone on that network triggered a flag last week, the whole office inherits it. Graduated responses handle this better than hard blocks. Score 35 with MFA is a minor inconvenience for a real employee. A hard block at the same score locks out the whole building.

VPN users who aren't malicious. Journalists, security researchers, and privacy-conscious developers use commercial VPNs daily. The is_vpn: true flag alone shouldn't trigger a block. Pair it with threat_score: a NordVPN IP with a score of 15 is a privacy-conscious user. The same VPN range with a score of 75 and is_known_attacker: true is a different story.

iCloud Private Relay and similar services. Apple's iCloud Private Relay, Cloudflare WARP, and Chrome's IP Protection are growing. The is_relay flag distinguishes these from traditional VPNs. Blocking relay traffic means blocking a meaningful chunk of iOS users. Unless you have a specific reason (geo-compliance, content licensing), treat relay IPs as low-risk.

Cloud provider IPs. Your CI/CD pipeline, webhook senders, and monitoring services all originate from AWS, GCP, or Azure ranges. The is_cloud_provider flag with cloud_provider_name helps you whitelist known sources. A login attempt from "Google LLC" infrastructure is suspicious. A health check from the same range is expected.

GDPR and IP logging. If you serve EU users, storing IP addresses with threat scores counts as personal data processing under GDPR. Set a retention policy (30-90 days for security logs is defensible), document the legitimate interest basis, and make sure your privacy policy covers it.

Wrapping Up

Drop the middleware into your auth routes, deploy in log-only mode for a week, and look at your actual score distribution before turning on the blocks. The thresholds above are starting points. Your traffic patterns will tell you where to tighten.

For high-traffic services, add the Redis cache from the start. For payment flows, switch to fail-closed and hold transactions when the API is unreachable. When traffic outgrows the API tier, batch analysis with the bulk endpoint (up to 50,000 IPs per POST) handles post-incident forensics without burning your real-time quota.