DEV Community: ABDULLAH AFZAL

Why FastAPI geolocation middleware is the wrong tool

ABDULLAH AFZAL — Wed, 16 Sep 2026 07:08:33 +0000

Search for FastAPI geolocation middleware and you'll get the same answer every time: subclass BaseHTTPMiddleware, call an IP lookup API, stash the result on request.state.geo. It works. It's also the wrong tool, and the reason is boring rather than clever.

Middleware runs before routing. It cannot know which endpoint matched, so it fires on everything: /health, /metrics, /docs, /openapi.json, your static mounts, and every CORS preflight OPTIONS. You've just put a network call in front of your liveness probe.

A dependency runs after routing, only where you declare it. That one ordering difference fixes the problem and brings typing and testability along with it.

TL;DR

BaseHTTPMiddleware runs on every request including health checks and docs routes. Depends() runs only on routes that ask for it.
Fix client IP resolution first. request.client.host is your load balancer, and X-Forwarded-For is caller-controlled unless you configure Uvicorn to trust it.
Return a Pydantic model from the dependency so the route signature shows what it gets and your editor can autocomplete it.
Keep geolocation and risk as two separate dependencies. Cheap routes take geo, sensitive routes take both.
Fail open on lookup errors, cache in Redis, and swap the whole thing out in tests with app.dependency_overrides.

You'll end with two composable dependencies, GeoContext and RiskProfile, that any route can pull in by adding one parameter. Roughly 120 lines total, Redis-cached, and testable without mocking HTTP.

Why FastAPI geolocation middleware is the wrong tool

The routing-order problem is the one that actually bites. Starlette runs middleware in the ASGI stack before the router resolves a path, so a geolocation middleware has no way to say "skip this for /health". You end up with a hand-maintained path prefix blocklist inside the middleware, which drifts the moment someone adds a route.

Latency is the part people feel in production. A Kubernetes liveness probe hits /health every few seconds. If your middleware makes an outbound API call on every request, that probe now depends on a third-party network round trip. When the upstream gets slow, probes time out, and your orchestrator restarts a pod that was perfectly healthy. I've watched a team spend most of a day on that one.

Then there's typing. request.state.geo is a bag with no schema. Your editor can't complete it, your reviewer can't see it in the function signature, and a typo in request.state.geo.country_code2 fails at runtime in whichever route nobody tested.

BaseHTTPMiddleware also has its own reputation for edge-case behaviour around exceptions, streaming responses, and background tasks. Plenty of people run it happily. It's still more machinery than this job needs.

What a dependency gives you instead

FastAPI's dependency injection system gives you four things, in the order you'll care about them. Per-route opt-in, so /health stays a pure function. A typed return value that shows up in the signature. Automatic caching within a single request, so declaring the same dependency twice doesn't call the API twice. And dependency_overrides, which makes testing a three-line fixture instead of a mock HTTP layer.

The FastAPI dependency docs cover the mechanics well. What they don't cover is the case for using them where your instinct says middleware, which is most of what follows.

Get the client IP right first

Everything downstream is worthless if you geolocate the wrong address. request.client.host gives you the peer that opened the TCP connection. Behind nginx, an ALB, Cloudflare, or Railway's Envoy layer, that peer is the proxy, and you'll cheerfully look up your own infrastructure for every visitor.

The fix is not to parse X-Forwarded-For in your application code. That header is whatever the caller typed unless something upstream has overwritten it, so trusting the leftmost entry hands any user the ability to claim any country they like. This is the single most common mistake in the geolocation middleware examples floating around.

Let Uvicorn do it. Its proxy header settings rewrite request.client.host from the forwarded headers, but only for peers you explicitly trust:

uvicorn app.main:app \
  --proxy-headers \
  --forwarded-allow-ips="10.0.0.0/8"

The default for --forwarded-allow-ips is 127.0.0.1, which is not what you want the moment your proxy lives on another host. Set it to your load balancer's actual range and nothing else. With that in place, request.client.host is trustworthy and the dependency stays short:

# app/deps/client_ip.py
import ipaddress
from fastapi import Request


def get_client_ip(request: Request) -> str | None:
    """The caller's public IP, or None when we don't have one worth looking up."""
    client = request.client
    if client is None:
        # Some ASGI transports (including parts of the test client) omit this.
        return None

    try:
        parsed = ipaddress.ip_address(client.host)
    except ValueError:
        return None

    # Private, loopback and reserved addresses have no public geolocation.
    # Returning None here saves a pointless round trip on every local request.
    if parsed.is_private or parsed.is_loopback or parsed.is_reserved:
        return None

    return client.host

Returning None rather than raising is deliberate. A missing IP is a normal condition, not an error, and the callers downstream all handle None already.

Running it locally

Every request from your laptop arrives as 127.0.0.1, so get_client_ip returns None and the geo dependency short-circuits before it ever calls out. That's the behaviour you want, and it means local development costs nothing.

When you do want real data in development, hardcode a test IP behind an environment flag rather than pointing the lookup at a private address. IP geolocation APIs reject private and bogon ranges, and you'll spend twenty minutes debugging an error response that was correct all along.

The geolocation dependency

One call, one model. Here's the request shape:

curl -s 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196'

And the full response, which is worth reading once before you decide what to keep:

{
  "ip": "91.128.103.196",
  "location": {
    "continent_code": "EU",
    "continent_name": "Europe",
    "country_code2": "SE",
    "country_code3": "SWE",
    "country_name": "Sweden",
    "country_name_official": "Kingdom of Sweden",
    "country_capital": "Stockholm",
    "state_prov": "Stockholms län",
    "state_code": "SE-AB",
    "district": "Stockholm",
    "city": "Stockholm",
    "zipcode": "164 40",
    "latitude": "59.40510",
    "longitude": "17.95510",
    "is_eu": true,
    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
    "geoname_id": "9972319",
    "country_emoji": "🇸🇪"
  },
  "country_metadata": {
    "calling_code": "+46",
    "tld": ".se",
    "languages": ["sv-SE", "se", "sma", "fi-SE"]
  },
  "currency": { "code": "SEK", "name": "Swedish Krona", "symbol": "kr" },
  "asn": {
    "as_number": "AS1257",
    "organization": "Tele2 Sverige AB",
    "country": "SE"
  },
  "time_zone": {
    "name": "Europe/Stockholm",
    "offset": 1,
    "offset_with_dst": 2,
    "current_time": "2026-09-07 16:55:30.494+0200",
    "current_time_unix": 1788792930.494,
    "current_tz_abbreviation": "CEST",
    "current_tz_full_name": "Central European Summer Time",
    "is_dst": true
  }
}

Two things in there will trip you up. latitude and longitude are strings, not floats, so cast them before any arithmetic. And country_metadata.languages is an array, not the comma-separated string that several other providers return. If you're porting code from another API, that's where it breaks.

I'm using ipgeolocation.io for these examples because the geolocation and threat endpoints share a response envelope, which keeps the two dependencies below nearly identical. IPGeolocation, ipinfo, ip-api, MaxMind GeoIP2, IPLocate and IP2Location all hand back roughly the same country-level payload, so swap in whichever is already in your stack. Only the parsing function changes.

Now the dependency:

# app/deps/geo.py
import logging
import os
from typing import Annotated

import httpx
from fastapi import Depends, Request
from pydantic import BaseModel

from app.deps.client_ip import get_client_ip

logger = logging.getLogger(__name__)


class GeoContext(BaseModel):
    ip: str
    country_code: str | None = None
    country_name: str | None = None
    city: str | None = None
    is_eu: bool = False
    currency_code: str | None = None
    asn_organization: str | None = None
    timezone: str | None = None


async def get_geo(
    request: Request,
    ip: Annotated[str | None, Depends(get_client_ip)],
) -> GeoContext | None:
    if ip is None:
        return None

    api_key = os.environ.get("IPGEO_API_KEY")
    if not api_key:
        logger.warning("IPGEO_API_KEY is not set, skipping geolocation")
        return None

    try:
        response = await request.app.state.http.get(
            "/ipgeo", params={"apiKey": api_key, "ip": ip}
        )
        response.raise_for_status()
        payload = response.json()
    except (httpx.HTTPError, ValueError) as exc:
        # Fail open. A geo lookup should never be why a page returns 500.
        logger.warning("Geolocation lookup failed for %s: %s", ip, exc)
        return None

    location = payload.get("location") or {}
    return GeoContext(
        ip=payload.get("ip", ip),
        country_code=location.get("country_code2"),
        country_name=location.get("country_name"),
        city=location.get("city"),
        is_eu=bool(location.get("is_eu", False)),
        currency_code=(payload.get("currency") or {}).get("code"),
        asn_organization=(payload.get("asn") or {}).get("organization"),
        timezone=(payload.get("time_zone") or {}).get("name"),
    )

The or {} on every nested access is not paranoia. Responses vary by key configuration, and payload["location"]["city"] on an IP with no city resolution is a KeyError in production at 3am.

Fail open or fail closed

The code above fails open: if the lookup breaks, get_geo returns None and the route carries on with whatever default it has. For pricing, currency, or language, that's obviously right. Nobody should see a 500 because a third-party API had a bad minute.

Fail closed is the correct choice in exactly one situation, which is when the lookup is a control rather than a decoration. If you're blocking sanctioned jurisdictions, "we couldn't check" has to mean "denied", because a fail-open geoblock is a geoblock that stops working the moment someone can make your API call time out. Decide which one each route needs and write it down, because the default you pick silently becomes policy everywhere.

Adding risk data as a second dependency

Country tells you where someone claims to be. It says nothing about whether they're behind a VPN, a residential proxy, or a datacenter. For a signup or checkout route you usually want both, and the IP Security API returns the threat side as its own endpoint:

curl -s 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=145.223.7.7'

{
  "ip": "145.223.7.7",
  "security": {
    "threat_score": 90,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["NetNut", "ProxyScrape", "Oxy Labs", "DataImpulse"],
    "proxy_confidence_score": 99,
    "proxy_last_seen": "2026-09-01",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["SurfShark VPN", "Ishaan VPN"],
    "vpn_confidence_score": 99,
    "vpn_last_seen": "2026-07-31",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "bot_confidence_score": 0,
    "bot_operator_name": "",
    "bot_type": "",
    "is_known_good_bot": false,
    "bot_last_seen": "",
    "is_spam": true,
    "is_cloud_provider": true,
    "cloud_provider_name": "Brander Group Inc.",
    "is_corporate_gateway": false,
    "corporate_gateway_type": "",
    "corporate_gateway_provider_name": ""
  }
}

Named providers are the part worth keeping. A boolean tells you the IP is a proxy; ["NetNut", "ProxyScrape", "Oxy Labs", "DataImpulse"] tells your fraud team which network it belongs to, which is the difference between an alert and an investigation. is_corporate_gateway matters for the opposite reason: a shared Zscaler or Netskope egress address looks like a proxy by every other measure, and blocking it means blocking an entire enterprise customer.

The dependency mirrors the geo one closely enough that I'll only show what differs:

# app/deps/risk.py
import logging
import os
from typing import Annotated

import httpx
from fastapi import Depends, Request
from pydantic import BaseModel, Field

from app.deps.client_ip import get_client_ip

logger = logging.getLogger(__name__)

BLOCK_THRESHOLD = 80


class RiskProfile(BaseModel):
    ip: str
    threat_score: int = 0
    is_vpn: bool = False
    is_proxy: bool = False
    is_residential_proxy: bool = False
    is_tor: bool = False
    is_anonymous: bool = False
    is_cloud_provider: bool = False
    is_corporate_gateway: bool = False
    vpn_provider_names: list[str] = Field(default_factory=list)
    proxy_provider_names: list[str] = Field(default_factory=list)

    @property
    def should_block(self) -> bool:
        # A corporate gateway scores like a proxy but is a legitimate employer
        # egress. Blocking it locks out everyone behind that company's network.
        if self.is_corporate_gateway:
            return False
        return self.threat_score >= BLOCK_THRESHOLD


async def get_risk(
    request: Request,
    ip: Annotated[str | None, Depends(get_client_ip)],
) -> RiskProfile | None:
    if ip is None:
        return None

    api_key = os.environ.get("IPGEO_API_KEY")
    if not api_key:
        return None

    try:
        response = await request.app.state.http.get(
            "/security", params={"apiKey": api_key, "ip": ip}
        )
        response.raise_for_status()
        security = (response.json() or {}).get("security") or {}
    except (httpx.HTTPError, ValueError) as exc:
        logger.warning("Security lookup failed for %s: %s", ip, exc)
        return None

    return RiskProfile(ip=ip, **{
        key: security[key] for key in RiskProfile.model_fields
        if key in security
    })

That dict comprehension keeps the model and the parser from drifting apart when you add a field. It also means an unexpected key in the response is ignored rather than raising.

Composing them without doubling your calls

Both dependencies declare get_client_ip. FastAPI's dependency injection caches sub-dependency results within a single request by default, so get_client_ip runs once even though two dependencies asked for it. Same applies if a route declares get_risk and a router-level dependency also uses it. You get one call, not two.

If you ever need the opposite, Depends(get_client_ip, use_cache=False) forces a re-run. I've needed that exactly never for this pattern, but it's there.

Wiring it to routes

A type alias per dependency keeps the signatures readable:

# app/routes.py
from typing import Annotated

from fastapi import APIRouter, Depends, HTTPException

from app.deps.geo import GeoContext, get_geo
from app.deps.risk import RiskProfile, get_risk

Geo = Annotated[GeoContext | None, Depends(get_geo)]
Risk = Annotated[RiskProfile | None, Depends(get_risk)]

router = APIRouter()


@router.get("/health")
async def health() -> dict[str, str]:
    # No dependencies. No network calls. This is the whole point.
    return {"status": "ok"}


@router.get("/pricing")
async def pricing(geo: Geo) -> dict[str, str]:
    return {"currency": geo.currency_code if geo else "USD"}


@router.post("/signup")
async def signup(geo: Geo, risk: Risk) -> dict[str, str]:
    if risk and risk.should_block:
        logger.info("Blocked signup from %s, score %s", risk.ip, risk.threat_score)
        raise HTTPException(status_code=403, detail="Signup unavailable")
    return {"country": geo.country_code if geo else "unknown"}

Three routes, three different policies, one set of dependencies. /health does nothing, /pricing pays for geo only, /signup takes both. Middleware cannot express that without a path blocklist.

For a whole section of the API, put the check on the router. The catch worth knowing: router-level dependencies run but their return value is thrown away, so they're for enforcement, not injection.

# app/routes.py, continued. Imports and the Geo/Risk aliases are above.


async def require_acceptable_risk(risk: Risk) -> None:
    """Router-level guard. Return value is discarded, so it raises or passes."""
    if risk and risk.should_block:
        raise HTTPException(status_code=403, detail="Unavailable")


checkout = APIRouter(
    prefix="/checkout",
    dependencies=[Depends(require_acceptable_risk)],
)


@checkout.post("/confirm")
async def confirm(risk: Risk) -> dict[str, int]:
    # get_risk already ran for the guard. The cache means this is free.
    return {"score": risk.threat_score if risk else 0}

Testing, which is where this pays off

app.dependency_overrides swaps any dependency for a fake. No HTTP mocking, no responses library, no network in the test suite:

# tests/test_pricing.py
import pytest
from fastapi.testclient import TestClient

from app.deps.geo import GeoContext, get_geo
from app.main import app


def fake_geo_sweden() -> GeoContext:
    return GeoContext(
        ip="91.128.103.196",
        country_code="SE",
        is_eu=True,
        currency_code="SEK",
    )


@pytest.fixture
def client():
    app.dependency_overrides[get_geo] = fake_geo_sweden
    try:
        yield TestClient(app)
    finally:
        # Clear or the override leaks into every later test in the session.
        app.dependency_overrides.clear()


def test_pricing_uses_local_currency(client):
    assert client.get("/pricing").json()["currency"] == "SEK"

Testing the same logic in middleware means intercepting an outbound HTTP call, which is doable but noisier. The testing-dependencies docs cover the override mechanics if you want the full picture.

One HTTP client for the process

Both dependencies reach for request.app.state.http. Create that once in the lifespan handler, not per request, because a fresh AsyncClient throws away connection pooling and TLS session reuse on every call:

# app/main.py
from contextlib import asynccontextmanager

import httpx
from fastapi import FastAPI

from app.routes import checkout, router


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.http = httpx.AsyncClient(
        base_url="https://api.ipgeolocation.io/v3",
        # Separate read timeout because a slow upstream is the realistic
        # failure, not a slow handshake. Keep the total well under your
        # own request budget.
        timeout=httpx.Timeout(connect=1.0, read=1.5, write=1.0, pool=1.0),
    )
    try:
        yield
    finally:
        await app.state.http.aclose()


app = FastAPI(lifespan=lifespan)
app.include_router(router)
app.include_router(checkout)

Caching with Redis

The same IP will hit you many times in a session, and paying for a lookup on every request is wasteful whichever provider you use. Redis over an in-process dict, for one specific reason: with four Uvicorn workers, an in-process cache gives you four separate caches and a hit rate a quarter of what you think you're getting. That bug is invisible in staging with one worker.

Two TTLs, because the data ages differently. Geolocation for an IP is stable for days. Threat signals are not, since an address can be clean this morning and a residential proxy exit by lunchtime.

# app/cache.py
import json
import logging

import redis.asyncio as redis

logger = logging.getLogger(__name__)

GEO_TTL = 24 * 60 * 60   # geolocation barely moves
RISK_TTL = 15 * 60       # threat signals go stale fast


async def cached_json(
    client: redis.Redis, key: str, ttl: int, loader
) -> dict | None:
    """Read-through cache. Redis being down degrades to a direct call."""
    try:
        hit = await client.get(key)
        if hit is not None:
            return json.loads(hit)
    except (redis.RedisError, ValueError) as exc:
        logger.warning("Cache read failed for %s: %s", key, exc)

    value = await loader()
    if value is None:
        return None

    try:
        await client.set(key, json.dumps(value), ex=ttl)
    except redis.RedisError as exc:
        logger.warning("Cache write failed for %s: %s", key, exc)

    return value

Wrap the API call in get_geo with cached_json(redis_client, f"geo:{ip}", GEO_TTL, loader) and you're done. Note that Redis failures are caught and logged rather than raised. A cache outage should slow you down, not take you offline.

Tip: Cache geolocation by /24 rather than by exact IP if your traffic is consumer-heavy. Neighbouring addresses in a residential block almost always resolve to the same city, and your hit rate improves noticeably. Don't do this for risk data, where the whole point is per-address precision.

When middleware actually is right

Dependencies aren't a replacement for middleware, and an article claiming otherwise would be selling you something. Middleware is correct whenever the work genuinely applies to every request, or has to happen outside the route's world.

Request ID generation, access logging, CORS, response header mutation, and compression all belong there, and the middleware docs show the shape. So does the thing this article depends on: Uvicorn's proxy header handling is itself middleware, and it works because rewriting the client IP really does apply to every request equally.

The rule of thumb: if the work applies to every request without exception, use middleware. If it applies to some routes, produces a value the route needs, or you want to fake it in tests, use a dependency. Geolocation and risk enrichment are firmly in the second category.

A few extra notes

IPv6 works without changes. ipaddress.ip_address handles both families and the API takes either, so the code above needs nothing extra. Worth an actual test case, though, because IPv6 is where the assumption that an address is four dot-separated numbers usually surfaces.

Rate limits are an ordinary failure. A 429 raises HTTPStatusError, gets caught by the same except block, and fails open like any other error. If you're hitting limits regularly, the Redis TTL is the lever, not a bigger plan.

Bulk endpoints exist for the offline case. If you're enriching historical logs rather than live requests, the bulk lookup takes up to 50,000 addresses per call, and doing that in a loop of single requests is the slow way to learn it exists.

Drop the two dependency files into an existing app and wire them to one route before you touch the rest. The client IP piece is the part that breaks in production and the part you can verify in about a minute: log request.client.host on a deployed route and confirm it isn't your load balancer. If it is, your --forwarded-allow-ips is wrong and everything downstream has been geolocating your own infrastructure.

How to Block Cloud-Hosted Signups Without Blocking Real Users

ABDULLAH AFZAL — Tue, 15 Sep 2026 09:53:14 +0000

A signup from a cloud-hosted IP is almost never a real person. Nobody opens a laptop, routes through an AWS datacenter in us-east-1, and fills in your registration form by hand. Datacenter traffic at a signup endpoint is automation: scrapers, credential-stuffing scripts, mass account creation, the odd misconfigured integration.

So blocking it sounds trivial. Grab a list of cloud IP ranges, drop anything that matches, ship it. Then someone on your own team gets locked out, an entire company behind a corporate proxy can't register, and you're staring at a support ticket wondering what you broke.

The fix isn't a longer blocklist. It's gating on the right signal, and recognizing the handful of cloud IPs that are actually humans. Here's both, with code you can paste into a Node or Python signup route.

TL;DR

A cloud/datacenter IP at signup is a strong automation-risk signal, but it does not prove the request is non-human. If your signup policy blocks cloud-origin traffic, gate on is_cloud_provider, not on "is this user anonymized."

Keep the VPN/proxy/Tor/relay decision separate and softer. Those flags catch real, privacy-minded users, so challenge them, don't hard-block.

Two cloud IPs you must not block: corporate secure-web-gateway egress (is_corporate_gateway, one IP fronts a whole company) and declared crawlers (is_known_good_bot).

Use cloud_provider_name to log an auditable reason for every block. Do not use the provider name alone as an allowlist: shared cloud providers host many unrelated customers.

Static CIDR lists rot and know nothing about gateways or good bots. That's the failure mode behind most "it blocked my own laptop" bugs.

In practice this is one lookup and about fifteen lines of decision logic. The lookup returns a set of boolean flags for an IP; the logic decides which flags mean "a server is pretending to be a user" and which mean "a real user is behind a shared address." Get that split right and you can substantially reduce the false positives of a blunt cloud-IP block.

A datacenter IP is a different signal than a VPN

Most "block anonymous traffic" advice lumps everything together: VPN, proxy, Tor, relay, datacenter, all treated as one risk bucket. That's the mistake. These are two different axes.

A person on a corporate VPN, iCloud Private Relay, or a mobile network that happens to route through a proxy is very often a real user with a real reason to sign up. Block them and you're turning away customers. A request from an EC2 instance or a rented Hetzner box is a different thing entirely: there's no human sitting at that IP. The traffic exists because someone rented compute and pointed it at your form.

So the useful question at a signup endpoint isn't "is this IP anonymized?" It's "is this IP a server?" Those overlap sometimes, but they're not the same, and conflating them is why blunt gates generate support tickets.

The signal you want: is_cloud_provider

Any decent IP intelligence API will tell you whether an IP belongs to a hosting provider. The one I'll use here, ipgeolocation.io, returns it as a boolean plus the provider's name, alongside the rest of the risk signals in a single response. Here's the full shape from the dedicated /v3/security endpoint for a real hosting-provider IP:

{
  "ip": "2.56.188.35",
  "security": {
    "threat_score": 35,
    "is_tor": false,
    "is_proxy": false,
    "proxy_provider_names": [],
    "proxy_confidence_score": 0,
    "proxy_last_seen": "",
    "is_residential_proxy": false,
    "is_vpn": false,
    "vpn_provider_names": [],
    "vpn_confidence_score": 0,
    "vpn_last_seen": "",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": false,
    "is_known_attacker": true,
    "is_bot": false,
    "bot_confidence_score": 0,
    "bot_operator_name": "",
    "bot_type": "",
    "is_known_good_bot": false,
    "bot_last_seen": "",
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A.",
    "is_corporate_gateway": false,
    "corporate_gateway_type": "",
    "corporate_gateway_provider_name": ""
  }
}

The two fields this whole tutorial hangs on are is_cloud_provider and cloud_provider_name. The boolean tells you the IP belongs to cloud-provider address space; the name tells you which provider owns that space. That name is what lets you allowlist providers you trust and log a real reason when you block, instead of shipping a mystery 403. Notice this IP is also flagged is_known_attacker with a low-ish threat_score of 35, which is common for bulletproof hosts: the same address is a datacenter and a repeat offender.

/v3/security is the endpoint to reach for when security is all you need. It costs 2 credits per lookup and returns only the security object, which keeps your credit usage predictable. If you already call /v3/ipgeo for geolocation, you can add include=security and get the same object bundled with location and ASN data in one call instead of two.

Heads up: the security signals are a paid feature. A free-plan key returns 401 on the security endpoint. Plans start at $19/month, which is the honest trade-off to weigh against the free alternatives below.

Before you start

You'll need Node 18+ (for global fetch) or Python 3.10+, and an API key.

Security data on ipgeolocation.io lives on the paid plans; the free plan covers basic geolocation only. Grab an API key and set it as an environment variable so it never lands in your source:

export IPGEO_API_KEY="your_key_here"

If paying for this doesn't fit, there are free options that also flag hosting IPs. ipapi.is has a free datacenter endpoint, IPLocate exposes a free is_hosting flag, and offline libraries like py-cloudip (Python) or cloud-ip-detector (PHP) match an IP against bundled CIDR data with no network call at all. They'll all tell you an IP is a datacenter. What the paid signal here adds is the provider name, the corporate-gateway and good-bot context that prevents the false positives later in this post, and a threat_score in the same response. Pick based on whether you need that context or just a boolean.

A quick smoke test against a known hosting IP before you write any code:

curl -s -X GET \
  'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=2.56.188.35'

You should get the security object back with is_cloud_provider set to true.

Detect a cloud-hosted signup

curl

The raw call takes an IP as a query parameter. Leave ip off entirely and the API reads the caller's own address, which is handy for a browser-side check:

# Specific IP
curl -s 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=2.56.188.35'

# Caller IP (no ip param) — returns the requester's own address
curl -s 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY'

Node.js

Two functions: one that fetches the security object, one that makes the actual decision. Keeping them separate means the decision logic is easy to unit test without hitting the network.

const IPGEO_KEY = process.env.IPGEO_API_KEY;
const SECURITY_URL = 'https://api.ipgeolocation.io/v3/security';

async function getSecurity(ip) {
  if (!IPGEO_KEY) throw new Error('IPGEO_API_KEY is not set');

  const url = `${SECURITY_URL}?apiKey=${IPGEO_KEY}&ip=${encodeURIComponent(ip)}`;

  // 1.5s ceiling. A signup should never hang on a third-party lookup.
  const res = await fetch(url, { signal: AbortSignal.timeout(1500) });

  if (!res.ok) {
    // 423 = bogon/private IP, 401 = key or plan problem, 429 = quota hit.
    throw new Error(`security lookup failed: HTTP ${res.status}`);
  }

  const data = await res.json();
  return data?.security ?? null; // null if the object is missing
}

Now the decision. This is the part worth reading twice, because it's where the false positives get filtered out:

// Cloud providers you run on or trust. Matched against cloud_provider_name.
const CLOUD_ALLOWLIST = new Set(['Your Own Infra Ltd.']);

function isCloudHostedSignup(security) {
  if (!security) return false;               // no data: treat as not-cloud
  if (!security.is_cloud_provider) return false;

  // Real employees behind an enterprise proxy. One IP fronts a whole company,
  // so blocking it locks out everyone at that customer.
  if (security.is_corporate_gateway) return false;

  // Declared crawlers (Googlebot, ChatGPT, uptime monitors). They won't sign
  // up, but if you reuse this gate on other routes, don't block them.
  if (security.is_known_good_bot) return false;

  // Providers you've explicitly decided are fine.
  if (CLOUD_ALLOWLIST.has(security.cloud_provider_name || '')) return false;

  return true; // a server renting an IP, aimed at your form: gate it
}

Python

Same two-part shape. requests uses a (connect, read) timeout tuple, and .get() with a default keeps a missing field from throwing:

import os
import requests

IPGEO_KEY = os.environ.get("IPGEOLOCATION_API_KEY")
SECURITY_URL = "https://api.ipgeolocation.io/v3/security"

CLOUD_ALLOWLIST = {"Your Own Infra Ltd."}


def get_security(ip: str) -> dict | None:
    if not IPGEO_KEY:
        raise RuntimeError("IPGEOLOCATION_API_KEY is not set")

    try:
        resp = requests.get(
            SECURITY_URL,
            params={"apiKey": IPGEO_KEY, "ip": ip},
            timeout=(1.0, 1.5),  # (connect, read) seconds
        )
        resp.raise_for_status()
    except requests.RequestException as exc:
        # Log and let the caller decide fail-open vs fail-closed.
        print(f"security lookup failed for {ip}: {exc}")
        return None

    return resp.json().get("security")


def is_cloud_hosted_signup(security: dict | None) -> bool:
    if not security or not security.get("is_cloud_provider"):
        return False
    if security.get("is_corporate_gateway"):   # real employees, shared IP
        return False
    if security.get("is_known_good_bot"):      # declared crawler
        return False
    if (security.get("cloud_provider_name") or "") in CLOUD_ALLOWLIST:
        return False
    return True

Gate the signup route

Wiring it into Express takes three things the naive version skips: the correct client IP, a cache, and an explicit failure policy.

const express = require('express');
const app = express();

// Behind a load balancer or CDN? Tell Express how many proxies you actually
// run, then req.ip is the real client. Don't trust more hops than exist, or a
// client can spoof X-Forwarded-For and bypass the gate.
app.set('trust proxy', 1);

// Cache per IP so repeated attempts from one address don't each cost 2 credits.
// A Map is fine to start; swap for Redis once you have more than one instance.
const cache = new Map();
const TTL_MS = 10 * 60 * 1000; // 10 minutes is plenty for signup abuse

async function cachedSecurity(ip) {
  const hit = cache.get(ip);
  if (hit && Date.now() - hit.at < TTL_MS) return hit.security;

  const security = await getSecurity(ip); // may throw
  cache.set(ip, { security, at: Date.now() });
  return security;
}

async function blockCloudSignups(req, res, next) {
  try {
    const security = await cachedSecurity(req.ip);
    if (isCloudHostedSignup(security)) {
      // Log the provider so the block is auditable, not a mystery 403.
      console.warn(`blocked cloud signup: ${req.ip} (${security.cloud_provider_name})`);
      return res.status(403).json({ error: 'Signups from hosting providers are not allowed.' });
    }
  } catch (err) {
    // Fail OPEN: a lookup outage shouldn't stop real users signing up.
    // If this endpoint is genuinely high-risk, flip this to fail closed.
    console.error(`security check skipped for ${req.ip}: ${err.message}`);
  }
  return next();
}

app.post('/signup', blockCloudSignups, (req, res) => {
  // ... your normal signup handler ...
  res.status(201).json({ ok: true });
});

Fail-open is the right default for a signup form. The cost of a lookup outage blocking real users is worse than a few bot signups slipping through during the outage. If you were gating something higher-stakes, like a password reset or a payout request, you'd make the opposite call and fail closed.

Which signal should gate what

The reason to pull the full security object instead of just the cloud boolean is that one response tells you how to treat every kind of traffic, not just servers. Here's how I map the flags to actions at a signup endpoint:

Signal in `security`	What it usually means at signup	Action
`is_cloud_provider` true, nothing else notable	A server renting a datacenter IP	Block
`is_corporate_gateway` true	Real employees behind an enterprise proxy (Zscaler, Netskope)	Allow, and don't rate-limit per IP
`is_known_good_bot` true	A declared crawler (Googlebot, ChatGPT)	Ignore, it won't sign up
`is_known_attacker` true, or `bot_type` is `credential_stuffing` / `brute_force`	An active attack	Block
`is_residential_proxy` true	Often abuse hiding in home IPs	Challenge, or block on high `threat_score`
`is_vpn` / `is_proxy` / `is_relay` / `is_tor` (i.e. `is_anonymous`)	Frequently a real, privacy-minded user	Step-up or challenge, don't hard-block
`threat_score` 80 to 100	Aggregated high risk	Block or send to manual review

The row that matters most for keeping users happy is the anonymized one. is_anonymous is true whenever VPN, proxy, Tor, or relay is detected, and a lot of those are ordinary people. Treat that as a reason to add friction, not to slam the door.

The false positives that lock out real users

This is where naive cloud blocking goes wrong, and it's the reason to use context-aware data instead of a raw CIDR list.

Static lists rot, and they block your own team. The classic bug is a developer who parses a datacenter IP list, drops every match, and then can't sign in from the office because their own egress moved into a range the list now covers. Lists carry no context and go stale between updates. The security data here refreshes at least twice a day and, more importantly, tells you when a "cloud" IP is actually a corporate gateway or a known-good bot.

Corporate gateways are real employees on a shared cloud IP. Enterprise secure web gateways like Zscaler and Netskope route a whole company's browser traffic through the vendor's cloud, so it reaches you from the vendor's address space. That space is registered to the vendor, so is_cloud_provider is true, but blocking it would lock out every employee at that customer. The API marks these separately:

{
  "ip": "87.58.66.106",
  "security": {
    "is_cloud_provider": true,
    "cloud_provider_name": "Zscaler Switzerland GmbH",
    "is_corporate_gateway": true,
    "corporate_gateway_type": "secure_web_gateway",
    "corporate_gateway_provider_name": "Zscaler",
    "is_anonymous": false,
    "threat_score": 5
  }
}

That's why the classifier bails the moment is_corporate_gateway is true. (Full response includes the other fields; trimmed here to the ones that matter.)

Good bots run from cloud space too. Search and AI crawlers mostly operate out of rented infrastructure, so they trip is_cloud_provider. At a signup endpoint this is moot, since crawlers don't POST registration forms, but if you reuse the same gate on content or pricing pages you'd start blocking Googlebot and ChatGPT. The is_known_good_bot flag is the allowlist:

{
  "ip": "4.227.36.0",
  "security": {
    "is_bot": true,
    "bot_type": "ai_crawler",
    "bot_operator_name": "ChatGPT",
    "is_known_good_bot": true,
    "is_cloud_provider": true,
    "cloud_provider_name": "Microsoft Corporation",
    "threat_score": 15
  }
}

Your own automation is a cloud IP. If a partner integration or your own server-to-server flow legitimately creates accounts, it'll come from a datacenter too. Allowlist it, but prefer a shared secret or a scoped API key over an IP allowlist, since IPs change and secrets don't.

Mind the cost. Each lookup is 2 credits, so a burst from one attacker shouldn't cost you 2 credits times a thousand attempts. That's what the per-IP cache is for. Rate-limiting at the edge by ASN, in Cloudflare or your WAF, is an even cheaper first layer before the API call ever happens.

Mobile and CGNAT are not a problem here, residential proxies are. Carrier-grade NAT and mobile ranges don't read as cloud, so the gate won't misfire on phone users. The genuinely hard case is residential proxies, which look residential on purpose. That's exactly why this gate is narrow: it catches servers, and you handle residential-proxy abuse through threat_score and is_residential_proxy, not through the cloud flag.

A few things worth adding

If you want a softer version, drive it off threat_score instead of a hard block: add friction in the 45 to 79 band, block at 80 and up, and let the cloud flag push borderline cases over the line. IPv6 works identically, the flag set is the same. And the cheapest win of all is to log every cloud_provider_name you're about to block for a week before you actually turn blocking on.

Drop the classifier into your signup route, keep the anonymized-traffic decision on its own softer track, and you'll stop the datacenter bots without a queue of real users asking why they can't register. That week of logging first is worth it: you'll find your own CI, a partner's integration, and that one big customer on Zscaler before any of them becomes a support ticket.

Is Anyone Actually Reading Your Abuse Reports?

ABDULLAH AFZAL — Fri, 04 Sep 2026 11:18:01 +0000

Somewhere on a hosting provider's /24, a scanner is working through port 22. It fails on one address, moves to the next in the block, fails again, and keeps walking. Every server it touches that has fail2ban configured with an automated reporting action fires off an abuse report. By evening, the operator's abuse desk holds a few hundred near-identical emails about the same box, each a slightly reworded "SSH brute force from your network."

Nobody reads them. Not because the abuse team is lazy, but because there's nothing left to read. Three hundred reports of one event carry about as much information as one report, and take three hundred times longer to get through.

Automated reporting didn't make that IP more likely to get actioned. It made every report about it less likely to.

That's the whole argument. Reporting abuse is worth doing. The way most of us do it now, on autopilot and at volume, is quietly making it worse.

Reporting got free, and free things get flooded

It used to take effort to report an abusive IP. You noticed the pattern in your logs, found the network's abuse contact, wrote the email, attached the evidence, and sent it. That friction was doing more work than anyone gave it credit for. It meant the reports that went out were the ones a person had decided were worth sending.

Then reporting became a line of config.

# Illustrative: add Fail2Ban's built-in complaint action to the normal ban action.
# This also requires its documented dependencies and a working mail setup.
action = %(known/action)s
         complain[logpath="%(sshd_log)s"]

fail2ban, CrowdSec, honeypots, and mail feedback loops all turned "report this" into a background job that runs thousands of times a day with no human in the loop. High-volume automated reporting became easy. The amount of signal in each report did not necessarily improve.

This is the pattern behind every system that gets cheaper to use faster than it gets smarter. When the marginal cost of sending drops to zero, quantity stops tracking importance. Email spam works this way. So does the notification tray on your phone. Abuse reporting is now in the same bucket, and we got here with good intentions and a cron job.

Volume is not the same as signal

Here's the part that's easy to miss when your dashboard shows a satisfying count of reports sent. The receiving end is either a human with a finite number of hours, or an automated reputation system that's only as good as what you feed it. Both get worse under a firehose.

Think about what a lazy automated report actually contains. An IP. A timestamp in whatever timezone the reporting server happens to run in. A one-line reason like "brute force," and often no evidence at all. Sometimes it contains the reporter's own IP or email, pasted into a comment field by accident. Multiply that by every install reporting the same scanner, and the operator isn't reading intelligence. They're reading log exhaust.

You don't have to take my word for it. Look at what one of the best-known abuse-reporting databases had to build to cope. AbuseIPDB asks you to report a continuing attacker roughly once per day, not once per attempt. The same account cannot report the same IP more than once every 15 minutes, and if the same IP is reported again within 24 hours with the same comment, AbuseIPDB updates the original report's timestamp instead of creating another one. It tells reporters to limit comments to the key information about the abuse and warns against putting personal information into those comments. Its API also enforces rate limits with 429 Too Many Requests.

Those rules aren't decoration. They're scar tissue. Each one exists because undisciplined reporting was degrading the database, and the fix was to make reporters slow down and clean up. When the platform built to absorb abuse reports has to defend itself against abuse reports, the practice has a quality problem, not a volume shortage.

The people doing the reporting suspect it too. Search the sysadmin forums and the same question keeps turning up: is there any point to reporting an abusive IP at all? That doesn't come from people who don't care. It comes from people who've been firing reports into a void and noticed nothing changed.

The strongest case against me

There's a real argument on the other side, and it deserves a fair hearing.

More data beats less data. A reputation system that sees one IP reported by five hundred independent networks has stronger evidence than one that sees it once, even if most of those reports are sloppy. Deduplication and scoring exist precisely to turn noisy inputs into a usable signal, and they mostly work. Reporting, even imperfect reporting, raises the cost of running an attack, because a burned IP is a burned IP. Blocklists built from exactly this kind of crowdsourced volume do block a great deal of bad traffic.

All of that is true, and none of it rescues the specific failures. Dedup collapses the count, but it can't reconstruct evidence a report never carried. Scoring is only as good as its inputs, and a flood of context-free reports drags the average toward noise: a confidence number built on five hundred reports that all say "brute force" with no detail is a number about popularity, not about what the IP did. And the thing volume genuinely can't fix is the human desk. An operator who could have suspended a customer off one clear, actionable report instead closes the ticket, because the one good report is buried under three hundred that say nothing.

So the counter-argument mostly holds for the reputation databases and falls apart for the operators who can actually stop the abuser. That split is the point.

Report less, report better

The fix isn't to stop reporting. It's to treat a report as a message to a stranger who's short on time, and act like it.

Throttle. Report a continuing attacker once per source per day, not once per packet. Whatever your tool fires on, put a window in front of it.

Deduplicate by incident and abuse destination, not blindly by individual IP. If several addresses in the same network are performing the same behavior in the same time window and resolve to the same abuse desk, combine them into one report with the relevant IPs and evidence. Don't automatically collapse an entire routed prefix into one incident, though: the same network can contain different customers and unrelated abusive hosts.

Make it actionable in ten seconds. The offending IP, a UTC timestamp, what it did, the destination or affected system when that helps identify the event, and a few lines of real log. That's the core of the report. Leave out the opinions, threats, and unrelated personal information. If you're posting to a public reputation database, strip your own IP, email, and other PII from comments unless the service explicitly requires it. One report a human can act on immediately beats a hundred they have to decode.

Send it to the operator, not the void. The contact you want is the network operator responsible for the IP, not the registry and not the abuser. ABUSE has been a standardized network-operations mailbox name since RFC 2142 in 1997, although the actual abuse address for an IP may be a different contact registered with the relevant RIR. Resolving it yourself means using registry-aware WHOIS or RDAP data and handling the differences between registries. Or you can skip that plumbing: a single abuse-contact lookup returns the responsible abuse contact and network information directly.

Escalate only when it's earned. If the operator ignores a clean report, an upstream provider, hosting reseller, or relevant blocklist may be a reasonable next move depending on the incident. If the registered abuse contact itself is missing or invalid, raise that contact-data problem with the relevant RIR. Don't treat the RIR as an escalation desk simply because a valid abuse contact chose not to respond. Leading with the blocklist because it's the easiest button is how the noise started.

None of this is hard. It's just less than what your tooling does by default, and that's exactly the point.

What you're actually spending

The internet's abuse handling runs on two things you spend every time you hit send: a volunteer's attention, and the shared reputation data everyone downstream depends on. Both are finite, and a lazy report spends them for nothing. If you're going to automate reporting, and you should, automate the throttling and the formatting and the routing along with it. Otherwise you're not fighting the spam. You're just more of it.

How Do I Route EU Users Data to an EU Region?

ABDULLAH AFZAL — Tue, 01 Sep 2026 12:27:38 +0000

GDPR-aware regional routing is two problems, not one: estimating where a request comes from, and deciding which data region your architecture or residency policy should use. An IP address helps with the first. GDPR does not impose a blanket rule that EU users' data must stay inside the EU, but it does regulate transfers of personal data to third countries.

Most write-ups pick a side. The code-first ones show you a country lookup and stop, with no mention of what the lookup is legally worth. The compliance-first ones explain the regulation and never show you a single line of routing. This is the piece in the middle: working detection and routing, plus an honest map of where IP geolocation stops being an answer.

TL;DR

Detect with an IP geolocation lookup. country_code2 and an is_eu boolean are enough to make the routing decision.
is_eu covers the EU-27, while this residency policy covers the full EEA-30. Add Norway, Iceland, and Liechtenstein explicitly so EEA-detected requests follow the same regional rule.
Route with edge middleware: read the client IP correctly (trust-proxy matters), map country to a data region, and store or process there.
Fail toward the EEA region, not away from it. If your residency policy keeps EEA-detected requests in the EEA, routing an unknown request there is the safer default and avoids an accidental policy violation.
IP is a signal, not a lawful basis. VPNs, proxies, and mobile carriers break it, GDPR scope does not turn on IP, and an IP address is itself personal data. If you want the short version: use the geolocation lookup to route, treat is_eu as a convenience rather than a compliance boundary, widen it to the EEA, and log every routing decision so you can defend it later. The rest of this walks through each step with code and the reasoning behind it.

What data-residency routing actually is

Data residency is a constraint on where data physically sits. Data-residency routing is the mechanism that honors whatever residency policy your product, customer contract, sector, or risk model requires. GDPR itself does not generally require personal data about EU or EEA users to be stored inside the EEA. Keeping relevant storage and processing inside the EEA can, however, simplify compliance by reducing the number of international transfers you need to account for.

Two adjacent ideas get tangled with it, and separating them keeps the design honest.

Data residency is not data sovereignty. Residency is the physical location of the bytes. Sovereignty is about which government's laws and courts have jurisdiction over that data, which can differ from where it is stored (a US-headquartered provider storing data in Frankfurt is a common sovereignty question). Routing solves residency directly. It only mitigates sovereignty.

Routing is not the same as IP minimization. Google Analytics, for instance, drops EU IP addresses before logging rather than routing anything. That is a valid pattern for one field. It is not a substitute for deciding where a user's account, orders, or messages live. Different problem, different tool.

The decision that determines where the data goes

Before any code, define what your routing policy actually means. If your policy is "keep requests detected in the EEA in an EEA region," is_eu alone is too narrow.

is_eu covers the 27 EU member states. The EEA also includes Iceland, Liechtenstein, and Norway, where the GDPR has been incorporated into the EEA framework. Those three are not EU members, so is_eu returns false for them. Add them explicitly when implementing an EEA-based residency policy.

This EEA routing boundary should not be confused with GDPR's territorial scope. Whether GDPR applies to a processing activity depends on Article 3 factors such as establishment, offering goods or services, and monitoring behavior, not simply on the user's detected country.

Set	Members	`is_eu` returns	Route under this EEA-residency policy?
EU-27	Austria, Germany, France, ... 24 more	`true`	Yes
EEA extras	Iceland (IS), Liechtenstein (LI), Norway (NO)	`false`	Yes
Everywhere else	US, IN, BR, ...	`false`	No, unless your residency policy says otherwise

Adequacy is a separate decision from IP-based routing. It concerns where personal data is being transferred, not where the user happens to be located.

If personal data is transferred from the EEA to a country, territory, sector, or organisation covered by a European Commission adequacy decision, that transfer can take place without an additional Chapter V safeguard. The Commission maintains the list and it changes, so treat it as current legal configuration rather than a hardcoded user-country list. Current examples include the United Kingdom, Switzerland, Japan, Republic of Korea, Brazil, New Zealand, Canada for covered commercial organisations, and participating US organisations under the EU-US Data Privacy Framework.

Data path	GDPR transfer position	Practical implication
Relevant processing remains within the EEA	No third-country transfer under Chapter V	Use an EEA region when that matches your residency policy
Transfer from the EEA to an adequate destination	Article 45 adequacy decision	No additional Chapter V transfer safeguard is required for the covered transfer
Transfer from the EEA to another third country	Chapter V mechanism required, unless an applicable exception applies	Assess SCCs or another valid transfer mechanism separately from IP routing

The nuance worth internalizing: keeping relevant storage, processing, and access inside the EEA can reduce international-transfer complexity. But an EEA database region does not by itself eliminate Chapter V questions if the data is remotely accessed, processed, supported, or onward-transferred from outside the EEA. Adequacy decisions and safeguards such as Standard Contractual Clauses address transfers when data does leave the EEA.

Detecting an EEA location by IP

The detection step is one HTTP call. Any IP geolocation provider returns the two fields that matter here: an ISO 3166-1 alpha-2 country code and, if the provider exposes one, an EU membership flag. ip-api, ipinfo, MaxMind GeoIP2, DB-IP, and IPGeolocation all return roughly the same country payload; pick by latency, pricing model (per-call API vs a local database), or what is already in your stack.

I'll use ipgeolocation.io for the examples because its free tier returns country_code2 and an is_eu boolean in a single call, which keeps the routing logic short. You can create a key on the free tier at ipgeolocation.io.

A quick look at the two fields with curl:

# Keep the key in the environment. Never commit it inside a URL.
export IPGEO_API_KEY="your_key_here"

# --max-time caps the whole request; a slow lookup should never block your request path.
curl -s --max-time 2 \
  "https://api.ipgeolocation.io/v3/ipgeo?apiKey=${IPGEO_API_KEY}&ip=8.8.8.8" \
  | jq '{country_code2: .location.country_code2, is_eu: .location.is_eu}'

For 8.8.8.8 (a US address) that returns country_code2: "US" and is_eu: false. The full response carries more than the routing decision needs, and it is worth seeing the shape once so you know what else is there:

{
  "ip": "8.8.8.8",
  "location": {
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "city": "Mountain View",
    "zipcode": "94043",
    "latitude": "37.42240",
    "longitude": "-122.08421",
    "is_eu": false,
    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
    "geoname_id": "5375480"
  },
  "country_metadata": {
    "calling_code": "+1",
    "tld": ".us",
    "languages": ["en-US", "es-US", "fr"]
  },
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" }
}

For an EU member the same call returns the member's code ("DE", "FR", and so on) with is_eu: true. For an EEA-but-not-EU country like Norway, country_code2 is "NO" and is_eu is false, which is exactly why the routing code below checks both the flag and a short EEA list.

Heads up: is_eu is a convenience, not a compliance boundary. It answers "is this one of the 27 EU states," not "is this user in GDPR scope." The code widens it deliberately.

Routing the request to an EEA region

Now the mechanism. The pattern that scales is to decide the region once, as early in the request path as possible, and carry that decision downstream to whichever store or queue the data lands in.

Two things break this in practice if you skip them, so they are in the code rather than a footnote. First, reading the client IP correctly behind a proxy or load balancer. Second, deciding what happens when the lookup fails.

Here is Express middleware that resolves an IP to a target region:

// npm i express
const express = require("express");
const app = express();

// If you run behind a proxy/LB/CDN, configure Express to trust only the
// proxy path you actually control. req.ip is then derived from the socket
// address and X-Forwarded-For using that trust configuration.
//
// A numeric hop count is appropriate only when every request reaches the app
// through the same number of trusted hops. In production, trusting explicit
// proxy IPs or CIDRs is safer when your topology allows it.
app.set("trust proxy", 1); // illustrative: exactly one trusted proxy hop

// This residency policy covers the EEA: EU-27 (is_eu) plus these three.
const EEA_EXTRA = new Set(["IS", "LI", "NO"]);

// Country -> data region. Illustrative AWS names; swap for your provider.
// This is a residency-policy decision, separate from any Chapter V
// analysis of transfers to third countries.
const REGION_BY_GROUP = {
  eea: "eu-central-1", // Frankfurt: keep EU/EEA data in the EU
  other: "us-east-1",
};

async function resolveRegion(ip) {
  const key = process.env.IPGEO_API_KEY;
  const url = `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${key}&ip=${ip}`;

  try {
    // 1.5s ceiling: a geolocation lookup must never hold the request open.
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) throw new Error(`lookup failed: ${res.status}`);

    const data = await res.json();
    const cc = data?.location?.country_code2 ?? null;
    const isEu = data?.location?.is_eu ?? false;

    // Missing country means the location is unknown, so use the protective default.
    if (!cc) return REGION_BY_GROUP.eea;

    if (isEu || EEA_EXTRA.has(cc)) return REGION_BY_GROUP.eea;
    return REGION_BY_GROUP.other;
  } catch (err) {
    // Fail toward the protective region. Under this residency policy,
    // an unknown location is treated as EEA rather than risking a mis-route.
    console.error(`region lookup error for ${ip}: ${err.message}`);
    return REGION_BY_GROUP.eea;
  }
}

app.use(async (req, _res, next) => {
  req.dataRegion = await resolveRegion(req.ip);
  next();
});

req.dataRegion is now set for every request, and downstream handlers pick the database, bucket, or queue for that region. The two decisions that make it production-safe are the trust proxy setting (so req.ip is the client, not your load balancer) and the catch block that fails toward the EEA region rather than away from it.

The same logic in Python, as a FastAPI dependency:

# pip install fastapi httpx
import os
import httpx
from fastapi import Depends, Request

EEA_EXTRA = {"IS", "LI", "NO"}  # EEA minus the EU-27 that is_eu covers
REGION_BY_GROUP = {"eea": "eu-central-1", "other": "us-east-1"}

async def resolve_region(request: Request) -> str:
    # Behind a proxy, configure your server (e.g. uvicorn --forwarded-allow-ips)
    # so request.client.host is the real client, not the proxy.
    ip = request.client.host if request.client else ""
    key = os.environ.get("IPGEO_API_KEY")
    url = f"https://api.ipgeolocation.io/v3/ipgeo?apiKey={key}&ip={ip}"

    try:
        # (connect, read) timeouts keep a slow lookup off the request path.
        async with httpx.AsyncClient(timeout=httpx.Timeout(1.5, connect=1.0)) as client:
            resp = await client.get(url)
            resp.raise_for_status()
            loc = resp.json().get("location", {})
            cc = loc.get("country_code2")
            is_eu = loc.get("is_eu", False)

            # Missing country means the location is unknown, so use the protective default.
            if not cc:
                return REGION_BY_GROUP["eea"]

            if is_eu or cc in EEA_EXTRA:
                return REGION_BY_GROUP["eea"]
            return REGION_BY_GROUP["other"]
    except Exception as err:
        # Unknown location routes to the EEA region under this protective residency policy.
        print(f"region lookup error for {ip}: {err}")
        return REGION_BY_GROUP["eea"]

# Usage: def handler(region: str = Depends(resolve_region)): ...

Both versions make the same call: check is_eu, widen it with the EEA set, and fall to the EEA region on failure.

Country to region, as a table

The dictionary in the code is the compact version of this decision. Spelled out:

Detected group	Example codes	Route under this residency policy
EU-27 (`is_eu: true`)	DE, FR, ES, IT, PL	EEA region (e.g. `eu-central-1`)
EEA extras	IS, LI, NO	EEA region
Non-EEA	US, GB, JP, BR, IN	Default or configured region
Lookup failed	n/a	EEA region (protective default)

Fail open or fail closed

This is the decision people skip, and for residency it is the one with legal weight. Fail open (route an unknown location to the default region) optimizes for availability and cost. A protective default (route it to the EEA region) is useful when your own residency policy requires EEA-detected traffic to remain there. For that policy, I fail toward the EEA region: occasionally routing a non-EEA request to Frankfurt costs some latency, while routing an EEA request to the wrong region violates the policy the router was built to enforce.

Where IP geolocation stops being enough

Everything above is a routing heuristic. It is genuinely useful and it is not a compliance determination, and conflating the two is how teams get surprised in an audit. Three boundaries matter.

IP location is a signal, not a lawful basis. GDPR's territorial scope does not turn on a user's IP. It applies to processing by an establishment in the EU, and to offering goods or services to, or monitoring, people in the EU, regardless of where the processing happens (GDPR Article 3). A US company with EU customers can be fully in scope even if it never runs an IP lookup. Use geolocation to route data efficiently; do not use it to decide whether the regulation applies to you. The EDPB territorial-scope guidelines are the reference if you need to reason about that line carefully.

VPNs, proxies, and mobile carriers break the signal. A user in Berlin on a corporate VPN that egresses in Virginia looks American. A traveler in the EU on a mobile network can geolocate to the carrier's registered country rather than their cell. Country-level accuracy is high on ordinary residential and business IPs and drops on VPN egress, datacenter ranges, and some mobile carrier blocks. If a mis-route has consequences, corroborate the IP signal with account data (a billing country, a stored preference, an explicit region choice) instead of trusting it alone. Providers that flag VPN, proxy, and hosting IPs let you at least detect when the signal is shaky.

An IP address is personal data. In the context of a service handling identifiable users, you should generally treat client IP addresses as personal data when they can reasonably be linked to a person. In Breyer v Germany (C-582/14), the Court of Justice held that a dynamic IP address can constitute personal data for a website operator where the operator has legal means reasonably available to identify the user with additional information. Practical consequence: the lookup you run to decide residency may itself involve processing personal data. If you send that IP to an external geolocation provider, also account for where that provider processes it and whether the lookup creates a third-country transfer. Keep the lookup purposeful, review the provider's processing arrangement, avoid storing raw IPs longer than you need, and pseudonymize where appropriate.

IP geolocation can establish	IP geolocation cannot establish
A probable country for routing	Legal residence or citizenship
A rough EU/EEA vs non-EU split	Whether GDPR applies to your processing
A fast first-pass region decision	A lawful basis or valid consent
A hint that a connection is anonymized	Where a user actually is, when they use a VPN

Where transfers out of the EEA are genuinely necessary, the mechanisms are adequacy decisions and Chapter V safeguards such as Standard Contractual Clauses, documented on the Commission's pages for adequacy and international transfers. Keeping the relevant data and access paths within the EEA can avoid a third-country transfer. An EEA storage region alone is not sufficient if processing or access still occurs from outside the EEA.

A reference checklist

Keep this next to the implementation:

Route on the EEA-30, not just is_eu (EU-27). Add IS, LI, NO.
Read the client IP through your proxy configuration, not a raw header.
Set a hard timeout on the lookup (1 to 2 seconds) so it never blocks the request path.
Fail toward the EEA region when the lookup is unavailable or ambiguous.
Treat the adequacy list as a lookup, not a hardcoded constant; the Commission updates it.
Log the routing decision (IP-derived country, chosen region, timestamp) so you can defend it.
Corroborate with account data when a mis-route has real consequences.
Remember the lookup itself processes personal data; minimize and pseudonymize. ## A few extra notes

Doing the lookup at the CDN edge and passing a trusted country header to your app beats calling an API on every request. Cloudflare, Fastly, and AWS CloudFront can attach a country code at the edge; your app then reads a header you control instead of paying a network round trip per request. If you are calling a geolocation API synchronously on every request with no cache, that is the first thing I would change. Cache exact-IP results with a short TTL, or preferably move the lookup to a trusted edge layer that already provides the country signal. For policy-sensitive routing, avoid broadening one IP's result across an entire /24.

IPv6 needs the same treatment as IPv4. If your service is dual-stack, make sure the lookup path handles a v6 client address, and test it, because v6 country accuracy on some ranges lags v4.

The UK is worth a specific note. Since Brexit it is a third country, but the European Commission renewed its GDPR adequacy decision in December 2025. That means personal data can currently be transferred from the EEA to the UK under Article 45 without an additional Chapter V safeguard. This is about the transfer destination, not about whether a UK user's data must be stored in any particular region. UK GDPR may separately apply to your processing.

Within the routing condition itself, EEA_EXTRA is the only jurisdiction list you hardcode. Keep IS, LI, and NO in one named constant rather than scattering them across handlers. Treat adequacy decisions, transfer mechanisms, proxy configuration, and your own residency policy as separate configuration that may also change over time.

Where to take it next

Drop the middleware into your request path, point the region map at your actual providers, and add the routing decision to your logs before you ship it. If you only harden one thing afterward, move the lookup to the edge with a cache so you are not paying for it per request. And keep the distinction in view: this routes data correctly, it does not decide whether GDPR applies to you. That question was answered long before the IP lookup ran.

A Self-Correcting Solar System Baseline From Sunrise/Sunset Data

ABDULLAH AFZAL — Thu, 27 Aug 2026 09:36:23 +0000

A fixed-schedule solar baseline drifts out of sync with the sun throughout the year. In Phoenix the sun is up for 13 hours 10 minutes in late August and 10 hours 2 minutes at the December solstice. A flat daily kWh target flags that entire winter as a fault, then stays quiet on the July afternoon when one string dies at 2pm under full sun. The fix is to anchor the baseline to the actual sun instead of the clock, and most of what you need for that does not require an irradiance forecast.

One thing before any code: sun geometry tells you when a system should be producing and when it should peak. It does not tell you how much light actually reached the panels. That is irradiance, and cloud cover swamps it. If you want modeled output in kWh, reach for Forecast.Solar or Solcast, which fold in weather and your array's tilt and azimuth. What follows is the free, dependency-light layer underneath that: the daylight window, the solar-noon peak, and the day-length trend.

TL;DR

Sun geometry (sunrise, sunset, solar noon, day length) catches a specific class of solar underperformance with no irradiance data.

Gate alerts to the real daylight window so your monitor stops crying "underperformance" before sunrise.

Track the daily production peak relative to solar noon. A persistent shift across comparable days can reveal shading, orientation, or system changes that a total-kWh check misses.

Normalize a flat kWh target by day length so winter stops tripping false alarms. First-order fix, not a physics model.

One call to an astronomy endpoint returns all of it. Code below in curl, Python, and Node.

For real production forecasting, use an irradiance API. Sun times are the sanity layer, not the forecaster.

Sun times will not predict your kWh, but they eliminate common timing-based false alarms and can surface useful production-shape anomalies early. Pull sunrise, sunset, solar noon, and day length once a day, gate your alerts to daylight, watch the peak, and scale the target for season.

What sun times can and cannot tell you

Sun geometry gives you three usable things: the window a system can physically produce in, the moment it should peak, and how that window changes through the year. All three come from a plain lat/long lookup and none of them costs you a weather subscription.

What they leave out is the part that actually varies day to day. A clear July noon and an overcast one have the same solar noon and nearly the same day length, but wildly different output. So sun times are a denominator, not a measurement. Treat a gap between expected window and actual production as a question, not a verdict, and reserve the confident "this panel is broken" call for the cases geometry can isolate on its own.

Plenty of tools return sun times: Sunrise-Sunset.org is free with no signup, SunCalc computes positions in the browser without an API at all, and NOAA has a solar calculator. I am using ipgeolocation.io's Astronomy API here because one call returns the window, solar noon, day length, twilight, and the sun's position together, which keeps the code short. Pick whatever you already have in your stack.

The three checks worth building

None of these needs irradiance. Each one closes a real gap in the naive "compare today's kWh to a fixed number" monitor.

Gate alerts to the real daylight window

The cheapest win is to stop evaluating production when the sun is not up. A monitor that compares output to a target every fifteen minutes will happily fire a "low production" alert at 06:00 in December, when sunrise is at 07:25 and the correct output is zero. Gate every underperformance rule behind the sunrise-to-sunset window and that class of alert disappears.

Trim the edges with a margin. Output in the first and last half hour of daylight is near zero because the sun is barely above the horizon, so a low-production alert there is just physics, not a fault. A 30-minute margin inside sunrise and sunset is a reasonable start; widen it for a site with a hard eastern or western horizon. The one edge case to handle is high latitude in midsummer or midwinter, where the API can report the sun as up or down all day; check sun_status before trusting the window there.

Watch the peak drift off solar noon

This is the check that earns its keep. Total daily kWh can look fine while a single string slowly fails, because the healthy strings mask the loss in the daily sum. The shape of the day gives it away sooner.

When the daily peak persistently shifts away from its normal offset, or the curve repeatedly becomes lopsided under comparable conditions, it can point to partial shading, uneven soiling, orientation effects, or inverter behavior. A single cloudy day's peak is weak evidence, so look for the change across multiple days rather than treating one maximum as a fault.

Orientation is the easy thing to get wrong here. A west-facing array peaks after solar noon by design and an east-facing one before it, so the threshold is relative to where your array should peak, not a universal number. Compare today's peak time to solar noon, keep a rolling few weeks of the offset, and alert on the change rather than the absolute value.

Normalize the baseline by day length

A flat kWh target assumes every day has the same amount of daylight, which is why it flags winter. Scaling the target by today's day length against a summer reference removes most of that error in about three lines. A 40 kWh midsummer target becomes roughly 29 kWh at the December solstice (10 hours 2 minutes of daylight against a 14-hour reference); the flat 40 kWh number would have marked a perfectly healthy winter day about 27% low.

Be honest about what this does not fix. Winter days are not just shorter, the sun is also lower, so each daylight hour delivers less energy and real output drops more than the day-length ratio predicts. Day-length scaling gets you from "wildly wrong" to "roughly right," which is enough to stop the seasonal false alarms. Closing the rest of the gap means modeling irradiance and sun elevation, which is exactly the job Forecast.Solar, Solcast, and the pvlib library exist to do.

Pull the sun data

The endpoint is a single GET. The free tier is 1,000 requests a day with no credit card, and one request covers a full day, so a per-site daily pull sits comfortably inside it. Sign up for a key on the Astronomy API and keep it out of source control.

# Free tier: 1000 requests/day, no card. One call returns the whole day's geometry.
# 2s timeout so a slow response can't hang a monitor loop.
curl -sS --max-time 2 \
  "https://api.ipgeolocation.io/v3/astronomy?apiKey=$IPGEO_API_KEY&lat=33.4484&long=-112.0740&date=2026-08-25&time_zone=America/Phoenix"

The response carries far more than the four fields we use. That is the point of one call:

{
  "location": {
    "latitude": "33.44840",
    "longitude": "-112.07400",
    "city": "Phoenix",
    "state_prov": "Arizona",
    "elevation": "331"
  },
  "astronomy": {
    "date": "2026-08-25",
    "current_time": "05:46:58.255",
    "sunrise": "2026-08-25 05:54",
    "sunset": "2026-08-25 19:05",
    "solar_noon": "2026-08-25 12:30",
    "day_length": "13:10",
    "sun_altitude": -3.03,
    "sun_azimuth": 75.14,
    "sun_distance": 151249918.79,
    "sun_status": "-",
    "morning": {
      "civil_twilight_begin": "2026-08-25 05:32",
      "civil_twilight_end": "2026-08-25 05:54",
      "golden_hour_begin": "2026-08-25 05:42",
      "golden_hour_end": "2026-08-25 06:31"
    },
    "evening": {
      "golden_hour_begin": "2026-08-25 18:29",
      "golden_hour_end": "2026-08-25 19:18",
      "civil_twilight_begin": "2026-08-25 19:05",
      "civil_twilight_end": "2026-08-25 19:28"
    },
    "moon_phase": "WAXING_GIBBOUS",
    "moonrise": "2026-08-25 17:48",
    "moonset": "2026-08-25 03:26",
    "moon_illumination_percentage": "93.10"
  }
}

Two things to notice before you write parsers. day_length is a string, "13:10", meaning 13 hours 10 minutes, not a decimal. And because the request set time_zone, the times come back as "YYYY-MM-DD HH:mm" in that zone rather than bare clock times. Both matter for the code. One more, in case it trips you up: sun_altitude and sun_azimuth are the sun's position at current_time, which is when the call ran, not at noon. In this capture that was just before sunrise, hence the negative altitude. The checker below ignores those fields, but they are useful for a live "is the sun even up right now" readout.

Pitfall: timestamps are returned in the time_zone you request. The curl example above asks for Phoenix local time, while the checker below deliberately requests UTC so the timestamps can be parsed unambiguously. Keep now timezone-aware and compare absolute times consistently. The date you request should still be the calendar date at the solar site.

Build the baseline checker

Fetch once per day, then run all three checks against that one response. Calling the API per check wastes credits and adds latency for data that does not change within a day. A small cron job at local midnight that caches the day's response is enough; there is no reason to hit the endpoint again until the date rolls over.

import os
import sys
from datetime import datetime, timedelta, timezone

import requests

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")
ASTRONOMY_URL = "https://api.ipgeolocation.io/v3/astronomy"


def fetch_sun_day(lat, lon, date_str):
    """One day of sun geometry. Costs one credit, so call it once per day and
    reuse the result for every check instead of hitting the API per rule."""
    if not IPGEO_API_KEY:
        raise RuntimeError("Set IPGEO_API_KEY in the environment")
    params = {
        "apiKey": IPGEO_API_KEY,
        "lat": lat,
        "long": lon,
        "date": date_str,
        # Request UTC so returned timestamps are unambiguous when parsed.
        "time_zone": "UTC",
    }
    try:
        # (connect, read) timeouts so a slow upstream can't stall the monitor loop
        resp = requests.get(ASTRONOMY_URL, params=params, timeout=(1.0, 1.5))
        resp.raise_for_status()
    except requests.RequestException as err:
        # Fail open: this is a sanity layer, not a safety system. If it's down,
        # skip the geometry checks rather than block the rest of monitoring.
        print(f"sun lookup failed, skipping geometry checks: {err}", file=sys.stderr)
        return None
    return (resp.json() or {}).get("astronomy")


def hhmm_to_minutes(value):
    """day_length arrives as a string like '10:02' (hours:minutes), not decimal."""
    if not value or ":" not in value:
        return None
    hours, minutes = value.split(":")[:2]
    return int(hours) * 60 + int(minutes)


def parse_dt(value):
    """Parse the API's UTC 'YYYY-MM-DD HH:mm' timestamps as aware datetimes."""
    if not value:
        return None
    try:
        return datetime.strptime(
            value, "%Y-%m-%d %H:%M"
        ).replace(tzinfo=timezone.utc)
    except ValueError:
        return None

Those three helpers absorb the two gotchas: the string day length and the dated timestamps. Everything below returns cleanly on missing fields so a partial response never throws.

def in_daylight(now, astro, margin_minutes=30):
    """True only inside the productive window. The margin trims dawn and dusk."""
    status = astro.get("sun_status")

    if status == "Always above the twilight angle":
        return True
    if status == "Always below the twilight angle":
        return False

    sunrise = parse_dt(astro.get("sunrise"))
    sunset = parse_dt(astro.get("sunset"))

    if not sunrise or not sunset:
        return True  # unknown, so don't suppress a potentially real alert

    if now.tzinfo is None:
        raise ValueError("now must be timezone-aware")

    now_utc = now.astimezone(timezone.utc)
    start = sunrise + timedelta(minutes=margin_minutes)
    end = sunset - timedelta(minutes=margin_minutes)

    return start <= now_utc <= end


def peak_drift_minutes(observed_peak, astro):
    """How far the day's production peak sat from solar noon, in minutes.
    observed_peak must be a timezone-aware datetime."""
    solar_noon = parse_dt(astro.get("solar_noon"))
    if not solar_noon or not observed_peak:
        return None

    if observed_peak.tzinfo is None:
        raise ValueError("observed_peak must be timezone-aware")

    observed_peak_utc = observed_peak.astimezone(timezone.utc)
    return abs((observed_peak_utc - solar_noon).total_seconds()) / 60.0


def seasonal_target(base_kwh, astro, reference_day_length="14:00"):
    """Scale a flat kWh target by today's day length against a summer reference.
    Removes the gross seasonal error. It under-corrects, because winter also has a
    lower sun (less energy per daylight hour); closing that gap needs irradiance."""
    today = hhmm_to_minutes(astro.get("day_length"))
    reference = hhmm_to_minutes(reference_day_length)

    if today is None or reference is None or reference == 0:
        return base_kwh

    return round(base_kwh * (today / reference), 1)

Use the daylight gate around real-time production alerts, but run the peak-drift and daily-kWh checks only after the day's production window is complete. A full-day kWh target should never be compared with energy accumulated halfway through the day. The tolerance band below is still only a rough weather buffer, not a substitute for irradiance data.

def evaluate_completed_day(
    observed_peak,
    actual_kwh,
    base_kwh,
    lat,
    lon,
    date_str,
):
    """Run after the day's production window has finished."""
    astro = fetch_sun_day(lat, lon, date_str)
    if astro is None:
        return

    drift = peak_drift_minutes(observed_peak, astro)
    if drift is not None and drift > 90:
        print(
            f"peak offset was {drift:.0f} min from solar noon; "
            "track whether that shift persists across comparable days"
        )

    expected = seasonal_target(base_kwh, astro)

    if actual_kwh < expected * 0.75:
        print(
            f"actual {actual_kwh} kWh below seasonal expectation "
            f"{expected} kWh"
        )

The Node version is the same shape. fetch with a hard timeout, optional chaining on the response, and the identical string-and-timestamp parsing. It assumes Node 18 or newer, where fetch and AbortSignal.timeout are built in; on older runtimes add node-fetch and an abort polyfill.

const ASTRONOMY_URL = "https://api.ipgeolocation.io/v3/astronomy";

async function fetchSunDay(lat, lon, dateStr) {
  const key = process.env.IPGEO_API_KEY;
  if (!key) throw new Error("Set IPGEO_API_KEY in the environment");

  // dateStr should be the calendar date at the solar site.
  // Request event timestamps in UTC so Date parsing is unambiguous.
  const url = `${ASTRONOMY_URL}?apiKey=${key}&lat=${lat}&long=${lon}`
    + `&date=${dateStr}&time_zone=UTC`;
  try {
    // 1.5s timeout so a slow upstream can't stall the monitor loop
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();
    return body?.astronomy ?? null;
  } catch (err) {
    // Fail open: sanity layer, not a safety system
    console.error(`sun lookup failed, skipping geometry checks: ${err.message}`);
    return null;
  }
}

// day_length is a string like "10:02" (h:mm), not a number
function hhmmToMinutes(value) {
  if (!value || !value.includes(":")) return null;
  const [h, m] = value.split(":");
  return Number(h) * 60 + Number(m);
}

// We request UTC from the API, so the timestamp can be parsed unambiguously.
function parseDt(value) {
  if (!value || value === "-:-") return null;
  const d = new Date(`${value.replace(" ", "T")}:00Z`);
  return Number.isNaN(d.getTime()) ? null : d;
}

function inDaylight(now, astro, marginMin = 30) {
  if (astro?.sun_status === "Always above the twilight angle") return true;
  if (astro?.sun_status === "Always below the twilight angle") return false;

  const sunrise = parseDt(astro?.sunrise);
  const sunset = parseDt(astro?.sunset);

  if (!sunrise || !sunset) return true; // unknown, don't suppress a real alert

  const start = new Date(sunrise.getTime() + marginMin * 60000);
  const end = new Date(sunset.getTime() - marginMin * 60000);

  return now >= start && now <= end;
}

function seasonalTarget(baseKwh, astro, referenceDayLength = "14:00") {
  const today = hhmmToMinutes(astro?.day_length);
  const reference = hhmmToMinutes(referenceDayLength);
  if (today === null || reference === null || reference === 0) return baseKwh;
  return Math.round(baseKwh * (today / reference) * 10) / 10;
}

Peak drift is the same idea on parsed values:

function peakDriftMinutes(observedPeak, astro) {
  const solarNoon = parseDt(astro?.solar_noon);
  if (!solarNoon || !observedPeak) return null;
  return Math.abs(observedPeak.getTime() - solarNoon.getTime()) / 60000;
}

Flag it against your array's orientation, same caveat as before: a west-facing array measures drift from its own expected offset, not from solar noon.

Where this stops and irradiance begins

Run the checker against a week of clear days and it behaves. Run it against a stretch of overcast ones and the seasonal check will nag, because a cloudy day and a broken panel look identical to sun geometry. That is the wall. The 25% tolerance band is a blunt way to ride through normal weather, and it works until a genuinely bad week hides a genuinely bad panel.

The honest boundary is this: use sun times as the reference for checks about timing and geometry. The daylight window is deterministic; peak offset is useful when it persists across multiple comparable days, but clouds can move a single day's observed maximum. Lean on day-length scaling only to keep the seasonal baseline in the right ballpark. The moment you need to tell "cloudy" from "faulty," or you care about temperature derating and soiling trends, you have left what geometry can answer and you want an irradiance model: Forecast.Solar and Solcast expose one over an API (Forecast.Solar drops straight into Home Assistant if that is where your dashboard lives), pvlib gives you one in Python, and any of them will take your panel tilt and azimuth into account.

Drop the daylight gate in first. It is the cheapest change and stops the most false alarms. Add the peak-drift check once you have per-interval data to compare against solar noon. And when geometry-level checks stop being enough, treat that as the cue to pull an irradiance forecast, not to keep widening the thresholds until the alerts go quiet.

Enrich Elasticsearch Logs With GeoIP at Ingest

ABDULLAH AFZAL — Mon, 24 Aug 2026 13:26:25 +0000

An access log full of raw IPs can't answer where a traffic spike came from. Elasticsearch GeoIP fixes that at write time, enriching public-IP events with whatever country, region, city, and coordinate data is available so queries, alerts, and dashboards downstream can use geography directly. This guide sets up that enrichment in an ingest pipeline, fixes the two things that silently break it, and puts your logs on a Kibana map.

TL;DR

The geoip processor ships with Elasticsearch as a module. No plugin install, and it auto-downloads the free MaxMind GeoLite2 databases.

Enrichment happens in an ingest pipeline. Test it with the _simulate API before you point real data at it.

Your Kibana map will be empty unless the location field is mapped as geo_point before you index. Set that in an index template first.

Private and internal IPs (RFC 1918) return no geo fields by design. Handle them, don't ignore them.

GeoLite2 is city-level-optimistic and CC BY-SA. When you need better accuracy or security context, swap the database at ingest without changing the pipeline shape.

The short version: turn on a bundled processor, wire it into a pipeline, map one field correctly, and Kibana renders your traffic on a map. The parts that trip people up are the geo_point mapping and the IPs that have no location, both covered below. The core examples below target modern Elasticsearch 8.x and 9.x clusters with security enabled. Third-party ingest plugins have their own Elasticsearch-version compatibility requirements, so check the plugin's supported version before installing one.

What the Elasticsearch geoip processor gives you

The geoip processor is a module distributed with Elasticsearch, so on a current cluster there's nothing to install. By default it uses the GeoLite2 City, GeoLite2 Country, and GeoLite2 ASN databases from MaxMind, shared under CC BY-SA 4.0, and Elasticsearch downloads and updates them automatically from the Elastic GeoIP endpoint.

Feed it a field holding an IP address and it writes a geoip object onto the document. With the default City database, that object can include continent_name, country_iso_code, country_name, region_iso_code, region_name, city_name, and a location object holding lat and lon. You control which of those land with the properties option; the default set is continent_name, country_iso_code, country_name, region_iso_code, region_name, city_name, and location.

Two option names worth knowing before you write anything: target_field (default geoip) is where the enriched object goes, and ignore_missing (default false) decides whether a document with no IP field quietly passes through or errors. We'll use both.

Step 1: Create the ingest pipeline

An ingest pipeline is a named list of processors that runs on a document before it's indexed. Create one with a single geoip processor pointed at your IP field:

# Create a pipeline named "geoip-pipeline" that enriches the "ip" field.
# --cacert points at the CA cert Elasticsearch generated on first start;
# on 8.x/9.x the HTTP layer is TLS-on by default, so http:// will fail.
curl -sS -X PUT "https://localhost:9200/_ingest/pipeline/geoip-pipeline" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Add GeoIP fields from the ip field",
    "processors": [
      {
        "geoip": {
          "field": "ip",
          "target_field": "geoip",
          "ignore_missing": true
        }
      }
    ]
  }'

ignore_missing: true matters more than it looks. Real log streams have events without a client IP (health checks, internal jobs). Without it, every one of those throws and the document is rejected. With it, they index cleanly and simply carry no geoip object.

Before you send a single real document, dry-run the pipeline with the _simulate API. This runs your processors against a sample doc and returns the result without indexing anything:

# Dry-run the pipeline against a real public IP.
# 8.8.8.8 is a convenient public test address. The exact GeoLite2 fields and coordinates can change as the database is updated.
curl -sS -X POST "https://localhost:9200/_ingest/pipeline/geoip-pipeline/_simulate" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "docs": [
      { "_source": { "ip": "8.8.8.8" } }
    ]
  }'

The response wraps the enriched document under doc._source, and you should see a populated geoip object:

{
  "docs": [
    {
      "doc": {
        "_source": {
          "ip": "8.8.8.8",
          "geoip": {
            "continent_name": "North America",
            "country_iso_code": "US",
            "country_name": "United States",
            "location": { "lon": -97.822, "lat": 37.751 }
          }
        }
      }
    }
  ]
}

If _simulate gives you the fields you expect, the pipeline works. The rest is deciding what data flows through it and making sure Kibana can read the output.

Step 2: Map location as geo_point before you index

Here's the failure that fills the Elastic forums: everything ingests fine, the geoip.location field is populated, and the Kibana map is stubbornly empty. The cause is mapping. Elasticsearch's dynamic mapping sees { "lat": ..., "lon": ... } and guesses two float fields. Kibana Maps only plots a field typed as geo_point, and it won't infer that on its own.

Fix it once with an index template so every matching index is born with the right type:

# Any index matching "logs-geo-*" gets geoip.location typed as geo_point.
# Create this BEFORE the first document lands, or the wrong type sticks.
curl -sS -X PUT "https://localhost:9200/_index_template/logs-geo-template" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "index_patterns": ["logs-geo-*"],
    "template": {
      "settings": {
        "index.default_pipeline": "geoip-pipeline"
      },
      "mappings": {
        "properties": {
          "geoip": {
            "properties": {
              "location": { "type": "geo_point" }
            }
          }
        }
      }
    }
  }'

Two things happened in that template. The mappings block pins geoip.location to geo_point so Kibana will plot it. And index.default_pipeline sets the pipeline to run automatically on anything written to a logs-geo-* index, so you don't have to name it on every request.

Pitfall: mapping type is fixed at field creation. If documents already landed and geoip.location came out as float, you can't change it in place. You create a new index with the correct template and reindex into it. Get the template in before the first write and you never hit this.

Step 3: Wire the pipeline to your log stream

You have two ways to attach the pipeline. The template above already set index.default_pipeline, which is the clean option: write to the index normally and enrichment is automatic. The other option is naming the pipeline per request with ?pipeline=geoip-pipeline, which is handy for one-off backfills but noisy to repeat on every write.

If you ingest with your own code, the bulk helper is the usual path. Here's a minimal, production-shaped Python ingester using the official client:

import os
from elasticsearch import Elasticsearch, helpers

# Never hardcode credentials. Pull them from the environment.
ES_URL = os.environ.get("ES_URL", "https://localhost:9200")
ES_USER = os.environ.get("ES_USER", "elastic")
ES_PASSWORD = os.environ.get("ES_PASSWORD")
CA_CERT = os.environ.get("ES_CA_CERT", "/etc/elasticsearch/certs/http_ca.crt")

client = Elasticsearch(
    ES_URL,
    basic_auth=(ES_USER, ES_PASSWORD),
    ca_certs=CA_CERT,
    request_timeout=10,  # fail fast instead of hanging a worker
)

def log_events():
    # Replace with your real source (a file tail, a queue, etc.).
    yield {"ip": "8.8.8.8", "path": "/checkout", "status": 200}
    yield {"ip": "2001:4860:4860::8888", "path": "/login", "status": 401}

def index_logs():
    # The index name matches logs-geo-*, so the default_pipeline runs
    # and geo_point mapping applies. No per-doc pipeline needed here.
    actions = ({"_index": "logs-geo-000001", "_source": event}
               for event in log_events())
    try:
        success, errors = helpers.bulk(client, actions, raise_on_error=False)
        if errors:
            # Log rejected docs; don't let one bad IP kill the batch.
            for err in errors:
                print(f"index error: {err}")
        return success
    except Exception as exc:
        # Network or auth failure: surface it, don't swallow it.
        print(f"bulk ingest failed: {exc}")
        return 0

if __name__ == "__main__":
    print(f"indexed {index_logs()} events")

raise_on_error=False plus an error loop is deliberate: one document with a malformed IP shouldn't sink a 10,000-event batch. You log the rejects and keep going.

One convention worth adopting if you use the Elastic Common Schema: put the client address in source.ip and target source.geo instead of a bare geoip field. Elastic's own dashboards and detection rules expect ECS field names like source.geo.country_iso_code, source.geo.city_name, and source.geo.location. Set "field": "source.ip" and "target_field": "source.geo" in the processor and your data drops straight into the built-in tooling.

A word on Logstash, since half the tutorials on this topic start there. The Logstash geoip filter still works and still makes sense if Logstash is already in your pipeline doing Grok parsing and transforms. But if Elasticsearch is your ingest point, the ingest-pipeline approach keeps enrichment inside the cluster with one less moving part to run and monitor. Use the filter when you're already in Logstash; use the processor when you're not.

Step 4: Put it on a map in Kibana

With geo_point mapping in place, Kibana Maps takes a couple of clicks:

Create a data view over your logs-geo-* indices (Stack Management, then Data Views).
Open Maps from the Analytics menu and add a layer from that data view.
Because geoip.location (or source.geo.location) is a geo_point, the documents layer plots each event as a point. Style by count to cluster dense areas. If you followed a tutorial that told you to create a "Tile Map" or "Coordinate Map" visualization, that's why it didn't work. Those classic visualization types were retired; the Maps application replaced them, and it reads geo_point fields directly through a data view.

Private and internal IPs return nothing

The geoip processor looks up public IP geolocation. Private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, and carrier-grade NAT (100.64.0.0/10) have no geographic location, so those documents come back with no geoip object at all. That's correct behavior, but if a chunk of your traffic is internal, a naive setup leaves you with events that silently have no geo and no explanation.

Tag them instead of dropping them. Add a conditional processor that marks internal traffic before the lookup, so a missing geoip object is intentional rather than a mystery:

# Mark RFC 1918 addresses as internal, then geoip-enrich the rest.
# Explicitly match the RFC 1918 private ranges so internal traffic
# is labeled instead of silently appearing without GeoIP data.
curl -sS -X PUT "https://localhost:9200/_ingest/pipeline/geoip-pipeline" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Tag internal IPs, geoip-enrich the rest",
    "processors": [
      {
        "set": {
          "field": "network.scope",
          "value": "internal",
          "if": "def ip = ctx.ip; ip != null && (ip.startsWith(\"10.\") || ip.startsWith(\"192.168.\") || ip.startsWith(\"172.16.\") || ip.startsWith(\"172.17.\") || ip.startsWith(\"172.18.\") || ip.startsWith(\"172.19.\") || ip.startsWith(\"172.20.\") || ip.startsWith(\"172.21.\") || ip.startsWith(\"172.22.\") || ip.startsWith(\"172.23.\") || ip.startsWith(\"172.24.\") || ip.startsWith(\"172.25.\") || ip.startsWith(\"172.26.\") || ip.startsWith(\"172.27.\") || ip.startsWith(\"172.28.\") || ip.startsWith(\"172.29.\") || ip.startsWith(\"172.30.\") || ip.startsWith(\"172.31.\"))"
        }
      },
      {
        "geoip": {
          "field": "ip",
          "target_field": "geoip",
          "ignore_missing": true
        }
      }
    ]
  }'

Internal events now carry network.scope: internal, so one common reason for a missing geoip object is explicit instead of silent. Public IPs with no database match can still have no geoip object. No more staring at half-empty maps wondering where the other half went.

Backfilling indices you already have

Enrichment only touches documents at write time, so turning on the pipeline does nothing for the millions of events already sitting in your indices. To geo-tag existing data, run _update_by_query with the pipeline applied:

# Reprocess existing docs through the pipeline.
# Run this against a copy or a low-traffic window first: it rewrites
# every matched document and costs real I/O.
curl -sS -X POST "https://localhost:9200/logs-geo-000001/_update_by_query?pipeline=geoip-pipeline&wait_for_completion=false" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must_not": [
          { "exists": { "field": "geoip" } }
        ]
      }
    }
  }'

The must_not exists geoip filter avoids reprocessing documents that were successfully enriched. Be aware that private IPs and public IPs with no database match also have no geoip field, so they will be selected again on a later run. If you need a strictly resumable backfill, add a separate processing marker and filter on that instead.
wait_for_completion=false returns a task ID immediately so a long backfill doesn't tie up your connection; poll it with the Tasks API.

One caveat: if the old index has geoip.location mapped as float (because it predates your template), _update_by_query writes the fields but Kibana still won't map them. In that case you reindex into a freshly templated index instead. Backfill in place when the mapping is already correct; reindex when it isn't.

When GeoLite2 is not enough

GeoLite2 is free, bundled, and good enough to see which countries your traffic comes from. It is also the lite tier: MaxMind's own positioning is that GeoLite2 is less accurate than paid GeoIP2, city-level results are approximate, and the CC BY-SA 4.0 license carries attribution and share-alike obligations that some commercial deployments can't accept. When you outgrow it, you swap the database, not the pipeline.

You have a few paths, and they nest cleanly into what you already built:

Point the same processor at a licensed MaxMind database. Elasticsearch can download GeoIP2 directly using your MaxMind license key through the database configuration API, and the geoip processor keeps working unchanged.
Use IPinfo databases via the ip_location processor. Recent Elasticsearch versions ship an ip_location processor that supports IPinfo databases alongside MaxMind, so you can switch providers without leaving the ingest layer.
Load a custom database file. Both processors accept a database_file option, so a compatible MaxMind-format database supported by the processor can back the lookup.
Enrich from a local database that also carries security and timezone context. IPGeolocation publishes an Elasticsearch ingest processor plugin that runs the lookup against a locally installed IPGeolocation database, so alongside country and city you get currency, timezone, and IP-security signals in the same document, with no per-event API call. That last option is worth a concrete look because it combines IPGeolocation's geolocation, timezone, currency, and security data in one local enrichment path. The plugin installs with elasticsearch-plugin install, a setup script downloads the database tier you licensed, and the processor is named ipgeo. Its required options are field (your IP field) and database_version (DB-I through DB-VII, the database tier you licensed); target_field defaults to ipgeo, and include pulls in the extra data classes:

# The ipgeo processor from the IPGeolocation plugin.
# database_version selects the licensed DB tier; include pulls in
# the security and timezone data classes on top of geolocation.
curl -sS -X PUT "https://localhost:9200/_ingest/pipeline/ipgeo-pipeline" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Enrich with IPGeolocation databases",
    "processors": [
      {
        "ipgeo": {
          "field": "ip",
          "database_version": "DB-VI",
          "ignore_missing": true,
          "include": "security,timezone"
        }
      }
    ]
  }'

A document enriched by that pipeline carries a richer object than GeoLite2 returns. The relevant part of the response, from the plugin's own docs:

{
  "ipgeo": {
    "country_name": "United States",
    "country_code2": "US",
    "city": "San Francisco",
    "state_prov": "California",
    "zipcode": "94107-2008",
    "location": { "lon": -122.39117, "lat": 37.78229 },
    "currency": { "symbol": "$", "code": "USD", "name": "US Dollar" },
    "time_zone": {
      "name": "America/Los_Angeles",
      "offset": -7.0,
      "is_dst": true,
      "current_time": "2024-05-17 04:52:01.693-0700"
    },
    "security": {
      "is_proxy": false,
      "proxy_type": "",
      "is_tor": false,
      "is_anonymous": false,
      "is_known_attacker": false,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": false,
      "threat_score": 0
    }
  }
}

The trade-off is honest and worth stating plainly: this path costs a plugin install, a licensed database, and an Elasticsearch restart, and the ipgeo.location field still needs the same geo_point mapping as before. What you get back is currency, timezone, and a security block (proxy, Tor, cloud-provider, known-attacker flags, and a threat_score) on every event, computed locally with no lookup latency. If your logs feed fraud rules or security dashboards, that context in the same document is the reason to pay. If you only need a map of where traffic comes from, GeoLite2 is already enough and you can stop at Step 4.

Operational notes

A few things that bite in production and rarely make it into tutorials:

The auto-downloaded databases expire. If Elasticsearch can't reach the Elastic GeoIP endpoint for 30 days, it stops using the stale databases and enrichment quietly goes blank, showing up as _geoip_expired_database tags on your documents. In an air-gapped cluster this is a when, not an if. Plan for a reverse-proxy or custom endpoint, or serve your own databases and turn the downloader off.

To disable the downloader entirely, set ingest.geoip.downloader.enabled: false in the cluster settings. Do this when you run only custom or licensed databases and don't want Elasticsearch reaching out for GeoLite2 updates you aren't using. Leave it enabled if you rely on Elasticsearch's automatically downloaded GeoLite2 databases. Disabling the downloader removes those downloaded databases; the 30-day expiration behavior applies when updates remain enabled but Elasticsearch cannot reach the GeoIP endpoint.

Enrichment runs on ingest nodes and costs CPU per document. On a high-volume cluster, watch ingest node load after you turn on a geo pipeline, and give dedicated ingest nodes room if a lookup runs on every event.

Get the geo_point mapping in before the first write, tag your internal IPs, and decide up front whether the free database is enough or you need licensed accuracy and security context. Those three calls are the difference between a map that just works and a week of debugging why half your events have no location.

How Do You Detect Bogon and Reserved IPs in Code?

ABDULLAH AFZAL — Thu, 20 Aug 2026 11:38:47 +0000

Some IP addresses should never show up as a client: bogon and reserved ranges. A signup form that logs 10.0.0.7 as the visitor, a fraud rule that scores 192.0.2.45, a geolocation lookup on 169.254.10.2: all three are working with addresses that carry no public meaning, and if your code treats them like normal traffic, you get silent bad data.

This is a reference for the application side of that problem. Not router ACLs or BGP prefix lists, which are covered to death elsewhere, but the check you run in Node or PHP when an IP arrives at your app and you have to decide: reject it, flag it, or trust it.

TL;DR

Bogon and reserved ranges are IPs that should never appear as a public source: unallocated space plus reserved blocks like private (RFC 1918), CGNAT, loopback, link-local, and documentation.
The action depends on the block. Private ranges are fine inside your network but suspect as a public client source. Documentation and "this network" ranges are always rejectable. CGNAT is legitimate but ungeolocatable.
The IPGeolocation API returns HTTP 423 Locked for bogon and private addresses, and those lookups do not consume credits, so the API can also act as a validation backstop.
In code, classify the IP against the special-use CIDR set locally first (fast, no network), then let the 423 be the authoritative signal on the lookup you were going to make anyway.
Normalize IPv4-mapped IPv6 (::ffff:a.b.c.d) before you check, or half your rules miss.

Special-use IPs fall into ranges that are either unallocated or reserved by RFC. Your app should treat each range by what it means: reject the impossible ones, flag the ungeolocatable ones, and accept private ranges only where an internal source makes sense. The rest of this reference is the range-by-range mapping and the code to apply it.

The special-use IP handling matrix

The core of this reference is not "what is a bogon." Our own full canonical IPv4 and IPv6 bogon list already covers the definitions and the complete range tables. What almost nobody writes down is what an application should do with each range when it shows up as a client address. That is the table below.

Three actions:

Reject: the address cannot legitimately be a public client. Drop it, or 400 the request.
Flag: the address can appear legitimately but you cannot geolocate or trust it. Keep the request, mark it, skip location logic.
Accept (internal): valid when the source is genuinely inside your network or behind your own proxy. The same address as a claimed public client source is a reject.

IPv4 special-use ranges and how your app should treat each

Range	What it is	Defined by	App treatment as a public client source
`0.0.0.0/8`	"This network"	RFC 791	Reject
`10.0.0.0/8`	Private	RFC 1918	Accept internal, reject as public
`100.64.0.0/10`	CGNAT / shared	RFC 6598	Flag (behind carrier NAT, ungeolocatable)
`127.0.0.0/8`	Loopback	RFC 1122	Reject (that is your own host)
`169.254.0.0/16`	Link-local	RFC 3927	Reject
`172.16.0.0/12`	Private	RFC 1918	Accept internal, reject as public
`192.0.0.0/24`	IETF protocol assignments	RFC 6890 / IANA registry	Check specific assignment; do not blanket-reject the entire `/24`
`192.0.2.0/24`	Documentation (TEST-NET-1)	RFC 5737	Reject
`192.168.0.0/16`	Private	RFC 1918	Accept internal, reject as public
`198.18.0.0/15`	Benchmark testing	RFC 2544	Reject
`198.51.100.0/24`	Documentation (TEST-NET-2)	RFC 5737	Reject
`203.0.113.0/24`	Documentation (TEST-NET-3)	RFC 5737	Reject
`224.0.0.0/4`	Multicast	RFC 5771	Reject (not a unicast client)
`240.0.0.0/4`	Reserved, future use	RFC 1112	Reject
`255.255.255.255/32`	Limited broadcast	RFC 919	Reject

The authoritative source of truth for this list is the IANA IPv4 Special-Purpose Address Registry, which records each block, its defining RFC, and whether it is valid as a source or destination. If you only hardcode one list, hardcode that one.

IPv6 ranges that actually reach applications

You do not need the full IPv6 bogon set (that is tens of thousands of prefixes). You need the handful that show up at an application:

Range	What it is	App treatment
`::1/128`	Loopback	Reject (your own host)
`::/128`	Unspecified	Reject
`::ffff:0:0/96`	IPv4-mapped	Normalize, then re-check the embedded IPv4
`fc00::/7`	Unique local (ULA)	Accept internal, reject as public
`fe80::/10`	Link-local	Reject
`2001:db8::/32`	Documentation	Reject
`ff00::/8`	Multicast	Reject

The IPv4-mapped row is the one that bites people. An address like ::ffff:10.0.0.7 is a private IPv4 address wearing an IPv6 coat. If your check only looks at IPv6 ranges, it sails through. Strip the ::ffff: prefix and run the IPv4 rules on what is left.

Bogon, martian, reserved: the distinction developers get wrong

These terms overlap, but they are not identical. A bogon is commonly an address from space that should not appear as a public Internet source, including unallocated space and addresses reserved for private or special use. A martian is an operational term for a packet whose source or destination is invalid or implausible in the network where it appears. Unlike the reserved ranges, “martian” is not a fixed CIDR list; whether an address is martian can depend on routing and network context.

Why it matters for your code: the stable special-use ranges are safe to hardcode because they rarely change. Unallocated address space is different: it changes as IANA and the RIRs delegate space, which is why a static “block all bogons” list eventually goes stale. For application-side validation, check the stable special-use ranges locally and use a current lookup or bogon feed for the moving portion. If you have ever wondered "why do I have a bogon IP in my logs," it is usually one of two things: a misconfigured client leaking a private source, or a spoofed packet. Neither is a real user you can act on.

Why your geolocation lookup returns 423 on these IPs

A well-behaved geolocation API refuses to invent a location for an address that has none. Send a bogon to the lookup endpoint and you get a 423 Locked back instead of a fake record:

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

HTTP/1.1 423 Locked
{
  "message": "'10.0.0.1' is a bogon IP address."
}

Two things make this useful rather than just an error. First, the lookup is not billed: bogon, private, and malformed IPs do not count against your quota, so you can throw questionable addresses at the API purely to validate them. Second, in a bulk call the same input does not blow up the batch. Invalid entries come back as per-record objects carrying a message field, while the valid IPs in the request are geolocated normally, so you can run a cleanup pass over a dirty log without splitting it first.

IPinfo, ip-api, MaxMind GeoIP2, IPGeolocation, and other IP-data providers handle bogon and private addresses specially, but the response model differs: some return a bogon marker, some return an error, and some return no matching record. I am using IPGeolocation for the examples because the 423 plus the not-billed behavior makes it clean to wire up as a validation layer. Pick whichever is already in your stack; the handling pattern below is the same.

Detecting special-use IPs in code

Two layers. The local check classifies the address against the martian set with no network call, which is the fast path for the common case. The API 423 is the authoritative backstop on the lookup you were making anyway, and it covers the moving unallocated ranges your hardcoded list does not.

Node.js: local classification with `net.BlockList`

Node ships a CIDR matcher in the standard library, so you do not need a dependency for the local check.

const net = require('node:net');

// Build the block list once at module load. Reuse it; rebuilding per request is wasteful.
const REJECT = new net.BlockList();
const FLAG = new net.BlockList();
const PRIVATE = new net.BlockList();

// Always-reject IPv4 (impossible or documentation-only as a public source)
[['0.0.0.0', 8], ['127.0.0.0', 8], ['169.254.0.0', 16],
 ['192.0.2.0', 24], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
 ['224.0.0.0', 4], ['240.0.0.0', 4]].forEach(([ip, p]) => REJECT.addSubnet(ip, p, 'ipv4'));

// Private (accept only when an internal source is expected)
[['10.0.0.0', 8], ['172.16.0.0', 12], ['192.168.0.0', 16]]
  .forEach(([ip, p]) => PRIVATE.addSubnet(ip, p, 'ipv4'));

// CGNAT: legitimate but ungeolocatable, so flag rather than reject
FLAG.addSubnet('100.64.0.0', 10, 'ipv4');

// IPv6 special-use ranges that can reach application code
REJECT.addSubnet('::', 128, 'ipv6');          // unspecified
REJECT.addSubnet('::1', 128, 'ipv6');         // loopback
REJECT.addSubnet('fe80::', 10, 'ipv6');       // link-local
REJECT.addSubnet('2001:db8::', 32, 'ipv6');   // documentation
REJECT.addSubnet('ff00::', 8, 'ipv6');        // multicast
PRIVATE.addSubnet('fc00::', 7, 'ipv6');       // unique local

function classifyIp(raw) {
  // IPv4-mapped IPv6 (::ffff:10.0.0.7) is a v4 address in disguise. Unwrap before checking.
  const ip = raw.startsWith('::ffff:') && raw.includes('.') ? raw.slice(7) : raw;
  const type = net.isIPv6(ip) ? 'ipv6' : net.isIPv4(ip) ? 'ipv4' : null;
  if (!type) return 'reject';          // not a valid IP at all
  if (REJECT.check(ip, type)) return 'reject';
  if (FLAG.check(ip, type)) return 'flag';
  if (PRIVATE.check(ip, type)) return 'private';   // caller decides accept vs reject by context
  return 'public';
}

module.exports = { classifyIp };

net.BlockList does the subnet math for both families, and building the lists once at load keeps the per-request cost to a lookup. The classifyIp return value is the decision your route handler acts on, not a bare boolean, because "reject," "flag," and "internal-only" are three different responses.

For addresses that pass the local special-use checks but may still fall into freshly unallocated space, let the geolocation lookup act as the backstop:

The following example uses the global fetch API and AbortSignal.timeout(), so run it on Node.js 18+.

async function geolocate(ip) {
  const local = classifyIp(ip);
  if (local === 'reject') {
      return { ok: false, reason: 'special-use' };
  }

  if (local === 'flag') {
      return { ok: null, reason: 'cgnat' };
  }

  if (local === 'private') {
      return { ok: null, reason: 'private' };
  }

  try {
    const res = await fetch(
      `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${process.env.IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}`,
      { signal: AbortSignal.timeout(1500) } // never let a lookup hang a request
    );

    // 423 means the API classified it as bogon/private. Trust that over your static list.
    if (res.status === 423) return { ok: false, reason: 'bogon' };
    if (!res.ok) return { ok: null, reason: `http_${res.status}` }; // fail open, see below

    const data = await res.json();
    return { ok: true, location: data.location ?? null };
  } catch (err) {
    // Timeout or network error. Fail open here so a lookup outage does not block real users.
    console.error('geo lookup failed:', err.message);
    return { ok: null, reason: 'lookup_error' };
  }
}

Note the two failure paths. A 423 is a definite "this IP is special-use," so it is safe to act on. A timeout or 5xx is unknown, and the ok: null lets the caller decide whether to fail open or closed.

PHP: a CIDR check without a library

PHP has no native "is this IP in this CIDR" for both families, so here is a compact helper that handles v4 and v6 with inet_pton and a bitmask.

<?php

function ipInCidr(string $ip, string $cidr): bool {
    [$subnet, $bits] = explode('/', $cidr);
    $ipBin = @inet_pton($ip);
    $subnetBin = @inet_pton($subnet);
    // Reject mismatched families (v4 IP against v6 subnet, or an unparseable address)
    if ($ipBin === false || $subnetBin === false || strlen($ipBin) !== strlen($subnetBin)) {
        return false;
    }
    $bits = (int) $bits;
    $bytes = intdiv($bits, 8);
    $remainder = $bits % 8;
    // Whole-byte portion must match exactly
    if ($bytes > 0 && substr($ipBin, 0, $bytes) !== substr($subnetBin, 0, $bytes)) {
        return false;
    }
    // Partial byte: compare only the masked high bits
    if ($remainder !== 0) {
        $mask = ~(0xff >> $remainder) & 0xff;
        if ((ord($ipBin[$bytes]) & $mask) !== (ord($subnetBin[$bytes]) & $mask)) {
            return false;
        }
    }
    return true;
}

function classifyIp(string $raw): string {
    // Normalize IPv4-mapped IPv6 addresses so the IPv4 rules apply.
$ip = $raw;
$packed = @inet_pton($raw);

if (
    $packed !== false &&
    strlen($packed) === 16 &&
    substr($packed, 0, 10) === str_repeat("\x00", 10) &&
    substr($packed, 10, 2) === "\xff\xff"
) {
    $ip = inet_ntop(substr($packed, 12, 4));
}

    if (filter_var($ip, FILTER_VALIDATE_IP) === false) {
        return 'reject'; // not an IP we can trust
    }

    $reject = ['0.0.0.0/8','127.0.0.0/8','169.254.0.0/16','192.0.2.0/24','198.18.0.0/15','198.51.100.0/24','203.0.113.0/24','224.0.0.0/4','240.0.0.0/4','::/128','::1/128','fe80::/10','2001:db8::/32', 'ff00::/8'];
    $private = ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7'];

    foreach ($reject as $cidr) {
        if (ipInCidr($ip, $cidr)) return 'reject';
    }
    if (ipInCidr($ip, '100.64.0.0/10')) return 'flag'; // CGNAT
    foreach ($private as $cidr) {
        if (ipInCidr($ip, $cidr)) return 'private';
    }
    return 'public';
}

The @ on inet_pton suppresses the warning on a garbage input; the explicit false checks handle it instead. Pair classifyIp with the same API backstop as the Node version. If it returns reject, stop immediately. Handle flag and private according to request context without geolocating them. Only send addresses classified as public to /v3/ipgeo; if that lookup returns HTTP 423, treat it as a bogon or otherwise non-public address that your local static list did not catch.

Reject, flag, or accept: making the call

The local classifier hands you a label; the request context decides the response.

Pitfall: The single most common mistake is treating a private source IP as a real client because your app sits behind a load balancer. If you read req.socket.remoteAddress, you will see the proxy, not the user. Read the client IP from a trusted X-Forwarded-For (only the hop your proxy sets, not the whole attacker-controllable header) and classify that.

Fail-open versus fail-closed is a decision you should make on purpose, not by accident. If the geolocation lookup errors or times out, failing open (let the request through, skip the location logic) is right for most apps, because a lookup outage should not lock out real users. Fail closed only when the geolocation is the security control, for example a hard geo-restriction where "unknown" must mean "denied." The 423 case is different from an error: it is a definite answer, so you act on it regardless of your fail direction.

The CGNAT trap deserves a callout. 100.64.0.0/10 is legitimate inside carrier and service-provider networks, but it is not a globally routable client address. If it reaches your application through trusted internal infrastructure, flag it and skip geolocation. If it appears as the claimed source of a normal public Internet request, treat it as invalid or suspicious rather than as a geolocatable public client.

Keeping the list current

The reserved ranges in the tables above are safe to hardcode because they are defined by RFCs that change on the order of years. The unallocated portion is the part that moves, and IPv6 still has large unallocated regions that shift as IANA delegates space. If you need the moving set kept current at the network layer, Team Cymru's bogon reference is the long-standing source, published as BGP feeds, DNS, and plain lists that update through the day. For an application, the cleaner split is to hardcode the static martian set for your local fast path and let the API's 423 cover whatever has changed since you last looked.

If you run this at scale, cache the classification. The local check is cheap, but the API backstop is a network hop, so a short-lived cache keyed on the IP saves you repeat lookups on the same noisy sources, which special-use addresses tend to be.

Which Proxy & VPN Signals Should Block a Signup?

ABDULLAH AFZAL — Tue, 18 Aug 2026 12:51:01 +0000

A proxy or VPN flag at signup is a signal, not a verdict. This guide maps each IP signal to a block, friction, or allow decision at account creation, so a single boolean does not end up quietly blocking real customers or waving real fraud through.

The mistake that runs through most fake-account defenses is treating "this IP is anonymized" as "this account is fraud." It isn't. A commercial VPN, a datacenter proxy, a residential proxy, a Tor exit, and an iCloud Private Relay connection are five different risk profiles, and two of them are things your best paying customers use every day. The decision you actually make at signup is per-signal, and it has three settings: allow, add friction, block.

TL;DR

Most anonymized traffic at signup earns friction, not a block. Reserve outright blocks for bots, known attackers, and stacked high-risk signals.
Never treat a relay as a VPN. iCloud Private Relay and Cloudflare WARP are widely used privacy services, and blocking their exit IPs outright can reject legitimate users.
Residential proxies are the hard case. The IP genuinely belongs to a consumer ISP, so IP data alone can flag it but cannot cleanly clear it. Pair it with non-IP signals before you block.
Use a single 0-100 threat score to pick the action, and per-detection confidence scores to decide how far to take it.
Run shadow mode first: log the score and the action you would have taken for two weeks, then set thresholds against real numbers, not guesses.

A proxy flag tells you an IP is anonymized; it does not tell you the person behind it is a fraudster. The job at signup is to route each signal to the right action. Bots and known attackers get blocked, VPNs and relays usually get allowed or lightly challenged, and residential proxies get friction until a second signal confirms intent. The rest of this is the per-signal matrix and the thresholds behind it.

The signup decision matrix

This is the reference. Each row is a signal you get back on an IP lookup, the action it usually justifies at account creation, and the legitimate user you would wrongly hit if you blocked on that signal alone.

Signal	Usual action at signup	Why	Who a hard block wrongly hits
`is_bot`, `is_known_attacker`	Block	Automation or a history of malicious activity. There is almost no legitimate signup reason to be either.	Rare. An occasional security scanner or a recycled IP with stale reputation.
`is_tor`	Step-up or block, by product	Strong anonymity with a high abuse rate. Fine to allow for a privacy tool, wrong to allow for a payments product.	Privacy-conscious users, journalists, people in censored regions.
`is_residential_proxy`	Friction or step-up. Rarely an IP-only block.	The address belongs to a real consumer ISP, so you cannot clear it on IP data alone.	A real household running a proxy SDK they forgot they installed; a shared home IP.
`is_proxy` (datacenter or commercial)	Friction; block on high confidence plus a raised score	Server-origin traffic at a human signup is unusual, but not always fraud.	A user behind a corporate egress that routes through a datacenter proxy.
`is_vpn`	Friction, not a block	Extremely common among legitimate privacy and corporate users.	Everyone on NordVPN, Surfshark, or a work VPN. That is a lot of people.
`is_relay` (iCloud Private Relay, WARP)	Allow or log. Do not treat as a VPN.	A privacy service used by legitimate Apple users, with no inherent indication of fraud.	iPhone users who have iCloud Private Relay enabled.
`is_cloud_provider`	Context. Friction only when paired with another flag.	Could be a scraper, could be a user on a cloud-hosted VPN.	Developers and privacy users on cloud egress.
`is_spam`	Friction or step-up	A spam history is a moderate signal, not a conviction.	Shared or recycled IPs that inherited a bad reputation.

The pattern to notice: only two rows are block-by-default. Everything else is friction or context, because the false-positive cost is real and the signals overlap. The same IP can be flagged VPN, proxy, and residential proxy at once, and the right response is driven by the combination and the score, not by any single true.

What each signal actually means at signup

Bots and known attackers

These are the clean blocks. is_bot marks automated behavior; is_known_attacker marks an IP with a history of brute force, credential stuffing, or vulnerability scanning. A human creating one account has no reason to trip either. If you block on anything at the IP layer, block on these, and log the rare false positive so you can spot a mislabeled range.

Tor exit nodes

is_tor is a product decision more than a fraud decision. Tor carries a high abuse rate, but it is also how some people access the internet safely. A privacy-forward tool might allow Tor signups with email verification. A payments product or a marketplace with promo credits probably sends Tor to step-up verification or blocks it. Pick the policy that matches what a fraudulent Tor signup would actually cost you, and say so in your own docs so support can explain it.

Residential proxies

This is the category that breaks blocklist-only defenses. A residential proxy routes traffic through egress points on real end-user devices whose IPs sit in address space allocated to consumer ISPs (security research on the residential-proxy ecosystem describes the model in detail). To your signup form, the request looks like an ordinary household on Comcast or BT, because at the network layer it is one.

That has a hard consequence: IP data can raise a flag on a known residential-proxy egress, but it cannot clear a residential IP the way it can clear a clean datacenter range, because the address is legitimately residential. So is_residential_proxy earns friction and a second look, not an automatic block. The second look is where non-IP signals carry the weight: email age, device consistency, and signup velocity from the same fingerprint. Anyone selling you "100% residential proxy detection" from IP data alone is overselling; the honest version is high-confidence flagging plus behavioral corroboration.

Datacenter and commercial proxies

is_proxy without the residential flag usually means a datacenter or commercial proxy: server-origin traffic. A person filling out a signup form from a datacenter IP is unusual enough to justify friction, and a high proxy_confidence_score stacked with a raised threat score is a reasonable block. The caveat sits right next to the rule: some corporate networks egress through commercial proxies, so confidence and score matter more than the bare boolean.

Commercial VPNs

is_vpn is the signal teams most often over-weight. Tens of millions of people run a VPN by default, for privacy, for work, or because their browser bundles one. Blocking VPN signups outright is a conversion tax you pay to catch a thin slice of fraud that better signals would catch anyway. Friction is almost always the right call: allow the signup, add a verification step, and let behavior downstream decide. Provider attribution helps here. A corporate VPN and a scraping network both set is_vpn, and naming the provider lets you write different rules for each instead of the same blunt block.

Relays: the false positive to stop making

If you take one thing from this guide, take this. is_relay covers iCloud Private Relay and services like Cloudflare WARP, and it is not a VPN in any sense that matters for fraud. Private Relay is available to iCloud+ subscribers who choose to enable it, which is a large share of iPhone traffic.

Treating relay traffic as VPN traffic and blocking it means turning away privacy-conscious Apple users at the door, and it is a common source of avoidable false positives. A separate relay flag exists precisely so you can allow these users while still challenging real VPN and proxy traffic. Allow, or log and move on.

Cloud provider IPs

is_cloud_provider on its own is weak. It could be a scraper running on a rented box, or a legitimate user whose VPN happens to exit through a cloud region. Treat it as context that sharpens other flags rather than a trigger on its own. Cloud plus bot plus a raised score is a block; cloud alone is a log line.

Turning scores into thresholds

Per-flag rules get you most of the way. A single aggregate score gets you a clean decision boundary. A composite threat_score from 0 to 100 rolls every signal into one number, and the documented action bands map directly onto the allow, friction, block model:

Threat score	Meaning	Signup action
1-19	Low observed risk	Allow with standard controls, log for pattern analysis
20-44	Use with context	Combine with device, behavior, velocity, or geo before acting
45-79	Elevated risk	Add friction: OTP, CAPTCHA, email verification, rate limiting, or a review queue
80-100	High risk	Block, hard challenge, or route to manual review

Two scores, two jobs. The threat_score picks the action band. The per-detection confidence scores, vpn_confidence_score and proxy_confidence_score, tell you how far to take that action. Medium-confidence VPN traffic in the 45-79 band gets a light challenge; a 99-confidence proxy detection stacked with attacker history in the 80-100 band gets blocked.

Here is the decision as code. It checks the strongest block signals first, allows relay traffic when no stronger risk signal is present, and then maps the remaining score bands to an action. It fails open, because a lookup timeout should not lock legitimate users out of your signup:

// Node.js 18+
const API_KEY = process.env.IPGEO_API_KEY;

// Returns "allow" | "friction" | "block". Fails open on any error.
async function signupAction(ip) {
  try {
    const res = await fetch(
      `https://api.ipgeolocation.io/v3/security?apiKey=${API_KEY}&ip=${encodeURIComponent(ip)}`,
      { signal: AbortSignal.timeout(1500) } // don't hang the signup flow
    );

    if (!res.ok) return "allow"; // fail open on API errors

    const security = (await res.json())?.security;
    if (!security) return "allow";

    const score = security.threat_score ?? 0;

    // Strong risk signals take precedence, even when the IP is also a relay.
    if (security.is_bot || security.is_known_attacker) return "block";

    if (score >= 80) return "block";

    // Relay alone is not a reason to challenge a legitimate signup.
    if (security.is_relay) return "allow";

    if (score >= 45) return "friction"; // OTP, CAPTCHA, email verification

    if (score >= 20 && security.is_residential_proxy) {
      return "friction";
    }

    return "allow";
  } catch {
    // Timeout, network error, or malformed response: let signup continue.
    return "allow";
  }
}

The fail open choice is deliberate and worth stating explicitly: if the risk lookup is unavailable, blocking every signup is worse than letting a few risky ones through to a later layer. If your product genuinely needs fail-closed at signup, that is a real choice too, but make it on purpose.

The false-positive costs you're trading against

Every block threshold buys fraud reduction with some rate of wrongly rejected real users. You should know who those users are before you set the dial, so this is the qualitative side of the ledger:

The corporate VPN user. Signs up from a work laptop that routes everything through the company VPN. Sets is_vpn. Blocking them means rejecting exactly the professional buyers a B2B product wants.
The traveler. On hotel or airport wifi with a personal VPN switched on, because that is the responsible thing to do on public networks. Blocking them punishes good security hygiene.
The iPhone user. Has iCloud Private Relay enabled, so their traffic sets is_relay. If your rules fold relay into VPN, you risk blocking a legitimate privacy-conscious user.
The real household behind a proxy SDK. Installed a free app that quietly enrolled their connection into a residential proxy network. Their signup is genuine even though the IP is flagged. This is why residential-proxy blocks need a second signal.

These are all realistic sources of false positives. They are ordinary people, and each one is a paying customer you turned away if a single anonymization flag is enough to block. That is the whole argument for friction over blocking on the middle-risk signals.

Where these signals come from

You get flags, scores, and provider names from an IP security lookup. IPQualityScore, Spur, and proxycheck all return proxy and VPN signals; I am using the IP Security API from IPGeolocation for the examples because it splits the relay flag out from VPN, names the provider behind a detection, and returns the 0-100 threat score the bands above are built on. Security fields are on the paid plans, starting at $19/month; the free plan returns geolocation but not the security object.

A single call to the dedicated /v3/security endpoint returns the full shape. This is a real flagged IP, not a documentation placeholder, so the payload matches what you would actually get back:

{
  "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."
  }
}

Three fields do the heavy lifting for signup decisions. threat_score picks the action band. is_relay, is_residential_proxy, and the provider-name arrays let you separate the risk profiles the matrix treats differently. And proxy_last_seen and vpn_last_seen date each detection, so an exit node seen this week can be weighted differently from one last observed months ago. For batch backfills over existing users, the same data is available in bulk at up to 50,000 IPs per request.

A starter policy you can ship

You do not need to get the thresholds perfect on day one. You need to stop guessing.

Shadow mode for two weeks. Log the threat_score, the flags, and the action your rules would have taken, but do not block anyone yet. This tells you how much of your real signup traffic each band actually catches.
Set the block line high. Start by hard-blocking only the 80-100 band plus is_bot and is_known_attacker. That catches the worst traffic with the lowest false-positive risk.
Route the middle to friction. Send 45-79 to email verification or a light challenge. Send residential-proxy flags in the 20-44 band to the same friction, not a block.
Let clean relays and low scores through. Allow relay traffic when no stronger block signal is present, and allow anything under 20 with standard controls.
Watch the false-block rate. The number that tells you a threshold is too tight is not caught fraud, it is support tickets from real users who could not sign up. Tune against that.

A few things that trip people up

is_proxy and is_residential_proxy are not the same decision. The first covers datacenter and commercial proxies, where a block on high confidence is defensible. The second covers consumer-ISP proxies, where an IP-only block is not, because the address is genuinely residential. Read them separately.

A high threat score is a reason to act, not a reason to block. The 45-79 band is deliberately the friction band. If you find yourself blocking there, you are trading conversion for a marginal fraud reduction that a verification step would have caught anyway.

Relay is not VPN. It keeps coming up because so many defenses get it wrong. If your rules do not have a separate branch for is_relay, add one before you touch anything else.

Shadow mode is not optional busywork. The teams that block real customers are almost always the ones that set thresholds from intuition instead of from two weeks of their own logged traffic.

Start in shadow mode, block only the top band and the clean bot signals, and send the middle to friction. Then tune against your false-block rate rather than your caught-fraud count, because the false blocks are the ones that cost you customers you will never hear from again.

Classify an IP by ASN Type: Hosting, Business, ISP

ABDULLAH AFZAL — Thu, 13 Aug 2026 10:35:25 +0000

An IP address does not tell you what kind of network it belongs to. The autonomous system behind it does. Every routable IP sits inside an ASN, and that ASN has a type: hosting, business, education, government, or a consumer ISP. One lookup returns it, and that single field sorts almost any address into datacenter traffic, an organization, or a real person on a home connection.

Almost. There are a few cases where ASN type alone points you toward the wrong conclusion, including one that matters particularly for fraud and abuse work. We'll get to them.

TL;DR

Every public IP belongs to an ASN, and the ASN carries a type field: ISP, HOSTING, BUSINESS, EDUCATION, or GOVERNMENT.
HOSTING means a datacenter or cloud provider. ISP means a consumer access network. BUSINESS, EDUCATION, and GOVERNMENT are organizations on their own address space.
A single call to the dedicated ASN endpoint returns the type and can also include routing data such as routes, upstreams, downstreams, and peers for additional context.
The type describes the network operator. When a business runs on rented cloud space, the operator is a hosting company but the tenant is a business. Reading only the ASN type mislabels them.

The rest of this is the matrix, a classifier you can paste in, and the four places the type field stops being enough.

The ASN-type classification matrix

Here is the whole idea in one table. Look up the ASN for an address, read type, map it to a bucket.

`asn.type`	What it is	Example ASN	Treat traffic as
`HOSTING`	Cloud/datacenter provider. Servers live here.	AS24940 (Hetzner)	Datacenter. Bots, scrapers, and VPN exits cluster here.
`ISP`	Primarily an end-user access network, including fixed-line and mobile ISP space.	AS1257 (Tele2)	Consumer/access network. Lower baseline infrastructure suspicion, but not proof of a human user.
`BUSINESS`	A company operating its own address space.	AS1 (Level 3)	Organization. Office egress, corporate VPNs, SaaS backends.
`EDUCATION`	Universities and research networks.	AS12 (New York University)	Organization. Campus and lab traffic.
`GOVERNMENT`	Public-sector networks.	(varies by RIR)	Organization.

The three buckets developers usually care about, hosting, business, and consumer, come straight out of this. HOSTING is your datacenter bucket. ISP is your consumer bucket. BUSINESS, EDUCATION, and GOVERNMENT are three flavors of the same "this is an organization, not a home user and not a rented server" bucket, and you can collapse them if your logic doesn't need the distinction.

What makes this reliable is that ASN type is a property of the network operator, not a guess from the IP number. You cannot look at 49.12.0.0 and know it's a datacenter. You look up its ASN, see AS24940 Hetzner tagged HOSTING, and now you know.

One ASN lookup, one classification

The ASN type field is available on the dedicated ASN endpoint and in the main geolocation response. The dedicated ASN API is the cleaner choice when classification is all you want, because it returns the ASN record and nothing else, and it takes either an IP or an AS number.

The response and the type field

A lookup by IP returns the ASN that announces it:

curl -X GET 'https://api.ipgeolocation.io/v3/asn?apiKey=API_KEY&ip=49.12.0.0'

{
  "ip": "49.12.0.0",
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "country": "DE",
    "type": "HOSTING",
    "domain": "hetzner.com",
    "date_allocated": "2002-06-03",
    "asn_name": "HETZNER-AS",
    "allocation_status": "ASSIGNED",
    "num_of_ipv4_routes": "84",
    "num_of_ipv6_routes": "6",
    "rir": "RIPE"
  }
}

type is HOSTING, so 49.12.0.0 is datacenter space. The type field requires a paid plan; the free tier returns the AS number, organization, and country but not the classification. Everything else in this guide keys off type, so that's the field to check your plan for.

Lookup by IP or by AS number

You can classify a single address, or a whole network. Passing an AS number instead of an IP skips the IP-to-ASN step and returns the same record:

curl -X GET 'https://api.ipgeolocation.io/v3/asn?apiKey=API_KEY&asn=1'

That returns AS1 (Level 3) as BUSINESS. This is useful when you already have the ASN from your logs or your CDN and just want its classification, or when you're building a static allowlist of, say, every ASN a partner operates. When you look up by asn, the response drops the top-level ip field, since there's no single address to report.

A classifier you can copy

Here's the logic wrapped so it returns a bucket and never throws on a bad response.

import os
import requests

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")

# ASN type values that mean "an organization runs this," not a home user
# and not a rented server. Collapse them if your logic doesn't need the split.
ORG_TYPES = {"BUSINESS", "EDUCATION", "GOVERNMENT"}


def classify_ip(ip):
    """Return 'hosting', 'consumer', 'organization', or 'unknown' for an IP.

    Never raises on a network or parse error; callers get 'unknown' and can
    decide their own fallback (fail-open vs fail-closed) from there.
    """
    try:
        resp = requests.get(
            "https://api.ipgeolocation.io/v3/asn",
            params={"apiKey": IPGEO_API_KEY, "ip": ip},
            # Short timeouts: a classification call should never hang a request path.
            timeout=(1.0, 1.5),
        )
        resp.raise_for_status()
    except requests.RequestException as exc:
        # Log and fall back. Don't let an IP lookup take down the caller.
        print(f"ASN lookup failed for {ip}: {exc}")
        return "unknown"

    # .get() the whole way down: any field can be absent or empty.
    try:
        data = resp.json()
    except ValueError as exc:
        print(f"Invalid ASN response for {ip}: {exc}")
        return "unknown"

    asn_type = (data.get("asn") or {}).get("type") or ""

    if asn_type == "HOSTING":
        return "hosting"
    if asn_type == "ISP":
        return "consumer"
    if asn_type in ORG_TYPES:
        return "organization"
    return "unknown"  # empty type, unrecognized value, or bogon range


if __name__ == "__main__":
    for ip in ("49.12.0.0", "8.8.8.8", "91.128.103.196"):
        print(ip, "->", classify_ip(ip))

Two decisions worth calling out. The timeout is deliberately tight because an ASN lookup usually sits on a request path (a signup, a login, a checkout), and a slow classifier is worse than no classifier. And an empty or unrecognized type returns unknown rather than a guess, so your downstream rules can treat "we don't know" differently from "we know it's a home user."

The same shape in JavaScript, using fetch with an abort timeout:

const IPGEO_API_KEY = process.env.IPGEO_API_KEY;

// Organization ASN types, kept separate from hosting and consumer.
const ORG_TYPES = new Set(["BUSINESS", "EDUCATION", "GOVERNMENT"]);

async function classifyIp(ip) {
  const url =
    `https://api.ipgeolocation.io/v3/asn` +
    `?apiKey=${IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}`;

  try {
    const resp = await fetch(url, {
      // Abort before this ever stalls a login or checkout flow.
      signal: AbortSignal.timeout(1500),
    });
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);

    const data = await resp.json();
    // Optional chaining the whole way: asn or type may be missing.
    const asnType = data?.asn?.type ?? "";

    if (asnType === "HOSTING") return "hosting";
    if (asnType === "ISP") return "consumer";
    if (ORG_TYPES.has(asnType)) return "organization";
    return "unknown";
  } catch (err) {
    // Network error, timeout, or bad JSON: fall back, don't throw.
    console.error(`ASN lookup failed for ${ip}: ${err.message}`);
    return "unknown";
  }
}

Both return one of four strings. What you do with them is your policy, not the classifier's job: most teams pass consumer, add friction to hosting, and treat organization as low-risk-but-log. The point is that the branching lives in one place, keyed on one field.

One operational note: If your logs or edge provider already give you the ASN, cache classification by AS number. If all you have is an IP, you still need an IP-to-ASN mapping first, so in a higher-volume implementation cache both the IP/prefix-to-ASN mapping and the ASN-to-type classification.

When ASN type is not enough

The matrix handles the large majority of addresses. Then there are four cases where reading type alone can give you an incomplete or misleading answer. These are the parts most guides skip, and they're the reason the classification isn't a one-liner.

Subleased cloud: the operator is hosting, the tenant is a business

This is the important one. A company rents servers or address space from a cloud provider and runs its own service on it. The ASN belongs to the hosting company, so asn.type reads HOSTING, but the actual occupant is a business. If you classify on ASN type alone, you file a legitimate company under "datacenter" and treat its traffic as suspect.

This is exactly why the company object in the main geolocation response is worth pulling alongside the ASN. The company object can identify a more specific organization associated with the IP range than the ASN operator, and it carries its own type. Look at 2.56.188.34:

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

{
  "asn": {
    "as_number": "AS62240",
    "organization": "Clouvider Limited",
    "type": "HOSTING",
    "domain": "clouvider.net"
  },
  "company": {
    "name": "Packethub S.A.",
    "type": "BUSINESS",
    "domain": "packethub.com"
  }
}

The ASN registrant is Clouvider, a hosting provider, tagged HOSTING. The company mapped to this address is Packethub, tagged BUSINESS. Same IP, two different answers, and the company result gives you more specific context for "who is associated with this IP". When company.type and asn.type differ, the company field can give you useful context about who is associated with that particular address range, while the ASN still tells you about the underlying network. Reading both, and knowing which to trust when they split, is the difference between a classifier that works on cloud-hosted businesses and one that flags every startup running on a VPS.

Corporate VPN: hosting-looking, entirely legitimate

An employee connecting through their company's VPN often egresses from a datacenter or a business ASN, not from their home ISP. The ASN type will say HOSTING or BUSINESS, and both are technically correct: the traffic really is leaving a server. But the human behind it is a legitimate employee, not a bot. If your rules hard-block hosting IPs, you've just locked out everyone on the corporate VPN. Weight the ASN type against account history and behavior rather than blocking on it outright.

Residential proxy: the one that reads consumer and isn't

Here is the case that runs opposite to the subleased-cloud one. A residential proxy routes traffic through a real home connection, so the exit IP sits on a consumer ISP and asn.type reads ISP. Everything about the network says "home user." But the traffic is being relayed on behalf of someone else, often a scraper or a fraud operation renting access to that household's connection. ASN type cannot see this, because at the network layer it genuinely is a consumer ISP. Catching it needs a dedicated signal: if you also run the security module, the is_residential_proxy flag is what flips an ISP-typed address from "trust" to "inspect." Without that flag, a residential proxy is invisible to ASN-type classification, which is worth knowing before you lean on the consumer bucket for anything security-sensitive.

CDN and anycast: the ASN bucket needs more context

Some addresses aren't a datacenter, a business, or a home. They're anycast IPs announced from many locations at once, fronting a CDN or a large platform. Akamai, Cloudflare, and the big content networks fall here. The ASN type may say HOSTING or BUSINESS, but treating the address as either misses that it's infrastructure serving content, not an origin you can reason about as a single user or server.

Treat is_anycast as an additional flag, not another ASN bucket. The ASN type can still describe the operator, but an anycast IP should not be interpreted as one physical server or one geographic origin because the same address may be served from multiple locations.

Corroborating with ASN topology

The ASN endpoint returns more than a label. Pass include=peers,downstreams,upstreams,routes,whois_response and you get the network's routing shape, which is a useful sanity check when a type value surprises you.

curl -X GET 'https://api.ipgeolocation.io/v3/asn?apiKey=API_KEY&asn=12&include=upstreams,downstreams,routes'

For AS12 (NYU, EDUCATION) the response includes its announced routes, its upstreams (transit providers like GTT and Zayo), and its downstreams (customer networks like NYU Langone Health). The signals that corroborate a type:

Downstreams. An ASN with customer networks hanging off it is transit or a large operator, not a home connection.
Upstreams. Who an ASN buys connectivity from tells you where it sits in the hierarchy.

You don't need this for routine classification, and pulling it on every request is wasteful. It earns its place when you're building the allowlist, auditing a surprising result, or investigating a specific ASN by hand. The raw whois_response is there too, but treat it as a last resort: it's an unstructured text blob meant for human reading, not something to parse in code. For routine classification, the structured fields are easier to work with. Keep whois_response for deeper registration details or manual investigation.

A few extra notes that don't need their own sections. IPv6 uses the same workflow: resolve the IPv6 address to its origin ASN, then classify that ASN in the same way. Bogon and private ranges have no public ASN, so a lookup on 10.0.0.0 or a documentation range returns an error rather than a type, which is why the classifier treats anything without a clean type as unknown. And the ASN type is stable over days and weeks, not seconds, so caching aggressively by AS number is safe.

Where this leaves you

Classification by ASN type is one field and one lookup for the common case, and a second field, company.type, for the case where a business runs on rented infrastructure. Wire the classifier onto the paths where the answer changes what you do, signup, login, checkout, and cache by AS number when you already have the ASN, or cache both IP-to-ASN and ASN-to-type mappings at higher volume. Keep the four edge cases in mind before you turn a bucket into a hard block: a hosting label can be a corporate VPN, a consumer label can be a residential proxy, and an anycast address isn't really any of the three. The type tells you what the network is. What you do with that is your call to make, and it should almost always be scoring, not blocking.

Turn a List of IPs Into Location Data in Google Sheets

ABDULLAH AFZAL — Wed, 12 Aug 2026 11:15:16 +0000

You have a Google Sheets file full of IP addresses. Maybe they came from server access logs, a list of login attempts, ad-click exports, or a fraud review queue. You need to know where those IPs are, what network they belong to, and whether any of them are running through a VPN or proxy.

You could paste them into an online lookup tool one by one. Or you could turn your Google Sheet into a geo-enrichment pipeline that resolves hundreds of IPs with a formula.

This guide covers the setup (about 10 minutes of copy-paste), a formula reference you can bookmark, and four practical workflows for doing something useful with the enriched data.

TL;DR

One Apps Script integration turns Google Sheets into a bulk IP enrichment tool. No add-ons, no code to write.
Formulas like =IPGEO(A2, "location.country_name") fill in country, city, timezone, currency, ASN, VPN status, proxy detection, and threat scores.
=IPGEO_BULK(A2:A500, "location.country_name") processes large lists in a single call instead of one formula per row.
All you need is a free API key. Sign up, paste the key once, and the formulas work immediately.
The full formula reference and source code live at the GitHub repository.

The short version: paste IPs in column A, use formulas in columns B onward, and the sheet fills itself with location and security data. The rest of this guide explains which formulas to use, when, and what to do with the output.

To geolocate IP addresses in Google Sheets, add the IPGeolocation Apps Script integration, store your API key once, and use custom formulas such as IPGEO for individual lookups or IPGEO_BULK for an IP range.

How to set it up

Several IP geolocation APIs work with Google Sheets through Apps Script. IPGeolocation, ipinfo, ip-api, and MaxMind GeoIP2 all return similar core data for country-level lookups. This guide uses IPGeolocation because it ships a ready-made Google Sheets integration with built-in formulas, bulk processing, and security signals, so you skip the Apps Script plumbing entirely.

The setup takes about 10 minutes:

Open your Google Sheet. Go to Extensions > Apps Script.
In the Apps Script editor, delete the starter code in Code.gs. Paste the full contents of Code.gs from the GitHub repository.
Save the project. Name it something like "IPGeolocation.io for Google Sheets."
In the function dropdown near the toolbar, select setIpGeolocationApiKey and click Run. Google will ask you to approve permissions (this is normal). A popup will ask for your API key. Paste it and click OK.
Go back to your spreadsheet tab and refresh the page. You should see a new IPGeolocation.io menu at the top. Sign up for a free API key if you don't have one. The key connects the sheet to the service and you only set it once per spreadsheet.

Test it by typing this in any empty cell:

=IPGEO("8.8.8.8", "location.country_name")

If it returns "United States," you're set.

Tip: If the IPGeolocation.io menu doesn't appear after refreshing, open Apps Script again and confirm the code saved correctly. A second refresh usually fixes it.

IP enrichment formulas

This is the table to bookmark. Every formula takes an IP address (or a cell reference like A2) as the first argument, a field path as the second, and optionally "security" as the third for security-related fields.

Location and network

What you need	Formula	Example output
Country name	`=IPGEO(A2, "location.country_name")`	Germany
Country code (2-letter)	`=IPGEO(A2, "location.country_code2")`	DE
City	`=IPGEO(A2, "location.city")`	Berlin
State or province	`=IPGEO(A2, "location.state_prov")`	Berlin
Latitude	`=IPGEO(A2, "location.latitude")`	52.5200
Longitude	`=IPGEO(A2, "location.longitude")`	13.4050
Timezone	`=IPGEO(A2, "time_zone.name")`	Europe/Berlin
Currency code	`=IPGEO(A2, "currency.code")`	EUR
ASN number	`=IPGEO(A2, "asn.as_number")`	AS13335
ASN organization	`=IPGEO(A2, "asn.organization")`	Cloudflare, Inc.

Security signals

What you need	Formula	Example output
VPN detected	`=IPGEO(A2, "security.is_vpn", "security")`	TRUE
Proxy detected	`=IPGEO(A2, "security.is_proxy", "security")`	FALSE
Tor exit node	`=IPGEO(A2, "security.is_tor", "security")`	FALSE
Bot detected	`=IPGEO(A2, "security.is_bot", "security")`	FALSE
Cloud provider	`=IPGEO(A2, "security.is_cloud_provider", "security")`	TRUE
Threat score (0-100)	`=IPGEO(A2, "security.threat_score", "security")`	72

Security formulas need that third "security" parameter. Without it, they return blank. There's also a dedicated =IPSECURITY(A2, "security.threat_score") formula that calls the security endpoint directly.

Shortcuts and bulk

Formula	What it does
`=IPGEO_COUNTRY(A2)`	Returns country name (shortcut)
`=IPGEO_CITY(A2)`	Returns city name (shortcut)
`=IPGEO_TIMEZONE(A2)`	Returns timezone name (shortcut)
`=IPGEO_ASN_ORG(A2)`	Returns ASN organization (shortcut)
`=IPGEO_IS_VPN(A2)`	Returns VPN detection (shortcut)
`=IPGEO_THREAT_SCORE(A2)`	Returns threat score (shortcut)
`=IPGEO_BULK(A2:A500, "location.country_name")`	Fills an entire column from a range
`=IPGEO_JSON(A2)`	Returns the raw JSON response (debugging)

IPGEO_BULK is the one to reach for when you have more than a few dozen IPs. Instead of dragging a formula down 500 rows (which fires 500 individual API calls), it processes the whole range in a single batch. Faster, fewer API calls, and the sheet stays responsive.

Note: Keep bulk ranges contiguous. IPGEO_BULK skips empty cells, so remove blank rows from the input range before running a bulk lookup to keep results aligned with the original IPs.

Four workflows that make the data useful

Looking up location data is the starting point. The value comes from what you do with it after the columns fill in.

Fraud and login review

Export login IPs from your auth system, paste them into column A, and bulk-enrich with country, city, VPN status, proxy status, and threat score. Then put conditional formatting to work:

Color-scale the threat score column. Green for 0-19, yellow for 20-59, red for 60-100. Suspicious rows stand out immediately without reading a single cell.
Filter by VPN. Show only TRUE rows. These are logins happening through VPN connections, which might be normal for remote employees or worth investigating for consumer accounts.
Cross-check country against expected geography. If your users are mostly in the US and Germany, a cluster of logins from a country you don't serve is worth a second look.

Marketing campaign analysis

If you capture IP addresses alongside campaign clicks or conversions, enrich them to answer questions your analytics dashboard can't:

Country and city breakdown that doesn't depend on the user's browser locale settings. IP-level country data is independent of what the user tells your form.
Bot and cloud-provider signals: A concentration of clicks from cloud infrastructure is worth investigating, especially when it overlaps with bot, proxy, known-attacker, or elevated threat signals. A cloud-provider flag by itself is context, not proof of fraudulent traffic.
Timezone grouping for scheduling. Pivot the enriched data by timezone to see when your actual audience is active, not when your analytics platform thinks they are. For a campaign with 2,000 clicks, =IPGEO_BULK(A2:A2001, "location.country_name") fills the country column in one call. Add a pivot table grouped by country, and you have a geographic distribution in under a minute.

Server log enrichment

Nginx and Apache access logs give you IP addresses, timestamps, URLs, and status codes. What they don't give you is who those IPs belong to.

Paste the IP column into a sheet. Enrich it with asn.organization and location.country_name, then pivot by ASN organization. A large share of requests may come from a relatively small set of networks. Some may be consumer ISPs, some cloud or hosting providers, some CDN infrastructure, and some networks you already recognize.

If an ASN you don't recognize is hammering a specific endpoint, that's a pattern worth investigating before it becomes an incident.

The sheet doesn't replace your monitoring stack, but it gives operations and security teams a quick way to triage access patterns without writing queries against a log aggregator. When someone asks "where is this traffic coming from," a pivot table by ASN answers it in a way that a raw IP list never will.

Compliance and access auditing

For teams with geographic access policies (data residency requirements, export controls, regional licensing), IP enrichment turns an access log into a compliance report.

The workflow: pull login records for a review period, enrich with country, and filter for logins originating outside your approved country list. If your policy says "US and EU only" and you see logins from a country not on that list, that's a finding that needs documentation. Adding the VPN column helps contextualize findings: a login from an unexpected country through a VPN has a different risk profile than one from a residential ISP in that same country.

This isn't a substitute for proper access controls. But when the auditor asks "were there any access events from outside approved regions during Q2," this is how you answer the question in 15 minutes instead of filing a ticket with engineering.

Handling larger datasets

Individual IPGEO formulas work fine for a few dozen rows. Beyond that, switch to IPGEO_BULK:

=IPGEO_BULK(A2:A1000, "location.country_name")

This processes the range as a single batch. The underlying API accepts up to 50,000 IPs per request, although practical Google Sheets batch sizes can be lower because Apps Script has its own execution and caching limits.

A few things to know about scale:

Caching. Results are cached for six hours inside Google Sheets using Apps Script's built-in cache service. If you look up the same IP twice within that window, the second call doesn't cost an API request.

Free tier quota. The free plan gives you 1,000 requests per day across all APIs. Bogon IPs (private ranges like 10.x.x.x, 192.168.x.x) don't count against quota, so dirty lists with internal IPs won't burn through your allowance.

Sheet performance. Google Sheets has its own execution limits for custom functions. If the sheet feels sluggish, switching from individual formulas to IPGEO_BULK is the single biggest performance improvement. The README's troubleshooting section covers other common slowdown causes.

What to watch out for

IP geolocation is approximate. Across IPGeolocation's dataset, country-level accuracy is 99%+, region/state is 90%+, and city-level is 85%+. City results should still be treated as estimates rather than exact positions, especially on mobile networks, VPNs, proxies, and networks where traffic exits far from the user.

VPN and proxy detection has false positives. A corporate VPN exit in another country looks identical to a privacy VPN from the network's perspective. Context matters. If your entire user base is enterprise employees, VPN flags will be noisy. Use threat_score thresholds rather than binary VPN flags for decision-making.

Google Sheets isn't a production system. This pipeline works well for periodic batch analysis, ad-hoc investigations, and generating reports. It's not a replacement for real-time API integration in your application code. For production use (per-request enrichment, middleware, real-time blocking), call the API from your backend.

The full formula reference and source code live at the GitHub repository, including a suggested five-tab template layout and additional troubleshooting. If a formula returns blank, the JSON dump formula (=IPGEO_JSON(A2)) shows the raw API response so you can check whether a field exists for that IP.

What's next

Drop the script into a sheet, paste your IPs, and run a bulk enrichment. Most people start with the location formulas and add security columns once they see how fast it fills in.

Automate IP Abuse Reports Into Your Ticket Queue

ABDULLAH AFZAL — Tue, 11 Aug 2026 11:35:45 +0000

Automating abuse reports for attacking IPs starts with a step most incident-response scripts skip: finding the network operator responsible for the address. Blocking the IP stops traffic from that address, but a well-evidenced report gives the operator a chance to investigate the system behind it and take action.

Doing that manually means looking up registration data, finding the right abuse contact, collecting timestamps and logs, and copying everything into a ticket or email. At any meaningful volume, that process gets skipped.

This guide builds a small pipeline to handle the repetitive parts: resolve the abuse contact for an offending IP, group repeated events by the abuse-handling network, and create a ticket with the contact details and evidence ready for human review. The raw lookup starts with curl, the complete workflow is implemented in Python, and the resolver is also shown in Node.js.

TL;DR

Blocking an abusive IP stops it hitting you. Reporting it gives the responsible network operator the evidence needed to investigate the source and take action.
The abuse contact is the operator's registered abuse desk from registry records, not the attacker. One call resolves it: GET /v3/abuse?ip=....
The response returns emails and phone_numbers as arrays, plus the operator's name, organization, route (the CIDR they answer for), country, and postal address.
Dedupe on route, not just the individual IP. Multiple abusive IPs can resolve to the same operator and abuse-handling network, so grouping them prevents your queue from filling with near-identical tickets.
Open a ticket for a human to review and send. Never auto-email abuse desks: log triggers include spoofed sources, and machine-gunning operators burns your sender reputation.
Fail open. A lookup or ticket failure should log and move on, never block your request path.

The pipeline is three steps: resolve the abuse contact for the offending IP, dedupe by the network route so one attacker isn't hundreds of tickets, and open a ticket with the contact and evidence attached. The code below is production-shaped, not a happy-path snippet.

Abuse reputation vs operator reporting: two different jobs

People conflate two actions that do different things.

The first is reporting the IP to a community blocklist like AbuseIPDB, usually wired through Fail2Ban. That raises the IP's reputation score so other people's firewalls treat it with suspicion. Useful, but it does nothing to the source. The attacker keeps their box.

The second is telling the operator that owns the IP range. IP address allocations are registered through one of the five Regional Internet Registries (ARIN, RIPE, APNIC, LACNIC, AFRINIC), and registry records commonly include an abuse or incident-response contact for the responsible operator. That contact is a role mailbox, abuse@ by convention, defined back in RFC 2142 as the address for "inappropriate public behaviour." Send evidence there and the operator can investigate, warn, or suspend the customer running the attack.

One point the registries make and worth repeating: the abuse contact is the network operator, not the abuser. You are asking the landlord to deal with the tenant. This tutorial automates the second job. The first is a one-liner you probably already have.

What one lookup returns

You can resolve the contact from raw WHOIS or RDAP yourself, and if you enjoy parsing free-text remarks: fields across five registries with different formats, go for it.

A lookup API flattens that into consistent JSON. IPGeolocation, IPinfo, and IPLocate all expose one; ip-api does not. I'll use IPGeolocation's dedicated endpoint here because it returns the parsed abuse object in a single call and normalizes the registry differences.

Grab a key and the raw call is one line:

curl -s -X GET \
  'https://api.ipgeolocation.io/v3/abuse?apiKey=API_KEY&ip=49.12.0.0'

For 49.12.0.0, an address in a Hetzner allocation, the response is:

{
  "ip": "49.12.0.0",
  "abuse": {
    "route": "49.12.0.0/20",
    "country": "DE",
    "name": "Hetzner Online GmbH - Contact Role",
    "organization": "ORG-HOA1-RIPE",
    "kind": "group",
    "address": "Hetzner Online GmbH\nIndustriestrasse 25\nD-91710 Gunzenhausen\nGermany",
    "emails": [
      "abuse@hetzner.com"
    ],
    "phone_numbers": [
      "+49 9831 505-3",
      " +49 9831 505-0"
    ]
  }
}

Eight fields, and each one matters when you build the ticket. route is the CIDR the desk answers for, which is your dedupe key. emails and phone_numbers are arrays, so code that assumes a string will break. kind is group or individual. organization can be an empty string on some ranges. And look at the second phone number: " +49 9831 505-0" has a stray leading space, and the address carries literal \n line breaks. Registry data is messy. Your code cleans it, or your tickets look broken.

Step 1: Resolve the abuse contact

Here's the resolver in Python. It fails open on purpose, returning None for anything it can't handle. Keep abuse reporting completely outside your application's request path. Run it from a worker, queue consumer, or detector action so an API, Redis, or ticketing outage cannot affect user traffic.

import os
import logging
import requests  # pip install requests

log = logging.getLogger("abuse_pipeline")

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")
ABUSE_URL = "https://api.ipgeolocation.io/v3/abuse"

def resolve_abuse_contact(ip):
    """Resolve the operator's abuse contact for `ip`, or None if it can't be
    resolved. Fails open: reporting is a background task and must never block
    the caller's request path."""
    if not IPGEO_API_KEY:
        log.error("IPGEO_API_KEY is not set")
        return None
    try:
        # (connect 1s, read 1.5s). Reporting isn't latency-critical, but you
        # still don't want a hung socket per detected event.
        resp = requests.get(
            ABUSE_URL,
            params={"apiKey": IPGEO_API_KEY, "ip": ip},
            timeout=(1.0, 1.5),
        )
    except requests.RequestException as exc:
        log.warning("Abuse lookup failed for %s: %s", ip, exc)
        return None

    if resp.status_code == 423:
        # Bogon or private IP. Nothing to report, and your detector probably
        # shouldn't have flagged an RFC 1918 address in the first place.
        log.info("Skipping bogon/private IP %s", ip)
        return None
    if resp.status_code == 401:
        log.error("Abuse endpoint returned 401; check the API key.")
        return None
    if resp.status_code == 429:
        log.warning("Rate limited on abuse lookups; back off and retry later")
        return None
    if resp.status_code != 200:
        log.warning("Abuse lookup for %s returned HTTP %s", ip, resp.status_code)
        return None

    try:
        payload = resp.json()
    except ValueError as exc:
        log.warning("Invalid JSON from abuse lookup for %s: %s", ip, exc)
        return None

    abuse = (payload or {}).get("abuse") or {}
    emails = abuse.get("emails") or []
    if not emails:
        # No registered abuse address. Rare, but real on some ranges.
        log.info("No abuse email for %s (%s)", ip, abuse.get("route"))
        return None

    return {
        "route": abuse.get("route"),
        "country": abuse.get("country"),
        "org": abuse.get("organization") or abuse.get("name") or "unknown operator",
        "emails": emails,
        "phones": [p.strip() for p in (abuse.get("phone_numbers") or [])],
        "address": (abuse.get("address") or "").replace("\n", ", "),
    }

The status-code handling isn't padding. 423 is a bogon or private IP, 401 is a free key hitting a paid endpoint, 429 is your rate limit. Each one is a different decision, and collapsing them into a bare except hides the one you actually need to act on. The .strip() on phones and the newline replace on the address are there because of the exact mess you saw in the payload above.

The same thing in Node. Node 18+ has global fetch, so no dependency:

const IPGEO_API_KEY = process.env.IPGEO_API_KEY;
const ABUSE_URL = "https://api.ipgeolocation.io/v3/abuse";

async function resolveAbuseContact(ip) {
  // Fails open: returns null on any problem so the caller keeps running.
  if (!IPGEO_API_KEY) {
    console.error("IPGEO_API_KEY is not set");
    return null;
  }

  const url = `${ABUSE_URL}?apiKey=${IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}`;

  let resp;
  try {
    // Abort after 1.5s so a slow lookup never wedges the event loop.
    resp = await fetch(url, { signal: AbortSignal.timeout(1500) });
  } catch (err) {
    console.warn(`Abuse lookup failed for ${ip}: ${err.message}`);
    return null;
  }

  if (resp.status === 423) return null; // bogon / private IP
  if (resp.status === 401) {
    console.error("Abuse endpoint returned 401; check the API key.");
    return null;
  }
  if (resp.status === 429) {
    console.warn("Rate limited on abuse lookups; back off and retry later");
    return null;
  }
  if (!resp.ok) {
    console.warn(`Abuse lookup for ${ip} returned HTTP ${resp.status}`);
    return null;
  }

  let payload;
  try {
      payload = await resp.json();
  } catch (err) {
      console.warn(`Invalid JSON from abuse lookup for ${ip}: ${err.message}`);
      return null;
  }

  const abuse = payload?.abuse ?? {};
  const emails = abuse.emails ?? [];
  if (emails.length === 0) return null; // no registered abuse desk

  return {
    route: abuse.route,
    country: abuse.country,
    org: abuse.organization || abuse.name || "unknown operator",
    emails,
    phones: (abuse.phone_numbers ?? []).map((p) => p.trim()),
    address: (abuse.address ?? "").replace(/\n/g, ", "),
  };
}

Both return a small normalized object or nothing. Everything downstream can trust the shape.

Step 2: Dedupe by route, not by IP

This is the step every other guide misses, and it's the one that decides whether your queue stays usable.

A single attacker sitting on a hosting provider rarely stays on one IP. They rotate across the block. If you dedupe on the IP, a scanner walking 49.12.0.5, 49.12.0.6, 49.12.0.7 opens a fresh ticket every hop, all pointing at the same Hetzner abuse desk. The desk gets 200 near-identical emails, ignores all of them, and your queue is noise.

Dedupe on route instead. The abuse contact answers for the whole CIDR, so one ticket per route per window is the right resolution. Redis makes it atomic:

import redis  # pip install redis

rdb = redis.Redis(host="localhost", port=6379, db=0)

def claim_route(route, ttl_seconds=86400):
    """True the first time a route is seen in the TTL window, False after.
    SET NX is atomic, so two workers racing the same route still open one
    ticket, not two."""
    if not route:
        return False
    try:
        return bool(rdb.set(f"abuse:route:{route}", "1", nx=True, ex=ttl_seconds))
    except redis.RedisError as exc:
        # Dedupe store is down. Allow the ticket rather than silently dropping
        # reports; a rare duplicate beats a missed abuse report.
        log.warning("Dedupe unavailable (%s); allowing ticket for %s", exc, route)
        return True

A one-day window is a reasonable default. A persistent attacker is worth one ticket a day, not one a minute. If you're single-process and don't want Redis, a dict of route -> expiry works, but you lose atomicity the moment you scale past one worker.

Step 3: Open the ticket

Now the resolved contact becomes a ticket. Here's a generic create_ticket() with Jira Cloud as the concrete target. The same normalized contact and evidence can be sent to Zendesk, ServiceNow, Linear, or another tracker, but each system has its own endpoint, authentication model, and ticket fields. Jira Cloud is the concrete example below.

import os
import requests

JIRA_BASE = os.environ.get("JIRA_BASE_URL")       # https://you.atlassian.net
JIRA_EMAIL = os.environ.get("JIRA_EMAIL")
JIRA_TOKEN = os.environ.get("JIRA_API_TOKEN")     # id.atlassian.com API token
JIRA_PROJECT = os.environ.get("JIRA_PROJECT_KEY", "SEC")

def create_ticket(summary, body):
    """Create a ticket for a human to review before anything reaches the
    operator. Jira Cloud here; other trackers differ only in fields and auth."""
    if not (JIRA_BASE and JIRA_EMAIL and JIRA_TOKEN):
        log.error("Jira credentials are not fully configured")
        return None
    payload = {
        "fields": {
            "project": {"key": JIRA_PROJECT},
            "summary": summary[:255],              # Jira caps summaries at 255
            "issuetype": {"name": "Task"},
            "description": {
                "type": "doc", "version": 1,
                "content": [{
                    "type": "paragraph",
                    "content": [{"type": "text", "text": body}],
                }],
            },
        }
    }
    try:
        resp = requests.post(
            f"{JIRA_BASE}/rest/api/3/issue",
            auth=(JIRA_EMAIL, JIRA_TOKEN),
            json=payload,
            timeout=(1.0, 3.0),
        )
        resp.raise_for_status()
    except requests.RequestException as exc:
        log.error("Ticket creation failed: %s", exc)
        return None
    return resp.json().get("key")                  # e.g. "SEC-1421"

The API token lives in an env var, never in the file. The [:255] truncation is a real Jira limit that will 400 your request if you ignore it. Everything is wrapped, because a tracker outage should log and drop the report, not crash the process handling your attack traffic.

The glue ties the three steps together:

from datetime import datetime, timezone

def report_abusive_ip(ip, reason, log_excerpt):
    contact = resolve_abuse_contact(ip)
    if not contact:
        return  # failed open, already logged

    if not claim_route(contact["route"]):
        log.info("Already ticketed %s today; skipping %s",
                 contact["route"], ip)
        return

    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%SZ")
    summary = f"Abuse report: {ip} ({contact['route']}) via {contact['org']}"
    body = (
        f"Offending IP: {ip}\n"
        f"Network: {contact['route']} ({contact['org']}, {contact['country']})\n"
        f"Reason: {reason}\n"
        f"Detected at (UTC): {ts}\n\n"
        f"Send report to: {', '.join(contact['emails'])}\n"
        f"Phone (incident only): {', '.join(contact['phones']) or 'none registered'}\n"
        f"Postal: {contact['address'] or 'n/a'}\n\n"
        f"Evidence:\n{log_excerpt}"
    )
    key = create_ticket(summary, body)
    if key:
        log.info("Opened %s for %s", key, ip)

The ticket carries what an abuse desk needs to act: the offending IP, the network, a reason, a UTC timestamp, and the log excerpt as evidence. It also carries the resolved emails so whoever picks up the ticket sends to the right desk without re-doing the lookup. UTC matters; a report timestamped in your local zone forces the operator to guess, and abuse desks that get vague reports close them.

Wiring it to a trigger

The pipeline needs an offending IP from somewhere. Your detection layer already produces them: Fail2Ban jails, a rate-limit rule, a WAF event, an SSH log parser. The cleanest hook is a small entrypoint your detector calls:

import sys

if __name__ == "__main__":
    # Fail2Ban action example:
    #   actionban = /usr/bin/python3 /opt/abuse/report.py <ip> "ssh brute force"
    if len(sys.argv) < 2:
        sys.exit("usage: report.py <ip> [reason]")
    offending_ip = sys.argv[1]
    reason = sys.argv[2] if len(sys.argv) > 2 else "automated detection"
    report_abusive_ip(offending_ip, reason, log_excerpt="see host logs")

One caveat that will bite you if you pull the IP from a web request instead of a firewall log: make sure it's the real source. Behind a proxy or load balancer, the socket address is the proxy, and X-Forwarded-For is caller-controlled and trivially spoofed. Report the wrong hop and you're emailing an innocent operator. Only trust X-Forwarded-For from proxies you actually run, and take the right entry, not the first thing an attacker put there.

The one thing not to automate

Resolve, dedupe, ticket. Do not add a fourth step that emails the abuse desk automatically. I'd argue this is the line, and it's worth being blunt about.

Detection triggers fire on spoofed and forged sources all the time. A NANOG thread on exactly this problem put it plainly years ago: the hard part of automated reporting was "dealing with spoofed sources," traffic that looks hostile but didn't come from where it claims. Wire an auto-emailer to a raw log trigger and you will send reports about IPs that never touched you, to desks that will start filtering your domain. Once abuse@ stops reading your mail, your real reports go nowhere.

A ticket puts a human in the loop for ten seconds: glance at the evidence, confirm it's real, send. That's the difference between a report an operator acts on and a report that gets your sender reputation torched. The automation should do the tedious part, the lookup and the routing, and stop at the judgment call.

When you outgrow the API

Per-request lookups are right until they aren't. If you're processing millions of events and calling the endpoint on each one, you're paying a credit and a round trip per event (the X-Credits-Charged response header tells you the exact cost). At that volume, the downloadable abuse contact database is the move: match the IP against a local copy refreshed daily, no network call in the hot path. Same data, sourced from all five RIRs, without the per-lookup cost.

And read the operator's terms before you scale up reporting. A polite, evidenced, deduplicated report is welcome. A firehose is abuse of the abuse desk, which is a special kind of irony you don't want to be responsible for.

The ASN Pivot Playbook: Routes, Upstreams, Downstreams

ABDULLAH AFZAL — Sun, 09 Aug 2026 10:53:38 +0000

An ASN pivot is the cheapest move in an IP investigation and the easiest one to over-read. One call turns a single address into a network, a list of announced prefixes, a transit chain, and a set of customer networks. None of that tells you who owns anything.

That gap is the whole problem. The data is easy to get and hard to weigh, so investigations into C2 infrastructure either ignore it or lean on it far past what it supports. This is the version I'd hand a new analyst: five pivots, in the order I'd run them, each with the false positive it hands you.

TL;DR

An ASN pivot maps one IP to the network announcing it, then walks outward through announced routes, downstream customers, upstream transit, and WHOIS.
downstreams and routes carry most of the signal. peers carries the least, and may not mean what the name suggests.
Upstream, downstream, and peer labels are not declared in BGP. They are inferred from observed AS paths, so treat them as a good guess rather than ground truth.
Routing adjacency alone is low-confidence evidence, always. It tells you where to look next, not who did anything.
False positive risk depends almost entirely on the AS type. Shared cloud and residential ISP networks produce near-worthless clustering; small dedicated networks produce useful clustering.
Everything below runs on one paid endpoint call plus local set math, in curl and Python.

The short version: use routing data to generate leads and non-routing evidence to confirm them. An analyst who can say what a pivot does not prove is more useful than one who can run more pivots.

The five pivots, ranked by what they prove

Run them in this order. Each one costs a single lookup, and you can pull all of the data in one request and slice it locally rather than making five calls.

#	Pivot	What you get	What it proves	Confidence
1	IP to origin ASN	AS number, org, type, RIR, allocation date	This address is routed by this network	High
2	ASN to announced routes	Every IPv4 and IPv6 prefix observed as originated by the AS	The address space currently announced with this AS as origin	High
3	ASN to downstreams	Customer networks routing through this AS	The data infers these networks as customers of this AS	Medium
4	ASN to upstreams	Transit providers carrying this AS	Who to escalate to, and how well connected the AS is	Medium
5	ASN to WHOIS	Registrant org, abuse contacts, handles	Who registered the number, which is not always who uses it	Low to medium

Nothing in that table is attribution. Pivot 1 is close to a fact. Everything below it is an inference with a shrinking amount of evidence behind it, which is why the order matters more than the coverage.

What upstreams, downstreams, and peers actually mean

Three relationships between autonomous systems, and the money decides which is which.

Upstreams are transit providers. You pay them, they carry your traffic to the rest of the internet and announce your prefixes onward. A network with multiple upstreams is multi-homed, which provides routing redundancy. The number of upstreams alone does not determine whether an AS is a stub.

Downstreams are customers. They route through you to reach everyone else, and you announce their prefixes on their behalf. Networks that provide transit have downstream customers; a stub AS does not provide transit between other ASes.

Peers sit level with you. Two networks exchange traffic directly, usually settlement-free, usually at an internet exchange. In the conventional valley-free routing model, peer-learned routes are generally exported to customers rather than to other peers or providers. A typical path therefore goes up through providers, may cross a peer link, and then goes down through customers. Real-world routing policies can have exceptions, so treat valley-free behavior as a useful model rather than a protocol guarantee.

Here's the part that changes how much you should trust any of it. BGP does not carry a field that says "this neighbour is my provider." The protocol announces reachability, not commercial terms, and the commercial terms are confidential. In datasets that infer AS relationships from observed BGP paths, upstream, downstream, and peer labels are algorithmic classifications rather than declarations carried in BGP itself. CAIDA, whose relationship dataset underpins a large share of this tooling, says as much directly in the paper describing their AS relationship inference algorithm: the business relationships are confidential, and the algorithm infers them from BGP paths.

So the labels are good. They are not ground truth, and an investigation that treats them as ground truth is building on sand.

Why `peers` may already contain your upstreams and downstreams

Worth checking before you write set logic against these arrays.

In the documented full response for AS12, every one of the 8 upstreams and both of the downstreams also appears in the peers array. peers also contains AS286 twice, once with country NL and once with US. On that response, peers behaves as "every adjacency we observed," not "settlement-free peers only."

I could only confirm this on one AS, so treat it as a property to check rather than a rule. Either way the defensive version costs two lines: deduplicate on AS number across the union, and treat the remaining peers entries after subtracting known upstreams and downstreams as peer candidates rather than proven settlement-free peers. Code that assumes the three sets are disjoint will double-count adjacencies and inflate whatever score sits on top.

Pivot 1: IP to origin ASN

Start here, always. An IP on its own is a poor unit of analysis, because bulletproof hosting operators rotate them deliberately. The Australian Cyber Security Centre's advisory on bulletproof hosting describes the technique plainly: these providers frequently change the internet-facing identifiers tied to a customer, including assigned IP addresses and domain names, which makes it harder to link an incident to whoever was using the address at the time. The AS number churns far more slowly than the address does.

curl -sS --max-time 3 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&ip=49.12.0.0"

{
  "ip": "49.12.0.0",
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "country": "DE",
    "type": "HOSTING",
    "domain": "hetzner.com",
    "date_allocated": "2002-06-03",
    "asn_name": "HETZNER-AS",
    "allocation_status": "ASSIGNED",
    "num_of_ipv4_routes": "84",
    "num_of_ipv6_routes": "6",
    "rir": "RIPE"
  }
}

To be explicit, since this is an article about investigations: Hetzner is a legitimate hosting company and appears here because it is a well-documented example of a HOSTING-type AS, not because of anything else. That distinction matters throughout, and the false-positive table later on is mostly about not making that mistake.

Two field quirks that will bite you. as_number carries the AS prefix, so it is a string, not an integer. num_of_ipv4_routes and num_of_ipv6_routes are also strings despite being counts, so cast before comparing. Full field reference is in the ASN API documentation.

import os
import requests

API_KEY = os.environ.get("IPGEO_API_KEY")
BASE_URL = "https://api.ipgeolocation.io/v3/asn"


def resolve_origin(ip_address):
    """Map an IP to the AS announcing it. Returns None on any failure."""
    if not API_KEY:
        raise RuntimeError("IPGEO_API_KEY is not set")

    try:
        resp = requests.get(
            BASE_URL,
            params={"apiKey": API_KEY, "ip": ip_address},
            timeout=(2.0, 5.0),
        )
        # 423 means bogon or private. That is an input problem, not an outage.
        if resp.status_code == 423:
            return None
        resp.raise_for_status()
    except requests.exceptions.RequestException as exc:
        # Enrichment is not a gate. Log and let the caller proceed without it.
        print(f"ASN lookup failed for {ip_address}: {exc}")
        return None

    asn = resp.json().get("asn") or {}
    return {
        "as_number": asn.get("as_number"),
        "organization": asn.get("organization"),
        "type": asn.get("type"),
        "rir": asn.get("rir"),
        # Counts come back as strings. Cast, and survive an empty value.
        "ipv4_routes": int(asn.get("num_of_ipv4_routes") or 0),
    }

That returns None rather than raising, which is a deliberate choice. An ASN lookup is enrichment on a case note, so it should fail open. If you wire this into enforcement, choose fail-open or fail-closed explicitly based on the control's role, your risk tolerance, and your availability requirements.

Pivot 2: ASN to announced routes

The routes array is the address space currently observed as originated by the AS, and it is your enumeration surface. If your one indicator sits in a /24 inside a network announcing 84 prefixes, you now have a defined perimeter to scan, correlate against logs, or check for previously-seen addresses.

curl -sS --max-time 5 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=AS12&include=routes"

The gotcha is small and annoying: IPv4 and IPv6 prefixes arrive mixed in the same array, as plain CIDR strings. Split them before you do anything numeric.

import ipaddress


def split_routes(routes):
    """Separate a mixed v4/v6 prefix list. Skips anything unparseable."""
    v4, v6 = [], []
    for prefix in routes or []:
        try:
            net = ipaddress.ip_network(prefix, strict=False)
        except ValueError:
            continue  # Malformed entry, not worth failing the whole pivot over
        (v4 if net.version == 4 else v6).append(net)
    return v4, v6

One caution before you scan everything you just enumerated. A prefix announced with the AS as origin does not make it interesting, and on a large host the announced space is mostly other people's servers.

Pivot 3: ASN to downstreams

This is the pivot that earns its place, and the one most write-ups skip.

The joint guidance CISA published with the NSA, FBI, DC3 and international partners in November 2025, Bulletproof Defense, makes the structural point: bulletproof hosting (BPH) operators increasingly resell stolen or leased infrastructure from legitimate hosting providers, data centres, ISPs and cloud providers, who may have no idea what they are carrying. If a reseller operates its own ASN and buys transit from another provider, it may appear as that provider's downstream. If it only leases IP addresses or servers inside the provider's network, no separate downstream ASN relationship may exist.

So when your indicator lands in a small or mid-sized AS, the customer list is where the interesting structure lives.

curl -sS --max-time 5 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=25139&include=downstreams"

{
  "asn": {
    "organization": "TVCABO Comunicacoes Multimedia, Lda",
    "country": "MZ",
    "downstreams": [
      { "as_number": "AS328162", "description": "Icolo Ltd", "country": "KE" },
      { "as_number": "AS10798", "description": "The Standard Bank of South Africa Proprietary Limited", "country": "ZA" },
      { "as_number": "AS37477", "description": "Mozabanco", "country": "MZ" },
      { "as_number": "AS329394", "description": "OneCloud LDA", "country": "MZ" }
    ]
  }
}

Read that list the way an investigator should: a regional operator with a bank, a data centre company and a cloud provider as customers is a normal regional operator. Nothing here is suspicious. On a genuinely suspect network the shape is the signal, not any individual name. Many small downstreams registered in quick succession, opaque or recently created organisation names, and customers announcing far more space than the business behind the name would plausibly need.

A downstream relationship suggests a customer-provider relationship based on observed routing data. It does not prove a commercial agreement, common ownership, or shared operation. Plenty of resellers are exactly what they claim to be.

Pivot 4: ASN to upstreams

Upstreams answer two different questions, and it is worth being clear about which one you are asking.

The investigative question is how well connected the network is. A single upstream means the network depends on one inferred transit provider in this dataset. Several upstreams indicate multihoming and routing redundancy, but they do not tell you whether the operator is legitimate or well funded.

The operational question is who to talk to. The ACSC advisory makes the point that upstream providers may be unaware they are carrying downstream criminal infrastructure, and the CISA guidance is addressed largely to those providers. If you are filing an abuse report that has gone nowhere at the hosting layer, the transit provider one hop up is the next escalation, and it is often the one with both the standing and the incentive to act.

curl -sS --max-time 5 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=AS12&include=upstreams"

There is a ceiling on this. Once you climb into tier-1 territory the concept stops being informative, because those networks carry effectively everything and their presence says nothing about any particular customer. When your upstream list is a set of global carriers, you have reached the top of the useful part of the pivot.

Pivot 5: ASN WHOIS, and the registrant trap

include=whois_response returns the raw registry record: registrant organisation, admin and tech handles, abuse contacts, allocation dates.

The trap is in the name of the organization field, and it catches people constantly. That field is the entity registered with the RIR as holding the AS number. It is not necessarily the entity using the address space. Subleasing, resale, acquisitions that never got reflected in the registry, and shell registrations all break the link, and this is precisely the pattern the CISA guidance describes when it talks about resold infrastructure. If you have ever wondered why looking up who owns an IP address gives you a cloud provider's name when the actual tenant is a startup you have never heard of, this is why.

Useful things in the record anyway: the abuse handle and email for reporting, RegDate and Updated for age, the RDAP references, and the maintainer objects, which occasionally tie several ASNs to one operator more reliably than any routing relationship does. Field names differ by registry, so an ARIN record and a RIPE record will not parse the same way. Recent allocation plus sparse contact detail plus a large customer list is a shape worth a second look.

Pull it once, slice it locally

All five pivots come out of one request. The include parameter takes all five datasets and adds no extra credit cost over the single credit the lookup already costs, so making five separate calls is just five times the spend for the same data.

# Continues the module from Pivot 1: requests, API_KEY and BASE_URL are already set.


def fetch_asn_profile(as_number):
    """One call, everything. Returns the asn object or None."""
    try:
        resp = requests.get(
            BASE_URL,
            params={
                "apiKey": API_KEY,
                "asn": as_number,
                "include": "routes,peers,upstreams,downstreams,whois_response",
            },
            timeout=(2.0, 10.0),  # Larger payload, so a longer read timeout
        )
        resp.raise_for_status()
    except requests.exceptions.RequestException as exc:
        print(f"Profile lookup failed for {as_number}: {exc}")
        return None

    return resp.json().get("asn") or {}


def relationship_sets(asn):
    """Dedupe adjacencies and separate unclassified peer candidates."""
    def numbers(key):
        return {n.get("as_number") for n in (asn.get(key) or []) if n.get("as_number")}

    upstreams = numbers("upstreams")
    downstreams = numbers("downstreams")
    peer_candidates = numbers("peers") - upstreams - downstreams

    return {
        "upstreams": upstreams,
        "downstreams": downstreams,
        "peer_candidates": peer_candidates,
        "all_adjacent": upstreams | downstreams | peer_candidates,
    }

Note that a lookup by AS number returns no top-level ip field, since there is no address to echo back. Do not assume it is there.

Cache relatively stable ASN metadata aggressively, but keep a timestamp. Organizations, allocations, and routing data can change. If route accuracy matters to your workflow, refresh routes more frequently than basic ASN metadata or fetch them per case.

What each signal actually proves

The table that should sit next to the pivot table in your head.

Signal	Confidence on its own	What raises it
Same IP observed across related events	Medium to high	Corroborating timing, service, account, or behavioral evidence
Same announced prefix	Medium to high	Matching services, banners, or TLS certificates on both hosts
Same origin ASN, small dedicated network	Medium	Consistent behaviour and timing across the hosts
Same origin ASN, large host or cloud	Very low	Effectively needs independent evidence to mean anything
Downstream relationship	Low to medium	Shared registrant, shared maintainer object, correlated registration dates
Upstream relationship	Very low	Almost nothing. Transit is a commercial arrangement, not an endorsement
Peer relationship	Very low	Same
Shared WHOIS registrant or maintainer	Medium	Corroborating DNS, certificate, or malware-family overlap

The pattern is consistent. Routing data is excellent at generating candidates and poor at confirming them. Certificates, passive DNS, service fingerprints and behavioural timing are what turn a candidate into a finding. Anyone who tells you an upstream relationship implicates a provider is selling something.

False positives by AS type

The type field is the single most useful thing for calibrating how much a shared ASN means. Same data, opposite conclusions.

`type`	What a shared ASN means	What to do
`ISP`	Almost nothing. Residential networks mix real users with compromised devices at scale	Never cluster on ASN alone. Score the host, not the network
`HOSTING`	Depends entirely on size. Meaningless on a large provider, meaningful on a small one	Check the routing footprint and other context first. Route count can help distinguish a broad network from a narrow one, but it is not a reliable measure of organization size by itself.
`BUSINESS`	Potentially useful, but may still contain shared, managed, or resold infrastructure	Confirm the operator and hosting model before clustering
`EDUCATION`	Often shared infrastructure with many unrelated users and systems	Avoid ASN-wide conclusions; investigate the individual host and context
`GOVERNMENT`	Shared organizational infrastructure where ASN-wide attribution is especially risky	Investigate narrowly and use appropriate escalation channels

The num_of_ipv4_routes count is a useful routing-footprint signal, which is the practical reason to bother casting that string. Do not treat it as a direct measure of organization size.

Stop rules

Over-pivoting is how a clean case turns into a pile of loosely related infrastructure nobody can act on. Stop when any of these is true.

You have reached a tier-1 network. Upstream relationships stop carrying information at the top of the transit hierarchy.
The AS type is ISP or a large HOSTING network. the shared-network signal is usually too weak on its own; further expansion just adds noise.
You are two relationship hops out with no corroborating evidence. Adjacency to adjacency is not a chain of evidence.
The candidate set is growing faster than your evidence. If each pivot adds twenty addresses and zero confirmations, the pivot is not working.
You cannot state what the next pivot would change. If the answer does not alter a decision, do not make the call.

Write the stop reason into the case note. The next analyst needs to know you stopped deliberately, not that you ran out of time.

Wiring it into a case note

Attach the routing profile to the indicator, not the case. Store as_number, organization, type, rir and the route counts alongside the address with a timestamp, because routing changes and an undated profile is one you cannot reason about six months later.

Keep the confidence label with the data. A field that records asn_match_confidence: low next to a cluster of addresses is worth more than the cluster, because it stops the next person treating your leads as your findings.

One credit per lookup, cached for a day, is cheap enough that IP enrichment at SIEM ingest is usually the right call rather than looking things up by hand mid-investigation. Just make sure the enrichment step cannot take the pipeline down with it.

Run the two-ASN check on the peers behaviour against your own data before you build scoring on those arrays. And if a pivot gives you a lead you cannot confirm with something outside BGP, write it down as a lead and move on. The discipline is the deliverable here, not the API call.

DEV Community: ABDULLAH AFZAL

Why FastAPI geolocation middleware is the wrong tool

Why FastAPI geolocation middleware is the wrong tool

What a dependency gives you instead

Get the client IP right first

Running it locally

The geolocation dependency

Fail open or fail closed

Adding risk data as a second dependency

Composing them without doubling your calls

Wiring it to routes

Testing, which is where this pays off

One HTTP client for the process

Caching with Redis

When middleware actually is right

A few extra notes

How to Block Cloud-Hosted Signups Without Blocking Real Users

A datacenter IP is a different signal than a VPN

The signal you want: is_cloud_provider

Before you start

Detect a cloud-hosted signup

curl

Node.js

Python

Gate the signup route

Which signal should gate what

The false positives that lock out real users

A few things worth adding

Is Anyone Actually Reading Your Abuse Reports?

Reporting got free, and free things get flooded

Volume is not the same as signal

The strongest case against me

Report less, report better

What you're actually spending

How Do I Route EU Users Data to an EU Region?

TL;DR

What data-residency routing actually is

The decision that determines where the data goes

Detecting an EEA location by IP

Routing the request to an EEA region

Country to region, as a table

Fail open or fail closed

Where IP geolocation stops being enough

A reference checklist

Where to take it next

A Self-Correcting Solar System Baseline From Sunrise/Sunset Data

What sun times can and cannot tell you

The three checks worth building

Gate alerts to the real daylight window

Watch the peak drift off solar noon

Normalize the baseline by day length

Pull the sun data

Build the baseline checker

Where this stops and irradiance begins

Enrich Elasticsearch Logs With GeoIP at Ingest

What the Elasticsearch geoip processor gives you

Step 1: Create the ingest pipeline

Step 2: Map location as geo_point before you index

Step 3: Wire the pipeline to your log stream

Step 4: Put it on a map in Kibana

Private and internal IPs return nothing

Backfilling indices you already have

When GeoLite2 is not enough

Operational notes

How Do You Detect Bogon and Reserved IPs in Code?

TL;DR

The special-use IP handling matrix

IPv4 special-use ranges and how your app should treat each

IPv6 ranges that actually reach applications

Bogon, martian, reserved: the distinction developers get wrong

Why your geolocation lookup returns 423 on these IPs

Detecting special-use IPs in code

Node.js: local classification with net.BlockList

PHP: a CIDR check without a library

Reject, flag, or accept: making the call

Keeping the list current

Which Proxy & VPN Signals Should Block a Signup?

TL;DR

The signup decision matrix

What each signal actually means at signup

Node.js: local classification with `net.BlockList`

Why `peers` may already contain your upstreams and downstreams