DEV Community: ABDULLAH AFZAL

What Is Google's ASN? Why the Answer Is a List

ABDULLAH AFZAL — Thu, 29 Oct 2026 18:20:13 +0000

Google's main ASN is AS15169. That's one Google ASN out of 21 that ARIN lists under three separate Google org IDs, and Amazon and Microsoft are built the same way: one famous number, then a long tail of ASNs split by customer type, legal entity, and acquisition.

So if you're grouping log traffic, writing a WAF rule, or deciding whether a request "came from Google," one number won't cover it, and lumping them all together is worse. This post skips the basics. For those (what an AS is, how BGP uses it, who hands them out), see this guide to autonomous system numbers.

TL;DR

AS15169 is Google's primary ASN, but it is not a reliable google-services classifier by itself. AS396982 and AS19527 are explicitly associated with Google Cloud customer traffic, but security policy should still classify the individual prefix using Google's published service, Cloud, or crawler range files.
An AS is a routing policy, not a company. A company with five routing policies ends up with five ASNs.
The AWS ASNs to know are AS16509 and AS14618, plus AS8987 for GovCloud (US) and AS214101 for the European Sovereign Cloud.
Microsoft's AS8075 is the last number in a block of eight, AS8068 to AS8075, registered in 1997.
Group twice: by parent company for reporting, by function for security policy. Then check who's behind the prefix, because the ASN doesn't always tell you. "Google" in a traffic report is at least three different things: Google's own services, strangers renting Google Cloud, and Google Fiber's home subscribers. They all roll up to the same parent. Treat them as one bucket on a dashboard if you like. Never treat them as one bucket in a firewall rule.

Google ASN list, sorted by job

Google LLC's primary ASN is AS15169, registered with ARIN in March 2000. It carries Google's own services, including the Googlebot crawler. It isn't the only one: Google's own PeeringDB record says Google manages seven ASNs, and ARIN's registry shows more than that. These are the ones you're most likely to meet in logs:

ASN	Registry name	Registered to	What it's for
AS15169	GOOGLE	Google LLC (ARIN)	Google's primary network; use prefix-level lists to distinguish services, crawlers, Cloud ranges and third-party space
AS396982	GOOGLE-CLOUD-PLATFORM	Google LLC (ARIN, Cloud org ID)	Google Cloud customer workloads
AS19527	GOOGLE-2	Google LLC (ARIN, Cloud org ID)	Google Cloud customers
AS16550	GOOGLE-PRIVATE-CLOUD	Google LLC (ARIN, Cloud org ID)	Private connectivity, 9 IPv4 routes
AS36040	YOUTUBE	Google LLC (ARIN)	YouTube, registered in 2005
AS43515	YOUTUBE	Google Ireland Limited (RIPE)	Google's Irish legal entity
AS139070	GOOGLE-AS-AP	Google Asia Pacific Pte. Ltd. (APNIC)	Google's Singapore legal entity
AS16591	GOOGLE-FIBER	Google Fiber Inc. (ARIN)	Residential ISP

Is Google Cloud on AS15169? Mostly not. The Google Cloud ASN you'll meet most is AS396982, and ARIN's record for it says so in plain words: "This ASN is used for Google Cloud Platform." That split between Google's own network and the network it rents out is the one that matters most, and the one ASN lookup pages tend to flatten into a single "Google" label.

Which list is right, PeeringDB's seven or ARIN's 21? Both. They answer different questions, which is the whole problem.

Why one company ends up with multiple ASNs

An AS is a routing policy, not a company

RFC 1930, the 1996 best-practice document for AS numbers, defines an AS as a group of prefixes with "a SINGLE and CLEARLY DEFINED routing policy." Section 4 even names the mistake of using an AS "as a convenient way of grouping together a set of prefixes which belong under the same administrative umbrella."

So the registry was never built to map ASNs to companies. A company gets another ASN whenever part of its network needs to behave differently on the internet, and a company the size of Google has a lot of parts that behave differently.

Customer traffic gets its own number

This is the reason I'd care about most if I ran a firewall. AS15169 sits under an ARIN org ID called GOGL. AS396982 and AS19527 sit under a different one, GOOGL-2, also named "Google LLC," and the AS19527 record carries a comment: "The IP addresses under this Org-ID are in use by Google Cloud customers." The comment then sends abuse complaints to Google Cloud's reporting form.

GOOGL-2 holds 11 ASNs, with names like GCP-ENTERPRISE-USER-TRAFFIC and G-CLOUD-AGENT-TRAFFIC. When someone's rented VM hammers your login page, the complaint path leads to the Cloud abuse desk, not to the people running Search.

My read, not Google's stated reason: it also keeps the reputation of Google's own address space apart from whatever tenants do with theirs. Either way, the line between "Google" and "someone on Google" is already drawn in the registry.

Legal entities live in different registries

ASNs belong to legal entities, and legal entities register with their regional registry. AS43515 is registered to Google Ireland Limited at RIPE. AS139070 belongs to Google Asia Pacific Pte. Ltd. at APNIC. Amazon's European Sovereign Cloud runs AS214101 under Amazon Data Services European Sovereign Cloud GmbH, also at RIPE. Three registries, a different spelling in each, one parent.

Regulated and private networks

Some networks exist to be kept apart. AWS's BYOIP documentation has customers check their route authorizations against AS16509 and AS14618, then against AS8987 for GovCloud (US), and AS16509 plus AS214101 for the European Sovereign Cloud. A government region on its own ASN is much easier to reason about than one hidden inside AS16509.

Other ASNs exist for private links. Microsoft runs ExpressRoute, its private-connection product, on AS12076, and its peering policy tells every peer not to accept routes from AS12076 "under any circumstances." Google's AS16550 is named GOOGLE-PRIVATE-CLOUD and announces just nine IPv4 routes.

Acquisitions keep their numbers, or get folded in

AS36040 is named YOUTUBE and was registered in August 2005, before Google bought YouTube. It now sits under Google LLC. Microsoft's main ARIN org ID, MSFT, holds 42 ASN records, and the names read like an M&A history: NUANCE-BURLINGTON, PHONEFACTOR-01, ASN-YAMMER, FAST-SEARCH-AND-TRANSFER-INC, MS-DANGER.

Not everything gets folded in. GitHub's AS36459 is still registered to GitHub, Inc., and LinkedIn's AS14413 to LinkedIn Corporation. It cuts the other way too: ARIN still files AS19425, named WAYMO, under Google LLC's GOGL org ID, even though Waymo runs as its own Alphabet company. Registry records lag the org chart, sometimes by years.

How Google, Amazon, and Microsoft lay it out

Google splits by who's on the other end

Put the registry records side by side and Google's layout jumps out. ARIN holds Google LLC under three org IDs: GOGL with 9 ASNs including AS15169, GOOGL-2 with the 11 Cloud ASNs, and GOOGL, spelled "Google, LLC" with a comma, holding AS36492 (GOOGLEWIFI). Add Google Ireland at RIPE, Google Asia Pacific at APNIC, and Google Fiber Inc., and one parent has six registrant records under five spellings.

GOOGL-2 is explicitly marked in ARIN as address space used by Google Cloud customers. GOGL is Google's older organization record, but an ASN under GOGL is not a service-level trust boundary. Prefix-level data is still needed before an address is treated as a Google-operated service.

Amazon runs one giant ASN and a few specialists

Amazon's main ASN is AS16509 (AMAZON-02), with AS14618 (AMAZON-AES) as the other big one. There's no single AWS ASN to allowlist. On October 29, 2026, AS16509 announced 19,751 IPv4 routes against 1,529 for AS14618, roughly 13 to 1 (route counts from ipgeolocation.io's ASN endpoint).

The two big ones sit under different ARIN org IDs, AMAZON-4 and AMAZO-4, both named "Amazon.com, Inc." AMAZO-4 also holds AS21664, named AMZN-BYOASN. GovCloud's AS8987 is registered to a third name, Amazon Technologies Inc., with aws.amazon.com as its domain. The oldest of the lot, AS7224 (AMAZON-AS), dates to October 1996 and announces 27 IPv4 routes.

Neither big number separates Amazon's own services from its customers' instances. An allowlist built on these Amazon ASN numbers admits anyone who can launch an EC2 instance.

Microsoft: one 1997 block and a long tail

The Microsoft ASN you'll see in logs and peering docs is AS8075, the one Microsoft names first in its peering policy. ARIN doesn't store it as a standalone record. AS8075 is the last number in one registration covering AS8068 through AS8075, dated March 31, 1997 and named MICROSOFT-CORP-MSN-AS-BLOCK.

The policy points to an IRR as-set, AS-MICROSOFT, for the full list of ASNs Microsoft manages, and says ASNs that customers bring through its BYOASN product get added to that set. The registry view sprawls further: those 42 MSFT records, plus GitHub and LinkedIn under their own names. One more line from the same policy matters later: prefixes that customers bring through BYOIP "are all properly registered as AS8075."

Same question, two sources per company:

Company	What the operator publishes	What ARIN shows
Google	7 ASNs in its PeeringDB record	21 ASN records under GOGL, GOOGL-2 and GOOGL, plus RIPE and APNIC entities
Amazon	4 ASNs in the BYOIP docs: 16509, 14618, 8987, 214101	AMAZON-4 and AMAZO-4, plus Amazon Technologies Inc.
Microsoft	AS8075 and the AS-MICROSOFT as-set; AS12076 for ExpressRoute	42 ASN records under MSFT

Neither column is wrong. The operator lists what it routes and wants you to peer with. The registry lists everything the legal entity has ever registered and not returned.

How to group IP traffic by organization

Name matching breaks on the first comma

The obvious approach is to group on the ASN's organization string. It falls apart fast. ARIN has Google as both "Google LLC" and "Google, LLC". RIPE adds "Google Ireland Limited". Amazon shows up as "Amazon.com, Inc.", "Amazon Technologies Inc." and "Amazon Data Services European Sovereign Cloud GmbH", and the company record on one AWS address I looked up, 3.80.0.1, read "Amazon Data Services Northern Virginia."

Fuzzy matching catches some of these and quietly invents matches you didn't want. Pick a key that doesn't change spelling.

Pick a key that survives

The ASN's registered domain is the first thing I'd try. Seven of the eight Google ASNs in the table above came back with google.com as their domain; Google Fiber came back with gfiber.com. Amazon needs three: amazon.com, aws.amazon.com and aws.eu. A short alias map covers all three companies.

If you need coverage beyond the big three, use a curated AS-to-organization mapping. CAIDA's AS2Org dataset maps ASNs to organizations from quarterly WHOIS dumps of all five RIRs, with snapshots back to October 2009. The newer ASINT project adds PeeringDB, company websites and merger records, and groups 111,470 ASNs into 81,233 organization families. Both are research datasets, so check how fresh they are before a production job depends on them.

For the ASNs that actually show up in your logs, keep a short list you've checked against the registry by hand. That's what the script below does.

Group twice: parent for reporting, function for policy

Here's the position I'll defend: one "Google" row is fine for a monthly traffic report and wrong for anything that allows or blocks. Googlebot crawling your docs and a scraper on a rented Compute Engine VM both roll up to Google LLC. They should not share a rule.

The ASN type field won't split them for you. AS15169 and AS396982 both come back as HOSTING (that field is still useful for other jobs; I covered them in classifying ASNs by type). The function often has to come from the prefix rather than the ASN. Google publishes the required source data: subtract cloud.json from goog.json to derive the ranges used by Google's own APIs and services, and use Google's separate crawler files when crawler identity matters. Treat the ASN role map below as a fallback, not as a security allowlist.

Keep two columns, then. parent holds google, amazon or microsoft. role holds google-services, cloud-tenants, isp, aws or mixed. Report on the first. Write policy on the second.

Check who's behind the prefix

The ASN tells you who announces a prefix. It doesn't always tell you who uses it. 57.140.0.0/16 is an ARIN direct allocation to Menlo Security, Inc., and 57.140.216.0/24 is announced by AS15169. Look up 57.140.216.1 and the ASN says Google, while the company using the range is Menlo Security:

{
  "ip": "57.140.216.1",
  "asn": {
    "as_number": "AS15169",
    "organization": "Google LLC",
    "country": "US",
    "type": "HOSTING",
    "domain": "google.com",
    "date_allocated": "2000-03-30",
    "rir": "ARIN"
  },
  "company": {
    "name": "Menlo Security, Inc.",
    "type": "BUSINESS",
    "domain": "menlosecurity.com"
  }
}

That's the /v3/ipgeo response with fields=asn,company. Drop the parameter and you also get location, network, time zone and currency for the same IP.

This is third-party address space announced through Google's ASN. It is consistent with BYOIP or another delegated routing arrangement, but the registry and BGP records alone do not prove the commercial mechanism. Microsoft and AWS explicitly document BYOIP under their ASNs, so the same separation between route origin and address holder matters there too. If your rule says "trust AS15169," you just trusted a security vendor's egress range as well.

The script below does both groupings and flags prefixes whose registered company differs from the mapped provider parent. Treat that as an external-prefix signal that may indicate BYOIP, not as proof by itself. I'm using ipgeolocation.io's bulk endpoint because each row carries the ASN registrant (asn) and the company using the prefix (company) side by side, which is exactly the pair the BYOIP check needs. ipinfo, MaxMind GeoIP2 and IP2Location expose ASN data too; whichever you use, make sure it keeps those two apart.

One trade-off up front: this bulk script requires a paid plan. The bulk endpoint, asn.domain, and company enrichment are paid features. A free single-IP /v3/ipgeo lookup still returns as_number, organization, and country, which is enough to build a basic ASN map, but it cannot run this bulk workflow or perform the external-prefix comparison.

import os
import sys
from collections import Counter

import requests

API_KEY = os.environ.get("IPGEOLOCATION_API_KEY")
BULK_URL = "https://api.ipgeolocation.io/v3/ipgeo-bulk"
BATCH_SIZE = 50_000  # documented per-request maximum

# ASNs whose job the registry or the operator states in writing.
# Checked against ARIN and PeeringDB on 2026-10-29. Re-check every quarter.
ASN_ROLE = {
    "AS15169": ("google", "mixed"),  # resolve service, Cloud and crawler roles by prefix
    "AS36040": ("google", "google-services"),  # registered as YOUTUBE
    "AS396982": ("google", "cloud-tenants"),   # ARIN: "used for Google Cloud Platform"
    "AS19527": ("google", "cloud-tenants"),    # ARIN: "in use by Google Cloud customers"
    "AS16591": ("google", "isp"),              # Google Fiber
    "AS16509": ("amazon", "aws"),
    "AS14618": ("amazon", "aws"),
    "AS8075": ("microsoft", "mixed"),          # BYOIP tenants are registered here too
}

# Registrant domains that roll up to one parent. Extend as you find more.
DOMAIN_PARENT = {
    "google.com": "google", "gfiber.com": "google",
    "amazon.com": "amazon", "aws.amazon.com": "amazon", "aws.eu": "amazon",
    "microsoft.com": "microsoft", "github.com": "microsoft",
    "linkedin.com": "microsoft",
}


def parent_of(domain):
    return DOMAIN_PARENT.get(domain, domain)

ASN_ROLE is the hand-checked list from the previous section, and DOMAIN_PARENT is the alias map. I left AS8075 as mixed on purpose: Microsoft's own policy says BYOIP customers are registered there, so even before you ask what Microsoft runs on it, you know some of it isn't Microsoft.

def lookup(ips):
    if not API_KEY:
        sys.exit("Set IPGEOLOCATION_API_KEY first.")
    try:
        resp = requests.post(
            BULK_URL,
            params={"apiKey": API_KEY, "fields": "asn,company"},
            json={"ips": ips},
            timeout=(3, 30),  # connect fast; big batches need read time
        )
        resp.raise_for_status()
        return resp.json()
    except requests.HTTPError as exc:
        # Don't print exc itself: its message contains the URL, and the URL contains your key.
        sys.exit(f"Bulk lookup failed: HTTP {exc.response.status_code}")
    except (requests.RequestException, ValueError) as exc:
        # A report built on half the data is worse than no report.
        sys.exit(f"Bulk lookup failed: {type(exc).__name__}")

The error handler prints the status code and the exception type, never the exception itself. requests puts the full URL in its error messages, and this URL carries your API key, so a plain print(exc) ships the key straight into your logs. Exiting on failure is deliberate too: for a reporting job, a partial count is worse than no count.

def classify(row):
    asn = row.get("asn") or {}
    company = row.get("company") or {}
    number = asn.get("as_number", "unknown")
    asn_domain = asn.get("domain", "")
    fallback_parent = parent_of(asn_domain) or asn.get("organization", "unknown")
    parent, role = ASN_ROLE.get(number, (fallback_parent, "unclassified"))

# The prefix registrant differs from the mapped provider parent.
# This may be BYOIP or another delegated routing arrangement, so label
# the observable condition rather than claiming the contract behind it.
tenant = company.get("domain", "")
if number in ASN_ROLE and tenant and parent_of(tenant) != parent:
    role = f"external-prefix:{company.get('name') or tenant}"
    return parent, role, number


if __name__ == "__main__":
    ips = [line.strip() for line in sys.stdin if line.strip()]
    rows = []
    for start in range(0, len(ips), BATCH_SIZE):
        rows.extend(lookup(ips[start:start + BATCH_SIZE]))

    by_parent, by_role = Counter(), Counter()
    for row in rows:
        if "message" in row:  # bogon, private, or malformed input
            print(f"skipped: {row['message']}", file=sys.stderr)
            continue
        parent, role, number = classify(row)
        by_parent[parent] += 1
        by_role[(parent, role, number)] += 1

    print("By parent:", dict(by_parent))
    for (parent, role, number), count in by_role.most_common():
        print(f"{parent:<10} {role:<32} {number:<9} {count}")

A free-plan key cannot run this script because /v3/ipgeo-bulk is paid-only. If you adapt it to make individual /v3/ipgeo calls on the free plan, unmapped ASNs can fall back to the organization string, but asn.domain and company will be unavailable and the external-prefix check cannot run. The bulk endpoint returns a message object for bogon or malformed input instead of failing the batch, which is why the loop skips those rows rather than crashing.

Feed it a list of IPs on stdin:

printf '%s\n' 8.8.8.8 66.249.66.1 34.140.0.10 57.140.216.1 3.80.0.1 20.42.65.92 10.0.0.1 \
  | python3 group_by_org.py

skipped: '10.0.0.1' is a bogon IP address.
By parent: {'google': 4, 'amazon': 1, 'microsoft': 1}
google     mixed                            AS15169   2
google     cloud-tenants                    AS396982  1
google     external-prefix:Menlo Security, Inc. AS15169   1
amazon     aws                              AS14618   1
microsoft  mixed                            AS8075    1

Four of the six public IPs roll up to Google, and the role column splits them three ways. 34.140.0.10 sits in a range Google lists in cloud.json, and its company record still reads "Google LLC". The company field names whoever registered the range, not the Cloud tenant, which is why the role has to come from the ASN.

A few extra notes

Sibling ASNs set off false alarms. BGP monitors flag a route when the origin ASN doesn't match the prefix's ROA, and plenty of those turn out to be a company moving a prefix between its own ASNs. The ASINT team reviewed 17,282 BGP anomaly alerts from January 2023 to July 2024 and marked 1,621 of them, about 9.4%, as likely intra-organization. An org map cuts that noise.

Refresh the map at least quarterly, the cadence CAIDA uses for AS2Org. Registry records outlive the networks behind them: Twitch's AS46489 is still registered to Twitch Interactive Inc. and announced zero routes when I checked.

Don't verify Googlebot by ASN alone. An AS15169 match is a good hint, but Google's own method is a reverse DNS lookup plus a forward confirm, or a match against its published crawler ranges. 66.249.66.1 in the run above is the example address from that page.

If you need to see what a single ASN connects to rather than who owns it, routes and neighbors are a separate pivot. I walked through that in the post on routes, upstreams, and downstreams.

Start with the ASNs that actually show up in your logs, check each one against its registry record once, and write its role down next to it. Re-run that check every quarter. Google, Amazon and Microsoft will keep adding numbers, and not every new one will come with a comment as helpful as GOOGL-2's.

EU Geo-Blocking Regulation: Redirects, Forms, Payments

ABDULLAH AFZAL — Mon, 26 Oct 2026 18:01:04 +0000

The EU Geo-Blocking Regulation (Regulation (EU) 2018/302) doesn't care whether you block EU shoppers with a firewall rule, a redirect or a postcode validator. All three count. The third is the one most teams still ship without noticing.

The twist arrived in July 2026. In a case involving a work that was public domain in some member states but still protected in another, the EU's top court held that the publisher needed effective technological measures to exclude users in the protected territory. State-of-the-art IP geo-blocking can qualify even though some users can circumvent it with a VPN. Same lookup, opposite legal answer. What separates them is the reason behind the check.

Heads up: this is a developer's reading of the regulation and the Commission's own guidance, with links to both. It isn't legal advice.

TL;DR

Article 3 (page access): you can't block or auto-redirect EU customers by IP address. Redirects need explicit consent, and the version they asked for has to stay one click away.
Article 4 (forms and terms): for goods you deliver or let people collect, e-services like hosting and cloud, and services at a physical venue, EU customers buy on the same terms as locals. Address and phone fields count.
Article 5 (payment): if you accept a card brand and category from one EU country, you accept it from all of them.
Copyright carve-out: software, games, e-books and music escape Article 4 only. Audiovisual, financial, transport, healthcare and gambling are outside the regulation entirely.
Legal blocks are fine: if EU or applicable national law requires the restriction, block and explain why. In the 2026 copyright ruling, the CJEU said state-of-the-art IP geo-blocking can qualify as an effective technological measure even though VPN circumvention remains possible. In short: the regulation follows the customer through your whole flow, not just the front door. Treat every country check as a decision that needs a legal reason. If the only reason is "they live in another EU country", the check probably has to go. If EU law, applicable national law, a court order, or the territorial scope of copyright itself legally requires the restriction, keep it and explain the reason to the user.

What the EU geo-blocking regulation actually covers

The regulation has applied since 3 December 2018. It protects "customers", which the text defines as consumers who are nationals or residents of an EU member state, plus businesses established in one when they buy for their own end use. Reselling, processing or subcontracting isn't covered.

It binds traders, not just EU traders. Recital 17 says it applies equally to traders established outside the EU, online marketplaces included, when they operate in the Union. A US SaaS company selling to Spanish customers is in scope.

Three things put a situation outside it:

Situation	Covered?
Customer in another EU member state buying from you	Yes
Every element of the sale inside one member state (purely domestic)	No
Someone who is neither an EU national nor an EU resident	No, this regulation only protects EU customers
Audiovisual, financial, transport, healthcare, gambling, electronic communications	No, excluded sectors
Non-audiovisual copyrighted content (software, games, e-books, music)	Partly: Articles 3 and 5 apply, Article 4 doesn't

That third row matters for anyone running country allow-lists. Blocking non-EU countries is mostly outside this regulation, with one wrinkle: an EU national travelling or living abroad is still a protected customer. It's one more reason an IP country is a poor stand-in for anyone's legal status.

The regulation is short. Articles 3, 4 and 5 do almost all the work, and each one lands on a different part of your stack.

Three articles, three places in your stack

Article 3 is your front door

Article 3 bans blocking or limiting access to your "online interface" for reasons related to a customer's nationality, residence or place of establishment, "through the use of technological measures or otherwise". Online interface means websites, parts of websites and apps. Recital 18 spells out which technological measures it means: tracking location "by means of an IP address or coordinates obtained through a global navigation satellite system". It names our tools specifically.

Redirects are the part developers trip over. You can run de.example.com and fr.example.com with different layouts, languages and prices. You can't bounce a visitor from one to the other because of where they are, unless they've explicitly agreed. Recital 20 and the Commission's Q&A on the Geo-blocking Regulation fill in the details: consent doesn't need to be asked on every visit, a preference saved to an account counts, the customer can withdraw it at any time, and the version they originally asked for must stay easily reachable. The Commission's example is literally "an easily accessible button to take the customer back".

The ban isn't limited to IP. The same Q&A says you can't block app versions based on the country where someone's card was issued either.

App stores are where this is playing out now. In November 2024 the Commission and the consumer protection (CPC) network notified Apple of practices across the App Store, Arcade, Music, iTunes Store, Books and Podcasts. They covered country-specific storefronts users couldn't easily switch, payment limited to cards from the account's country, and downloads limited to the account's country. In a September 2026 answer to a Parliament question, the Commission said the action is still in progress and confirmed that restricting access to apps from other EU countries is one of the practices the regulation potentially prohibits.

Article 4 is your checkout form

Article 4 is the "shop like a local" rule. In three situations you can't apply different general conditions of access (prices, payment terms, delivery terms) because of where a customer is from:

Goods delivered to a place you already deliver to, or collected at a pickup point you already offer.
Electronically supplied services, which recital 24 illustrates with cloud services, data warehousing, website hosting, firewalls, search engines and internet directories.
Services at a physical location: hotel rooms, car rental, event and theme-park tickets. You don't have to deliver everywhere. A German shop that only ships within Germany can keep it that way. What it can't do is refuse a Belgian customer who wants it shipped to a German address or picked up in Germany.

Here's why this belongs in a developer article. The European Court of Auditors' special report on geo-blocking compares the Commission's mystery-shopping surveys from 2015 and 2019, stage by stage. Cross-border shoppers blocked or redirected at the front door were already rare and got rarer: 3.4% to 2.9%. Blocks at registration fell from 26.9% to 14.0%. Shoppers who registered fine and then got stopped before the delivery stage rose from 37.8% to 43.0%.

Read that again with your codebase in mind. The geo-blocking that's left mostly isn't a firewall rule. It's a postcode regex that only accepts five German digits, a phone field that rejects anything but +49, a country dropdown with one entry. The Commission's Q&A addresses this directly: a form that requires a residence address but only accepts national formats, with no way to enter a foreign one, "would need to be adapted". Germany's enforcer, the Bundesnetzagentur, lists billing address, IP address and telephone number as the signals traders use to spot foreign buyers.

The audits find exactly that. As the auditors' report recounts, when Sweden's consumer agency checked 78 online shops in 2021, 24 of the 32 that offered in-store pickup required a Swedish postal address.

Two things Article 4 doesn't touch. Article 4(2) lets you set different prices per country or per storefront, as long as anyone can buy at any storefront's terms. And the Q&A says dynamic pricing based on things unrelated to residence, like demand or past purchases, is outside the regulation. Price experiments are fine. Pricing keyed on the visitor's country is the problem.

Article 5 is your payment step

Within the payment methods you accept, you can't refuse a payment or change its conditions because of the customer's nationality or residence, the location of their payment account, where their payment provider is established, or where their card was issued in the EU. It applies to electronic payments by credit transfer, direct debit or card within the same brand and category, where strong customer authentication is met and the currency is one you accept.

You still choose what you accept. Visa debit only? Fine. Visa debit only if it's from a French bank? Not fine.

Article 5(2) lets you hold delivery until you've confirmed the payment went through, but only "where justified by objective reasons". That isn't a licence for a fraud rule that declines every card issued outside your home country. Stripe's guidance on the regulation reads it the same way: fraud tools shouldn't auto-decline accepted cards from particular EU countries. Score risk on many signals. Issuer country alone is a location proxy, and the regulation is about location proxies.

The copyright carve-out most developers misread

"We sell software, so geo-blocking rules don't apply." It's the most common misreading of the regulation, and it's half right.

Article 4(1)(b) excludes services whose main feature is access to copyright-protected works. The Commission's Q&A names e-books, software (updates included), music streaming and online games. Those services are exempt from Article 4's equal-terms rule, so a games publisher can decline to sell in a country where it doesn't hold the rights. But the same Q&A says they stay subject to everything else: no blocking access to website, marketplace or app-store versions by IP or payment details, no redirecting without consent, and no discriminating on where an accepted card was issued.

So a software seller can say "we don't sell this edition in Portugal". It can't stop a Portuguese visitor from loading the page.

Hosted products are murkier. Recital 24 puts cloud services, hosting and firewalls squarely inside Article 4. Whether a given SaaS counts as "mainly access to copyrighted works" or as a cloud service isn't settled, and the Court of Auditors notes that enforcement bodies themselves find the "main feature of which" wording unclear. My take: if you sell a hosted product on public terms to anyone who signs up, build as if Article 4 applies. Being wrong in that direction costs a country dropdown. Being wrong in the other costs an enforcement letter.

Two smaller notes. Traders covered by their country's VAT exemption scheme for small businesses don't have to follow Article 4(1)(b) for e-services (Article 4(4)). And audiovisual streaming is out of the regulation altogether, which is why streaming services' licence maps, not this law, decide what you can watch from another country.

When is geo-blocking legal in the EU?

Short answer: when the visitor isn't an EU customer, when the sector is excluded, or when another law requires the block. That third case is where developers need to get the details right.

When another law requires it

Articles 3(3) and 4(5) carve out blocking, limiting or redirecting that's needed to comply with EU law, or with national law that's consistent with EU law. Think gambling licences, court orders, national book-pricing laws, products that are banned in one country.

There's a condition people skip. When you block for a legal reason, you must give "a clear and specific explanation" of why, in the language of the interface the customer was trying to reach. A bare 403 Forbidden doesn't do that.

HTTP already has a status code for this. RFC 7725 defines 451 Unavailable For Legal Reasons and says the response body should explain the legal demand: who made it, which law, and who it applies to. It also defines an optional Link header with rel="blocked-by" to identify the entity actually implementing the block, not the law or rights holder behind the demand. The regulation doesn't mention 451, but the two fit together well.

What the July 2026 Anne Frank ruling changed

The case: parts of Anne Frank's manuscripts are still under copyright in the Netherlands until 2037 but are public domain in Belgium and elsewhere. A scholarly edition was published free on a website that blocked Dutch IP addresses. The rights holder argued that Dutch users could just use a VPN, so the work was still being "communicated to the public" in the Netherlands.

On 9 July 2026 the CJEU disagreed. Someone publishing a work that's protected in some member states and public domain in others must make sure it's only accessible from the public-domain ones, and must use effective technological measures to do it. State-of-the-art geo-blocking can qualify as effective even though a VPN can get around it, with the national court ultimately assessing whether the particular implementation meets that standard. If the blocking isn't effective, the publisher is responsible, not the VPN provider.

The Commission's IP Helpdesk summary adds two details builders should note. IP-address geo-blocking was the technological measure at issue. And the site's extra "please confirm you're in a country where this is public domain" prompt didn't count, because it depended entirely on the user's honesty.

So in a copyright situation like this one, effective technological geo-blocking can be necessary to keep access outside the protected territory. An IP-based measure can satisfy that standard; a checkbox based only on the user's declaration cannot substitute for it.

What nobody knows yet is how high "state of the art" sets the bar. The Dutch Supreme Court still has to decide whether this site's blocking met it, weighing available technology, how easily it's circumvented and what better measures cost. Whether that will eventually mean VPN or proxy detection on top of a country lookup is an open question. I wouldn't tell you it does, and I wouldn't bet on it never mattering.

Patterns that keep your country checks legal

Start by finding every place your code makes a decision by country. A quick search catches most of them:

# List every line that branches on a country, a geo header or a geo database.
# Skip vendored code so the results stay readable.
rg -n -i "country_?code|cf-ipcountry|geoip|geo_?block|allowed_?countries" \
  --glob '!node_modules' --glob '!vendor'

CF-IPCountry is the header Cloudflare adds with the visitor's two-letter country code (Cloudflare docs), so it shows up in a lot of edge-routing code. Go through each hit and write the reason next to it in a comment. If the honest reason is "the customer is in another EU country", that check is the one to remove or rewrite.

Suggest, don't redirect

Detecting the country is fine. Acting on it without asking is what Article 3 forbids. The fix is a banner instead of a redirect.

The examples use an IP geolocation API from ipgeolocation.io, because the v3 lookup returns the country code alone when you ask for just that field. ipinfo, MaxMind GeoIP2 or a CDN country header give you the same input. First, a small server-side helper:

// geo.js: Node 18+ (built-in fetch). Set IPGEO_API_KEY in the environment.
const API_URL = 'https://api.ipgeolocation.io/v3/ipgeo';

export async function lookupCountry(ip) {
  if (!ip) return null;
  const url = new URL(API_URL);
  url.searchParams.set('apiKey', process.env.IPGEO_API_KEY ?? '');
  url.searchParams.set('ip', ip);
  // Ask for one field: smaller response, and the only thing we use.
  url.searchParams.set('fields', 'location.country_code2');

  try {
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) {
      console.warn(`geo lookup failed: HTTP ${res.status}`);
      return null;
    }
    const data = await res.json();
    return data?.location?.country_code2 ?? null;
  } catch (err) {
    // Timeouts and network errors land here. Callers decide what null means.
    console.warn(`geo lookup error: ${err.message}`);
    return null;
  }
}

Then an endpoint that only suggests a storefront. It never redirects. Before reusing req.ip for an enforcement control later in this article, make sure your proxy trust configuration cannot be bypassed through a shorter or direct path to the application.

// server.js
import express from 'express';
import { lookupCountry } from './geo.js';

const app = express();
// Illustrative only: this is safe when every request reaches Express through
// exactly one trusted proxy and clients cannot reach the origin directly.
// If request paths vary, trust the exact proxy IPs/CIDRs you control instead.
app.set('trust proxy', 1);

const STOREFRONTS = { DE: '/de/', FR: '/fr/', NL: '/nl/' };

app.get('/api/store-suggestion', async (req, res) => {
  const country = await lookupCountry(req.ip);
  // Fail open: no country means no banner, and the visitor keeps browsing.
  res.json({ country, storefront: STOREFRONTS[country] ?? null });
});

app.listen(3000);

And the browser side. It shows a banner only if the visitor hasn't already chosen, and remembers the choice:

// banner.js: runs on every storefront page.
const CHOICE_COOKIE = 'store_choice';

function savedChoice() {
  const match = document.cookie.match(/(?:^|; )store_choice=([^;]*)/);
  return match ? decodeURIComponent(match[1]) : null;
}

async function maybeSuggestStore() {
  if (savedChoice()) return; // They already decided. Don't ask again.

  try {
    const res = await fetch('/api/store-suggestion');
    if (!res.ok) return;
    const { storefront } = await res.json();
    if (!storefront || location.pathname.startsWith(storefront)) return;

    const banner = document.getElementById('store-banner');
    if (!banner) return;
    banner.querySelector('a.go').href = storefront;
    banner.hidden = false;

    // Both buttons record an explicit choice; only "go" navigates.
    banner.querySelector('a.go').addEventListener('click', () => remember(storefront));
    banner.querySelector('button.stay').addEventListener('click', () => {
      remember(location.pathname.split('/').slice(0, 2).join('/') + '/');
      banner.hidden = true;
    });
  } catch (err) {
    console.warn('store suggestion unavailable', err);
  }
}

function remember(path) {
  document.cookie = `${CHOICE_COOKIE}=${encodeURIComponent(path)}; path=/; max-age=31536000; SameSite=Lax`;
}

maybeSuggestStore();

Keep a visible store switcher in the header on every page, so the original version stays one click away even after someone picks. Storing the choice in a cookie brings GDPR and the ePrivacy rules into play, which the Commission's Q&A flags too, so run it past whoever owns your cookie policy.

Forms, payments and legally required blocks

Forms are where most remaining geo-blocking lives, so they get the most attention:

Split residence from delivery. Restrict the delivery address to the places you ship. Accept any EU billing or residence address, with a free-text fallback for formats you don't validate.
Phone fields accept every EU prefix. If you need a local number for the courier, ask for it on the delivery step, not at signup.
Accept payments by brand and category, not by issuer country. If your PSP lets you block by BIN country, don't point that at EU countries for methods you accept. For blocks another law really does require, answer with a 451 and say why, in the language of the page:

// legal-block.js: a public-domain edition still protected in some countries.
// Mount on a route with a language segment, e.g. app.get('/:lang/edition', copyrightBlock, handler).
import { lookupCountry } from './geo.js';

const PROTECTED_IN = new Set(['NL']); // from your rights research, not a guess
const EXPLANATION = {
  en: 'This edition is still protected by copyright in your country, so we cannot make it available there.',
  nl: 'Deze editie is in uw land nog auteursrechtelijk beschermd en is daar daarom niet beschikbaar.',
};

export async function copyrightBlock(req, res, next) {
  const lang = req.params.lang === 'nl' ? 'nl' : 'en'; // the page's language, not Accept-Language
  const country = await lookupCountry(req.ip);

  // Fail closed: a block that law requires shouldn't vanish when the lookup does.
  if (country === null) {
    return res.status(503).set('Retry-After', '60').send('Location check unavailable. Please try again shortly.');
  }
  if (PROTECTED_IN.has(country)) {
    return res
  .status(451)
  .send(EXPLANATION[lang]);
  }
  return next();
}

Note the fail-closed choice. The suggestion banner fails open because a missing banner hurts nobody. A legally required block fails closed because that's where an outage turns into an infringement.

How seriously is this enforced?

Unevenly, so far. The Court of Auditors' audit found that fines vary wildly by member state: minimum fines from €26 to €900,000, maximums from €1,448 to €5 million. Between December 2018 and June 2024 there was exactly one coordinated EU-level enforcement action under the regulation, and only two of the 18 national enforcement bodies that answered the auditors' survey had ever penalised a trader. A 2023 study for the Commission found 37% of traders didn't know the regulation existed.

It would be easy to read that as permission to ignore it. I wouldn't. The auditors recommended an EU-wide enforcement mechanism by the end of 2026, the Apple case shows the CPC network going after app-store mechanics specifically, and the Commission is preparing a revision of the CPC Regulation for the fourth quarter of 2026. Fixing a postcode validator now is cheaper than doing it under a deadline.

What's changing in 2026

The regulation is under its five-yearly evaluation. The Commission's first round of feedback ran in February and March 2025 and drew more than 500 responses, mostly about whether to bring audiovisual services into scope, then a public consultation from 6 October 2025 to 5 January 2026, per the Bundesnetzagentur's summary. The Court of Auditors asked the Commission to study extending the scope to the excluded sectors by the end of 2026.

Two related proposals are due this quarter: the CPC Regulation revision, and the Digital Fairness Act, which the European Parliament's research service says is scheduled for mid-November. Nothing published so far ties the Digital Fairness Act to geo-blocking, so I wouldn't plan around it. If the evaluation does propose widening the scope, streaming and copyrighted content are where it would hit hardest.

Run the search above on your repo this week. Put a legal reason next to every country check that survives it, and fix your address and phone fields before you touch the firewall rules, because that's where the auditors found the blocking.

How Does an IP to Company Lookup Actually Work?

ABDULLAH AFZAL — Tue, 20 Oct 2026 16:17:56 +0000

An IP to company lookup tells you which organization registered or routes a block of IP addresses. It does not tell you who is behind the connection. When a visitor browses from their employer's office network, those two answers match. When they work from home, they almost never do.

Behind every result sit up to three records, and each answers "who owns this IP" differently: the network that carries the traffic, the organization a regional registry gave the address block to, and the customer that organization says it passed the block on to. A visitor report that names a company has picked one of those three.

TL;DR

An IP to company lookup returns the registered holder of an IP range, built from registry (WHOIS) records, provider reassignment filings, and internet routing data.
It names a visitor's employer only when that employer holds its own registered IP block and the visitor is on that network.
Home broadband, cloud servers, VPNs, and Apple's Private Relay resolve to the provider (Comcast, AWS, a VPN host, Akamai), not the visitor's company.
In June 2026, 52.5% of US workers in financial activities and 47.2% in the information sector teleworked. Those are core B2B buyers, and their home visits show up as an ISP.
Treat business, education, and government results as candidate organization-level matches. Corroborate them with the record age, network context, your target-account list, and first-party activity before triggering an alert or personalization. Treat ISP and hosting results as unidentified. IP to company data works as an account-level signal for office traffic and fails quietly for everything else. The fix is not a better vendor. It is filtering on the company type field before a match reaches a sales alert or an account report.

What an IP to company lookup actually returns

Ask "who owns this IP?" and the internet has three different answers on file.

The network operator announces the address block to the rest of the internet and carries its traffic. It is identified by an autonomous system number (ASN). The registry holder is the organization one of the five regional internet registries allocated the block to. The customer on record is whoever that holder later reassigned a smaller slice to, if it bothered to file the paperwork.

Visitor identification tools usually call this "reverse IP lookup," and under the hood they are reading the same records. A good IP to company lookup returns at least two of these side by side, plus a type label. Here is what five real addresses returned on October 19, 2026:

IP	Network that routes it (type)	Company on record (type)	What a visitor report would show
8.8.8.8	Google LLC (hosting)	Google LLC (hosting)	Google. Correct, but it is Google's public DNS service, not a person
17.253.144.10	Apple Inc. (business)	Apple Inc. (business)	Apple is the correct address holder, but this still does not prove an Apple employee or buyer made the visit
73.162.10.20	Comcast Cable Communications (ISP)	Comcast IP Services (ISP)	Comcast. The visitor's employer is invisible
52.95.110.1	Amazon.com, Inc. (hosting)	Amazon Technologies Inc. (business)	Amazon. Could be any of AWS's customers
209.73.4.40	RapidScale, Inc. (hosting)	Pomona Management Co. (no type)	Pomona Management, based on a filing from 1998

None of the five rows identifies a person or proves buying intent. Apple is the cleanest organization-level match because Apple owns the address space, but it still needs first-party context before it becomes a sales signal.

How an IP address gets matched to a company

Registry records: who was given the block

Every public IP address traces back to one of five regional internet registries: ARIN (North America), RIPE NCC (Europe and the Middle East), APNIC (Asia-Pacific), LACNIC (Latin America), and AFRINIC (Africa). Each publishes who holds which block through WHOIS and its structured successor RDAP, which returns the same registration data as JSON (RFC 9083 defines the format).

Blocks are big. The Comcast address above sits inside Comcast's parent 73.0.0.0/8 allocation, but a more-specific 73.162.0.0/16 reassignment exists for Comcast IP Services. Both layers still name Comcast-related entities, not the household or person using the address this afternoon. The registry tracks responsibility and delegation of the space, not the current subscriber.

Reassignment filings: the only place a customer's name appears

When an ISP or hosting provider hands part of its space to a business customer, it can file a reassignment record with the registry. In ARIN's region this is a SWIP or RWHOIS entry, and it is the only step in the whole chain where a customer's company name enters the data.

The rule is narrower than most people assume. ARIN policy 2018-6, implemented in March 2020, requires registration for reassignments of a /29 or larger, meaning eight or more addresses. A provider is not required by that rule to publish a customer-specific reassignment for one to seven static IPs, so a small office may still appear only under the provider's name.

Providers also file reassignments to themselves. ARIN's record for the Comcast address above shows the /16 slice it sits in reassigned to "Comcast IP Services, L.L.C." inside a larger block held by "Comcast Cable Communications, LLC." That filing is where "Comcast IP Services" in the table's company column comes from, and it is why neither column names a customer.

Routing data: who actually carries the traffic

Separately from the registry, every routed block is announced by an ASN. Mapping an ASN back to an organization is its own inference problem. CAIDA's AS-to-organization dataset, a standard reference in network research, rebuilds that mapping from quarterly WHOIS dumps of all five registries plus the Japanese and Korean national registries.

ASN data is reliable for one question: what kind of network is this? A hosting ASN, an ISP ASN, and a business ASN behave differently, which is why the type label matters more than the name. (If you want the field-level detail, I covered classifying an IP by ASN type separately.)

Enrichment: name, domain, and type

Raw registry text reads like CHINANET FUJIAN PROVINCE NETWORK or POMONA-GW-DTI-NET. Data providers clean that into a company name, attach a website domain, and assign a type: ISP, hosting, business, education, or government. That type label is the field marketers should look at first and usually look at last.

Why the company and the network owner disagree

The fifth row in the table is the most useful one to pick apart.

The address 209.73.4.40 is routed by RapidScale (AS63182). ARIN's registration record for the block shows a /28, 16 addresses, reassigned on August 14, 1998 by Logicworks to a customer called Pomona Management Co., with the record last changed in May 2010. The provider contact on file lists a RapidScale email address next to the old Logicworks one, and ARIN notes it has had no response from that contact since March 2026.

So the block is now routed by a different company than the one that filed it, the contact went quiet, and the customer name stayed exactly where it was for 28 years. A visitor report would still say "Pomona Management" with full confidence. It might even be right. Nothing in the data can tell you.

The Amazon row shows a milder version: the network is "Amazon.com, Inc." and the block is registered to "Amazon Technologies Inc." Same corporate family, different legal entity at each layer. Neither tells you which AWS customer's server made the request.

This is also the plain-English answer to "ISP vs ASN vs company." The ISP is who sells the connection. The ASN is who routes the traffic. The company on record is whoever the registry paperwork names for that specific block. For a home user, all three are the ISP. For an enterprise on its own network, all three can be the enterprise. Everywhere in between, they drift apart.

Where IP to company attribution breaks

Remote workers on home internet

This is the big one for B2B. According to the Bureau of Labor Statistics, 52.5% of workers in financial activities teleworked in June 2026, along with 47.2% in information and 41.8% in professional and business services. Banks, insurers, software companies, agencies, and consultancies are exactly the accounts B2B teams put on target lists.

When those people visit your pricing page from home, the lookup returns Comcast, Spectrum, or Verizon. On mobile and on some broadband networks it is worse, because carrier-grade NAT puts many subscribers behind one shared public address (why CGNAT breaks IP geolocation covers the mechanics). Their visits aren't misattributed. They are simply not attributable.

Cloud servers and shared hosting

A match on AWS, Google Cloud, Azure, DigitalOcean, or another hosting provider means the traffic exited cloud-provider address space. It may be server automation, a crawler, a VPN exit, a corporate secure web gateway, remote browser isolation, a cloud desktop, or another hosted workload. The provider name does not identify the tenant, the visitor's employer, or whether the request came from a human buyer.

A cloud provider's address blocks are shared across its customers, so even when the provider is named correctly, the tenant is not in the data. "Amazon visited your site 400 times" usually means "something running on AWS did."

VPNs and privacy relays

Consumer VPNs exit through hosting networks, so a visitor on NordVPN or Surfshark resolves to whatever data center the VPN rents.

Corporate VPNs are the odd exception that can help you. If a company sends remote staff traffic back through its own gateway on its own registered block, those visits resolve to the company even from a home office. If the company uses split tunneling or a cloud-hosted security gateway instead, the traffic leaves through the security vendor's network rather than the employer's, and you lose the match.

Apple's iCloud Private Relay works the same way at a much larger scale. Apple publishes its egress list, and an APNIC analysis of Private Relay counted about 20,000 IPv4 subnets and 202,000 IPv6 /64 subnets, run on Akamai, Cloudflare, and Fastly networks. A Safari user with Private Relay turned on shows up as a CDN, never as an employer.

Old, missing, and moved records

The Pomona record is not unusual. Required reassignments are filed when qualifying blocks are handed out and may remain after the customer leaves. Assignments smaller than eight addresses are not required to have customer-specific registrations under ARIN's rule, so they often have no public customer record. And when providers merge or sell, the routing data updates fast while the registry paperwork lags. The researchers behind as2org+ (PAM 2023) built their method specifically because WHOIS-only mappings carry errors and outdated data, including around mergers and acquisitions.

How to read a company match before you act on it

This is the table I'd put in front of anyone building account reports or sales alerts from company IP lookups:

Company type	What it usually means	Safe to do	Don't
Business	The organization's own block, or a filed reassignment	Treat as a candidate account match after checking the record age, network context, and target-account list	Assume a specific person, role, employer, or buying intent
Education	A university or school network	Segment as education, route to that team	Count every student as a lead
Government	An agency network	Route to the public-sector team	Assume a buying intent from one visit
ISP	Home broadband or mobile	Use country and region only	Put "Comcast" in an account report
Hosting	A server, crawler, VPN exit, or relay	Exclude from account reports and visit counts	Treat it as a company visit

My position is stricter than any visitor identification vendor will put in its onboarding deck: drop ISP and hosting matches from account-level reporting entirely. A report that lists "Amazon Technologies" and "Comcast IP Services" as top visiting accounts is worse than a shorter report, because it trains the sales team to ignore the whole thing.

One more check worth adding: when the company on record differs from the network owner and the type is business, you are usually looking at a filed reassignment. That is often the most specific answer the data can give. Check the record date before you trust it.

Questions to ask an IP to company vendor

Do you return a company type, and can I filter on it? If not, you will be cleaning Comcast out of reports by hand.
Where does the name come from? Registry holder, reassignment filing, or your own enrichment. Ask them to show the source for three IPs you pick.
How fresh is it, and can I see a record date? ipinfo and ipgeolocation.io both advertise daily updates. Daily refreshes of a 1998 filing still return a 1998 filing.
Do you flag VPN, relay, and hosting traffic separately? A hosting flag alone does not tell you whether the visit came from a VPN user or a scraper.
What is the match rate on my traffic? Not a benchmark. Send them a week of your own visitor IPs and count how many come back as business, education, or government. ## Where IP to company data is still worth using

Account-based marketing on office-heavy targets is the clean case. In the same BLS telework breakdown, the rate was 17.8% in health care, 19.6% in manufacturing, and 21.4% in public administration, so most of their working hours happen on office networks, which is the only place a company match has a real chance. Sales alerts work when they fire only on business-type matches against a named target list. Security and fraud teams get value from the other end of the table: a hosting or VPN match on a signup form is a signal in itself.

For the examples in this article I used ipgeolocation.io, which returns the company and the network owner as separate fields with a type on each. If you'd rather test against your own traffic without calling an IP to company API on every visit, an IP to company database lets you join a CSV export of visitor IPs offline. ipinfo, ipapi.is, and MaxMind's GeoIP2 ISP database offer comparable data, so test two before you commit.

Before buying anything, export last month's visitor IPs, run them through any IP address company lookup, and count the results by company type. The share that comes back as business, education, or government is the real ceiling on what IP to company data can do for your pipeline. Plan around that number, not the vendor's.

How to Detect In-App Browsers: Instagram, TikTok, Facebook

ABDULLAH AFZAL — Mon, 19 Oct 2026 11:11:50 +0000

You can detect an in-app browser from the user agent with one regex. The one most snippets copy, though, misses Instagram and TikTok on iOS and current Facebook on Android. I ran the common checks against real user agent strings from October 2026 to see which ones still hold.

The short version: every big social app still puts its own token in the user agent, and those tokens are the most reliable signal you have. The generic "this looks like a WebView" heuristics are the part that's rotted. They're fine as a fallback and dangerous as your only check.

TL;DR

An in-app browser is a WebView the host app embeds instead of handing your link to Safari or Chrome. Instagram, Facebook, and TikTok all do it.
Detect it by app token first: Instagram, FBAN / FBAV / FB_IAB and musical_ly / trill_ / AppName/ultralite for TikTok. Treat BytedanceWebview alone as a generic ByteDance-app signal, not proof of TikTok.
The "iPhone UA without Safari/" check misses Instagram and TikTok on iOS. Both now end in Safari/604.1.
The Android ; wv) check misses current Facebook for Android, which no longer sends wv.
Use detection to adapt the page (hide Google sign-in, explain how to open the page in a browser), not to force an escape. Escapes break with app updates. Treat the app token as the primary check and the WebView heuristics as a backstop, then change what the page offers instead of trying to break out. The tokens have been around for years. The heuristics and the escape tricks are what keep failing.

What an in-app browser actually is

An in-app browser is a web view that a native app embeds so links open inside the app instead of in the user's default browser. When someone taps your link in Instagram, Facebook, or TikTok, the page renders in the app's own WebView: WKWebView on iOS, Android System WebView on Android. The host app owns the toolbar, the menu, the cookies, and whether your page is allowed to launch anything.

That last part is the whole problem. An embedded WebView uses app-specific browsing state rather than the visitor's normal Safari or Chrome session, so the visitor often arrives signed out even when they are logged in in the system browser. Cookie persistence and password autofill vary by platform and app. The host app can also inject JavaScript into or inspect the page. Felix Krause showed in 2022 that Instagram and Facebook on iOS inject a pcm.js script into third-party pages opened from links and ads. Meta told him the script aggregates events for ad measurement. Whatever it's for, your page is running code you didn't ship.

In-app browser vs WebView vs Custom Tabs

People use these terms loosely, and the distinction decides what you can detect and what breaks.

WebView (WKWebView, Android WebView): the app embeds a rendering engine and controls it. It can inject scripts and read the page. This is what Instagram, Facebook, and TikTok use, and it's what "in-app browser" usually means.
SFSafariViewController / Chrome Custom Tabs: the app presents a browser-controlled surface in a separate security domain. The host app cannot inspect or modify the page or its cookie storage. Existing sign-in state may be reused depending on the platform, browser, and session configuration. Krause's same test showed SFSafariViewController running none of the injected commands.
System browser: the link leaves the app entirely. WhatsApp did this on iOS in Krause's testing. When this article says "detect an in-app browser", it means the first case. For the OAuth, cookie-isolation, and script-injection problems discussed here, the other two behave more like an external browser.

What breaks inside Instagram, TikTok, and Facebook WebViews

The worst one is sign-in. Google has blocked OAuth inside embedded WebViews since September 30, 2021, and a blocked request gets a disallowed_useragent error. The same post spells out the part that bites web developers: if another app opens your site in a WebView (the Instagram in-app browser, say), your "Sign in with Google" button breaks, and Google's advice is to contact that app's developer. Good luck with Meta. The rule isn't arbitrary either. RFC 8252 says native apps MUST NOT use embedded user-agents for authorization requests.

Sessions are usually cold relative to Safari or Chrome. A visitor who is logged in to your site in the system browser can arrive in the Instagram WebView without that browser session, and autofill behavior may differ.

App handoffs are unreliable. Universal links and store links that open the native app from Safari often just load the mobile web page instead.

And attribution gets messy. Traffic from these apps regularly shows up with no useful referrer, so social clicks get counted as Direct unless your links carry UTM parameters.

None of these are bugs you can fix from your side. What you can do is know when you're in one and stop offering the things that will fail.

The user-agent tokens each app sends

These come from real strings collected in October 2026. The version numbers will be stale by the time you read this. The tokens won't.

App	Platform	Token to match	Example fragment
Instagram	iOS	`Instagram <version>`	`Mobile/23F84 Instagram 444.0.0.31.65 (iPhone18,3; iOS 26_5_2; ...) Safari/604.1`
Instagram	Android	`Instagram <version> Android`	`...; wv) ... Mobile Safari/537.36 Instagram 444.0.0.46.85 Android (35/15; ...)`
Facebook	iOS	`FBAN/FBIOS`, `FBAV/`	`Safari/604.1 [FBAN/FBIOS;FBAV/575.0.0.30.70;...]`
Facebook	Android	`FB_IAB/FB4A`, `FBAV/`	`Mobile Safari/537.36 [FB_IAB/FB4A;FBAV/575.1.0.55.73;IABMV/1;]`
Facebook Lite	Android	`FBAN/EMA`	`[FBAN/EMA;FBLC/es_ES;FBAV/525.0.0.5.102;...]`
TikTok	iOS	`musical_ly_<version>`, `BytedanceWebview`	`Safari/604.1 musical_ly_46.4.0 JsSdk/2.0 ... BytedanceWebview/d8a21c6`
TikTok	Android	`musical_ly_<build>`, `BytedanceWebview`	`musical_ly_2024204030 JsSdk/1.0 ... AppName/musical_ly ... BytedanceWebview/d8a21c6`
TikTok Lite	Android	`AppName/ultralite`, `BytedanceWebview`	`AppName/ultralite app_version/45.0.56 ... BytedanceWebview/d8a21c6`
Messenger	iOS / Android	`FB.../Messenger`	per inapp-spy's rules, not tested here
Threads	iOS / Android	`Barcelona`	per inapp-spy's rules, not tested here
LinkedIn	iOS / Android	`LinkedInApp`	per inapp-spy's rules, not tested here
Snapchat	iOS / Android	`Snapchat`	per inapp-spy's rules, not tested here
X (Twitter)	iOS / Android	`Twitter`	per inapp-spy's rules, not tested here

Two things in that table catch people out. TikTok Lite doesn't send musical_ly at all, so a regex built only on that token misses it. And BytedanceWebview isn't TikTok-only: the same token shows up in other ByteDance apps (the strings with NewsArticle in them), so treat it as a "ByteDance app" match rather than proof of TikTok.

You'll also see IABMV/1 on current Instagram and Facebook strings. I haven't found any documentation for it, so I don't match on it.

Which detection checks actually work (tested October 2026)

I ran three common checks against six current strings, one per app and platform. The first is a token regex of the kind recent guides publish (Instagram|FBAN|FBAV|FB_IAB|musical_ly|Snapchat). The other two are the generic WebView checks that libraries and Stack Overflow answers fall back on.

Real UA (Oct 2026)	Token regex (no `BytedanceWebview`)	Android `; wv)`	iOS "no `Safari/` after `iPhone`"
Instagram iOS 444	Catches	n/a	Misses
Facebook iOS 575	Catches	n/a	Catches, by accident
TikTok iOS 46.4	Catches	n/a	Misses
Instagram Android 444	Catches	Catches	n/a
Facebook Android 575	Catches	Misses	n/a
TikTok Lite Android 45	Misses	Catches	n/a

The token check is the only one that holds up across the board. Add AppName/ultralite for TikTok Lite, and keep BytedanceWebview as a broader ByteDance fallback rather than using it to name the app TikTok.

Why the "iPhone without Safari" check fails now

The idea was sound when it spread: Safari on iOS ends its user agent with Safari/604.1, and older WebViews didn't. Apps have since started copying that suffix. Instagram's iOS string now ends in Safari/604.1, and the TikTok in-app browser's string includes Version/18.7.7 Mobile/15E148 Safari/604.1 before its own tokens.

Facebook iOS only passes because of a quirk. Its bracketed block (FBDV/iPhone17,2;FBMD/iPhone;...) repeats the word iPhone after Safari/604.1, and the regex lookahead matches that second occurrence. That's luck, not detection.

Why the Android `wv` check misses Facebook

Android's default WebView user agent includes a wv token, and the Android team's own guidance is that sites can keep looking for wv unless the app overrides the user agent. Facebook's current builds don't send it. Current FB_IAB/FB4A strings read Build/BP2A.250605.015) with no wv, while older Facebook builds and Facebook Lite still send it. If your analytics rely on wv, traffic from the newer Facebook in-app browser on Android is landing in your "regular Chrome" bucket.

Detecting in-app browsers in JavaScript

MDN's position is that user-agent sniffing is fragile and feature detection is better. For most things I agree. This is the exception: there's no feature you can test for "the host app is injecting scripts and Google will refuse this login". The user agent is the signal the apps chose to send, so use it.

Here's a detection module that checks app tokens first and only falls back to the generic heuristics when nothing named matches. It takes a string, so it runs unchanged on navigator.userAgent in the browser and on the User-Agent header in Node.

// detect-in-app.js
// Order matters: Messenger strings also carry Facebook tokens, so check it first.
const APP_TOKENS = [
  { app: 'messenger', re: /\bFB[\w_]+\/Messenger/i },
  { app: 'instagram', re: /\bInstagram\b/i },
  { app: 'facebook',  re: /\bFBAN\/|\bFBAV\/|\bFB_IAB\//i },
  // Specific TikTok-family tokens first.
  { app: 'tiktok',    re: /musical_ly|\btrill_|AppName\/ultralite/i },

  // This also appears in other ByteDance apps, so do not name it TikTok.
  { app: 'bytedance', re: /BytedanceWebview/i },
  { app: 'threads',   re: /\bBarcelona\b/i },
  { app: 'linkedin',  re: /LinkedInApp/i },
  { app: 'snapchat',  re: /Snapchat/i },
  { app: 'x',         re: /\bTwitter/i },
];

// Backstops only. Both miss current apps (see the table above),
// but they still catch unnamed WebViews from smaller apps.
const GENERIC_WEBVIEW = [
  /;\s?wv\)/i,                              // Android WebView with the default UA
  /\b(iPhone|iPod|iPad)\b(?!.*Safari\/)/i,  // iOS WebView that dropped the Safari token
];

export function detectInAppBrowser(ua) {
  const s = typeof ua === 'string' ? ua : '';
  if (!s) return { inApp: false, app: null, signal: 'no-ua' };

  for (const { app, re } of APP_TOKENS) {
    if (re.test(s)) return { inApp: true, app, signal: 'app-token' };
  }
  if (GENERIC_WEBVIEW.some((re) => re.test(s))) {
    return { inApp: true, app: null, signal: 'generic-webview' };
  }
  return { inApp: false, app: null, signal: 'none' };
}

The signal field is there for your logs. When you see a lot of generic-webview hits with app: null, that's a new app worth adding a token for.

On the page, use the result to change what you offer:

// adapt.js
import { detectInAppBrowser } from './detect-in-app.js';

const APP_NAMES = {
  instagram: 'Instagram',
  facebook: 'Facebook',
  messenger: 'Messenger',
  tiktok: 'TikTok',
  bytedance: 'a ByteDance app',
};

function adaptForInAppBrowser() {
  let result;
  try {
    result = detectInAppBrowser(globalThis.navigator?.userAgent);
  } catch (err) {
    // Detection is a UX nicety; if it throws, render the normal page.
    console.warn('In-app detection failed:', err);
    return;
  }
  if (!result.inApp) return;

  document.documentElement.dataset.inApp = result.app ?? 'unknown';

  // Google returns disallowed_useragent inside WebViews, so don't offer it.
  document.querySelector('#google-signin')?.setAttribute('hidden', '');

  const hint = document.querySelector('#open-in-browser-hint');
  if (hint) {
    const where = APP_NAMES[result.app] ?? 'this app';
    hint.textContent =
      `Opened in ${where}? For sign-in and downloads, use the ••• menu to open this page in your browser.`;
    hint.hidden = false;
  }
}

if (typeof document !== 'undefined') {
  document.readyState === 'loading'
    ? document.addEventListener('DOMContentLoaded', adaptForInAppBrowser)
    : adaptForInAppBrowser();
}

The hint stays generic on purpose. The apps rename their menu items often enough that exact wording goes stale before your copy does.

If you'd rather not maintain the regex list yourself, inapp-spy covers 14 apps and is actively maintained. It also detects Telegram, which it can only do client-side, not from a user agent string. Bowser and ua-parser-js are fine for general browser detection but weren't built for this.

Detecting on the server

Client-side detection is enough for UI tweaks. Server-side is where you want it for everything else: tagging analytics events so Instagram traffic stops hiding in "Direct", choosing a magic-link flow before you render the login page, or just knowing how much of your mobile traffic arrives inside an app.

Express middleware with the token check

The same module works in Node. The middleware below runs the token check on every request, then optionally asks a UA parser for a second opinion. Keep in mind the user agent is client-controlled: fine for UX and analytics, not for anything security-relevant.

// server.js (Node 18+ for global fetch and AbortSignal.timeout)
import express from 'express';
import { detectInAppBrowser } from './detect-in-app.js';

const PARSER_URL = 'https://api.ipgeolocation.io/v3/user-agent';
const API_KEY = process.env.IPGEO_API_KEY; // server-side only, never ship it to the browser

// UA strings repeat heavily (one Instagram build, thousands of visitors),
// so a small in-memory cache saves most parser calls.
const cache = new Map();
const CACHE_MAX = 5000;

async function parserVerdict(ua) {
  if (!API_KEY || !ua) return null;
  if (cache.has(ua)) return cache.get(ua);
  try {
    const res = await fetch(`${PARSER_URL}?apiKey=${API_KEY}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ uaString: ua }),
      signal: AbortSignal.timeout(1500),
    });
    if (!res.ok) throw new Error(`parser HTTP ${res.status}`);
    const data = await res.json();
    const verdict = {
      type: data?.type ?? null, // "Browser Webview", "Mobile App", "Browser", ...
      name: data?.name ?? null,
      engineType: data?.engine?.type ?? null,
    };
    if (cache.size >= CACHE_MAX) cache.delete(cache.keys().next().value);
    cache.set(ua, verdict);
    return verdict;
  } catch (err) {
    // Fail open: the token check already ran, so a slow or failed
    // parser call should never block the request.
    console.warn('UA parser unavailable:', err.message);
    return null;
  }
}

export async function inAppBrowser(req, res, next) {
  const ua = req.get('user-agent') ?? '';
  const local = detectInAppBrowser(ua);

  // Known tokens are sufficient. Use the paid parser only as a fallback.
  const parsed = local.inApp ? null : await parserVerdict(ua);
  const parserSaysInApp = parsed?.type === 'Browser Webview';

  // Either the app token or a Browser Webview result is enough.
  // A generic Mobile App result is not proof that a page is in a WebView.
  req.inApp = {
    inApp: local.inApp || parserSaysInApp,
    app: local.app, // null when only the parser fired
    signal: local.inApp ? local.signal : parserSaysInApp ? 'parser' : 'none',
  };
  next();
}

const app = express();
app.use(inAppBrowser);
app.get('/', (req, res) => res.json(req.inApp));
app.listen(3000);

Without IPGEO_API_KEY set, the parser step is skipped and you get the token check alone, which is the right default.

Using a UA parser's `type` as a second signal

I use ipgeolocation.io's parser here because the User Agent API's type field can identify Browser Webview separately from a plain Browser. The API also returns Mobile App, but that broader value is not used as a parser-only in-app-browser signal because it can describe native app traffic that is not rendering a webpage.Parsing an arbitrary string with POST, as the middleware does, needs a paid plan; the GET endpoint that parses the caller's own user agent is on every plan. Here's the full response for the Instagram iOS string above:

{
  "user_agent_string": "Mozilla/5.0 (iPhone; CPU iPhone OS 26_5_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/23F84 Instagram 444.0.0.31.65 (iPhone18,3; iOS 26_5_2; en_US; en; scale=3.00; 1206x2622; IABMV/1; 1047335181) NW/7 Safari/604.1",
  "name": "Instagram",
  "type": "Mobile App",
  "version": "444.0.0.31.65",
  "version_major": "444",
  "device": {
    "name": "Apple iPhone",
    "type": "Phone",
    "brand": "Apple",
    "cpu": "Unknown"
  },
  "engine": {
    "name": "AppleWebKit",
    "type": "Browser",
    "version": "605.1.15",
    "version_major": "605"
  },
  "operating_system": {
    "name": "iOS",
    "type": "Mobile",
    "version": "26.5.2",
    "version_major": "26",
    "build": "??"
  }
}

I ran the same six strings through it on October 19, 2026:

UA	`type`	`name`
Instagram iOS	`Mobile App`	`Instagram`
Instagram Android	`Browser Webview`	`Chrome Webview`
Facebook iOS	`Browser Webview`	`UIWebView`
Facebook Android (no `wv`)	`Browser Webview`	`Chrome Webview`
TikTok Lite Android	`Browser Webview`	`Chrome Webview`
TikTok iOS	`Browser`	`musical_ly_46.4.0 JsSdk`

Five of six outputs are useful, including the Facebook Android string that the wv check misses. Two limits are worth knowing. On Android it usually reports a generic Chrome Webview rather than naming the host app. It also classifies Instagram iOS as Mobile App and the current TikTok iOS string as a regular browser. The middleware therefore uses known app tokens to identify named apps and accepts only Browser Webview as a parser-only fallback. Neither source alone covers all six.

If you already call /v3/ipgeo for location or ASN data, adding include=user_agent (paid plans) returns the same object in that response at no extra credit cost.

What to do once you know

My take: detect to adapt the page, not to escape the app.

There's a whole genre of escape tricks. On Android, an intent: URL can sometimes hand the page to Chrome. On iOS, people have tried x-safari-https://, app-specific schemes, and even a Shortcuts callback hack. Every one of them depends on undocumented behaviour inside an app whose owner wants you to stay put and ships updates constantly. You find out an escape stopped working when your conversion rate tells you.

Adapting doesn't have that problem. When inApp is true:

Hide "Sign in with Google" and lead with email magic links or passkeys. Google will refuse the OAuth request anyway.
Replace file downloads with "email me the file".
Show one line telling the visitor how to open the page in their browser, using the app's own menu wording.
Put UTM parameters on every link you post to these apps, so the visits stay attributed when the referrer is missing.
Log req.inApp.app with each session. It's the cheapest way to find out how much of your mobile traffic never reaches a real browser. That list keeps working when Instagram ships its next build. The escape hack might not.

How long this will keep working

The tokens are the stable part. The Android team is reducing the default WebView user agent, but it keeps the wv token. Apps that append their own token to the default string keep that token, and apps that replace the string entirely aren't affected at all. Either way, the app tokens survive. User-Agent Client Hints only cover WebViews sending the default string, so they won't replace this for the apps people care about.

What will drift is version formats and the occasional new token, like TikTok Lite's. Re-run your detector against a fresh batch of real strings every quarter. The test harness is ten lines of Node and a list of user agents from your own logs.

Start by logging req.inApp for a week before changing any UI. You'll know which apps actually send you traffic, and whether a missing Google button is worth an afternoon or a sprint.

Peering vs Transit vs IXPs: How Networks Actually Connect

ABDULLAH AFZAL — Thu, 15 Oct 2026 08:21:11 +0000

Peering vs transit comes down to who pays and which routes cross the link. Transit is paid access to the whole internet: a provider carries your traffic anywhere. Peering is a swap: two networks exchange traffic for their own customers, usually for free. An IXP is the building and the switch where that swap often happens.

Here's the part most explanations skip. On the wire, transit and peering look identical: a BGP session over a cable. The difference lives in contracts and route filters that outsiders never see, so every "upstream" or "peer" label in a dataset is a guess. (Not AWS VPC peering, by the way. Same word, different topic.)

TL;DR

Transit: you pay a provider for reachability to the wider internet. Depending on the service, it may send you a default route, selected routes, or a full routing table.
Peering: two networks exchange only their own routes and their customers' routes. Usually no money moves, though paid peering exists.
An IXP is a place, not a third kind of relationship. Networks peer there directly or through a route server, and the route server stays out of the AS path.
The rules are written down. RFC 9234 defines Provider, Customer, and Peer by what each side may send. Break the rules and you get a route leak.
Public relationship data is inferred. In the ASN data used below, the peers list holds every directly connected network, upstreams and customers included. The short version: transit buys reach, peering trades it, and IXPs make trading cheap. Everything you see from outside, in BGP data or an ASN lookup, is an inference about deals nobody publishes. Read the labels as well-informed guesses, and you'll avoid most of the mistakes people make with this data.

Peering vs transit in one table

	IP transit	Settlement-free peering
Who pays	The customer pays the provider, usually on 95th-percentile usage or a committed rate	Nobody pays the other side. Each covers its own port and cross-connect costs
Routes you receive	A default route, selected routes, or a full table, depending on the service	Normally the peer's own prefixes and its customers' prefixes
Routes you send	Your prefixes and your customers' prefixes	Same
What you can reach	The whole internet	Only the peer and the networks behind it
Where it happens	Anywhere the provider has a port	A private cross-connect or an IXP

The "routes you receive" row is the one that matters. Money is the reason the two relationships differ, but route export rules are how the difference actually shows up in the network. A transit provider hands you a path to everywhere. A peer hands you a path to itself and its own customers, and that's all.

That's also why "IP transit vs peering" isn't really a choice between two options. Almost every network that peers also buys transit, because peering only covers the destinations your peers can reach. Transit is the fallback for everything else.

Transit: renting the rest of the internet

What a transit provider actually sells

A transit provider sells two things in one contract. It carries your outbound traffic to any destination, and it announces your prefixes to the rest of the internet so traffic can find its way back. Without the second half, you'd have an outbound-only network.

Billing is usually by 95th-percentile usage: the provider samples your traffic, throws away the top 5% of samples, and bills on the highest one left. Burst for a few hours a month and you don't pay for it. Burst every evening and you do.

Networks that can afford it buy from two or more providers. Two upstreams means one provider's outage doesn't take you offline, and it gives you some bargaining power at renewal time. When you see a network with several upstreams in ASN data, that's what you're looking at. One wrinkle: an upstream in that data is an ASN, not a company, and one company can run several. If the provider vs. ASN distinction is fuzzy, there's a good explainer on how an ISP differs from an ASN.

Tier 1 is a peering club, not a size

A Tier 1 network reaches every destination on the internet without paying anyone for transit. It gets there by peering settlement-free with every other Tier 1, and by selling transit to everyone below. Lumen (AS3356), Arelion (AS1299), and NTT (AS2914) show up on most Tier 1 lists.

The definition is about contracts, not size. A huge eyeball network with millions of subscribers can still be a transit customer somewhere, and that makes it Tier 2. There's no registry that certifies Tier 1 status either. Like everything else in this article, outsiders infer it.

Peering: trading your customers' routes, not the internet

Settlement-free, paid, and why big networks refuse to peer down

Settlement-free internet peering works when both sides gain about equally. Two regional ISPs in the same city peer so their subscribers' traffic stays local instead of crossing a transit provider they're both paying for. Neither sends a bill, because both are saving money.

When the traffic is lopsided, the deal can turn into paid peering. A content network pushing far more traffic into an eyeball network than it receives back may pay for the privilege. It's still peering, because routes are still exchanged only for each side's own customers. Money flows, but the export rules don't change.

The refusal is the interesting part. A large transit network has no reason to peer with a network that could be paying it for transit. Every peer is a customer it didn't get. That's why peering policies at big carriers come with traffic-volume minimums and geographic requirements, and why small networks get told to buy transit.

There's also a performance argument, and it's measured. A 2017 IEEE study by Ahmed et al. compared peering and transit paths at scale and found peering paths outperformed transit paths for 91% of the ASes in their data. Peering paths had smaller propagation delays for more than 95% of ASes, mostly because they're shorter.

Bilateral, private, and route-server peering

Two networks with a lot of traffic between them often set up a private network interconnect (PNI): a dedicated cross-connect in a shared data center, used by nobody else. Everyone else peers over an IXP, either bilaterally (one BGP peering session per partner) or multilaterally through the IXP's route server.

Bilateral sessions give you control, one partner at a time. A route server gives you scale: one session, and you're peering with every other member that uses it.

An IXP is a place, not a relationship

An internet exchange point is a switching fabric inside one or more data centers. Members rent a port, plug in, and set up whatever BGP sessions they agree on with other members. The IXP itself carries traffic between ports at layer 2, and it isn't anyone's peer or anyone's provider. That's why "peering vs transit vs IXP" is a slightly broken question. Peering and transit are relationships. The IXP is where a lot of the peering happens.

What a route server does

Peering bilaterally with 300 members means maintaining 300 sessions. A route server collapses that to one. RFC 7947 defines it: a box that collects routes from the members connected to it and redistributes them to the others. It brokers routes but never forwards traffic. Packets still go directly from one member's router to the other's across the fabric.

Members still choose who they exchange routes with. Route servers usually let a member filter out specific networks, so "multilateral" doesn't have to mean "everyone".

Why IXPs vanish from AS paths

RFC 7947 recommends that a route server not prepend its own AS number to the routes it passes along. In a standards-compliant deployment, the AS path therefore shows the two participant ASes next to each other, much like a direct bilateral session. Legacy or non-compliant route-server behavior can differ.
The IXP switching fabric itself is not an AS hop, so it does not appear in the AS path as another transit network.
The AS path alone usually cannot tell you whether two networks interconnect through a route server, a bilateral session at an exchange, or a private cross-connect. Next-hop information and BGP communities can sometimes provide clues, while PeeringDB and the IXP's own member lists provide useful external evidence.

The rules that make it work: valley-free routing

RFC 9234 turns the export rules into protocol. It defines five BGP Roles (Provider, Customer, Peer, Route Server, and Route Server Client) and what each may send:

A provider may send any route it has to a customer.
A customer may send its provider only routes it originates itself or learned from its own customers.
A peer may send another peer only its own routes and its customers' routes. A route server client follows the same rule toward the route server. Notice what's missing: money. The RFC says outright that its relationship terms "do not necessarily represent business relationships based on payment agreements." They describe what may propagate where. That's the cleanest evidence for the point this article keeps making: the relationship is the route filter, and the bill is just why the filter exists.

Follow those rules and every path has the same shape: up through providers, across at most one peer link, then down through customers. Researchers call that valley-free. A path that goes down and back up, or crosses two peer links in a row, breaks the rules. That's what a route leak is: RFC 9234 defines it as, for example, announcing a route learned from one transit provider to another provider or a peer.

RFC 9234 also adds a BGP Role capability. When both sides advertise roles and the pair does not match one of the permitted relationships, the connection is rejected. If one side does not advertise a role, the session may still be established unless strict mode is enabled. The RFC also defines an "Only to Customer" attribute for routes learned from providers, peers, or route servers, allowing compliant routers to prevent or detect leaks even several hops away.

You never see the contract

CAIDA publishes a public AS relationship dataset, and the paper behind its method puts it plainly: business relationships between networks are typically confidential, so they're inferred from BGP paths. Their 2013 method validated 34.6% of 126,082 inferred links and found the customer-provider inferences 99.6% accurate and the peer inferences 98.7% accurate.

Those are good numbers, but they come with two caveats. First, only about a third of the links could be checked against ground truth. Second, the three-way model is a simplification. CAIDA's follow-up work on complex AS relationships found 4.5% of 90,272 provider-customer links were complex: 1,071 hybrid relationships (transit in one place, peering in another) and 2,955 partial-transit deals. CAIDA calls these lower bounds, because most peering relationships are invisible.

They're invisible because of the export rules above. A peer sends a peering route only to its own customers, never up to its providers. So a peering link appears in public BGP data only if a route collector gets a feed from one of the two peers, or from somewhere in their customer trees. Every dataset that lists peers is undercounting them, and none of them can tell you by how much.

Reading upstreams, downstreams, and peers in ASN data

The ASN lookup is where all of this lands for most developers. CAIDA's AS Rank and Hurricane Electric's BGP Toolkit show relationship data in a browser. For programmatic access, I'll use ipgeolocation.io's ASN endpoint, because one call returns all three lists. It's on the paid plans and costs one credit per lookup.

The NYU example, field by field

curl -sS --max-time 15 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=12&include=peers,upstreams,downstreams"

{
  "asn": {
    "as_number": "AS12",
    "organization": "New York University",
    "country": "US",
    "type": "EDUCATION",
    "domain": "nyu.edu",
    "date_allocated": "1984-07-05",
    "asn_name": "NYU-DOMAIN",
    "allocation_status": "",
    "num_of_ipv4_routes": "12",
    "num_of_ipv6_routes": "1",
    "rir": "ARIN",
    "downstreams": [
      { "as_number": "AS394666", "description": "NYU Langone Health", "country": "US" }
    ],
    "upstreams": [
      { "as_number": "AS3269", "description": "Telecom Italia S.p.A.", "country": "IT" },
      { "as_number": "AS8220", "description": "COLT Technology Services Group Limited", "country": "GB" },
      { "as_number": "AS286", "description": "GTT Communications Inc.", "country": "US" },
      { "as_number": "AS3257", "description": "GTT Communications Inc.", "country": "US" },
      { "as_number": "AS3754", "description": "NYSERNet", "country": "US" },
      { "as_number": "AS3356", "description": "Level 3 Parent, LLC", "country": "US" },
      { "as_number": "AS6461", "description": "Zayo Bandwidth", "country": "US" },
      { "as_number": "AS137", "description": "Consortium GARR", "country": "IT" }
    ],
    "peers": [
      { "as_number": "AS3269", "description": "Telecom Italia S.p.A.", "country": "IT" },
      { "as_number": "AS8220", "description": "COLT Technology Services Group Limited", "country": "GB" },
      { "as_number": "AS286", "description": "GTT Communications Inc.", "country": "US" },
      { "as_number": "AS394666", "description": "NYU Langone Health", "country": "US" },
      { "as_number": "AS3257", "description": "GTT Communications Inc.", "country": "US" },
      { "as_number": "AS3754", "description": "NYSERNet", "country": "US" },
      { "as_number": "AS3356", "description": "Level 3 Parent, LLC", "country": "US" },
      { "as_number": "AS6461", "description": "Zayo Bandwidth", "country": "US" },
      { "as_number": "AS137", "description": "Consortium GARR", "country": "IT" }
    ]
  }
}

Eight upstreams for a university is a lot, and the list explains itself once you read the names. Lumen (AS3356), Zayo, COLT, and Telecom Italia are commercial transit. NYSERNet is New York's research and education network, and GARR is Italy's. GTT appears twice, as AS286 and AS3257: one company, two ASNs. The single downstream is NYU Langone Health, a separate network that routes through NYU.

Two field quirks will bite you. as_number carries the AS prefix, so it's a string. num_of_ipv4_routes and num_of_ipv6_routes are strings too, despite being counts.

Why your upstream is also in your peer list

Look at peers again. It has nine entries, and every one of them is either an upstream or the downstream. The docs' field reference describes peers as directly connected ASes, and the live data matches that exactly. In this dataset, peers means "neighbors", not "settlement-free peers".

To find lateral peers, subtract the upstreams and downstreams. For NYU that leaves nothing. That doesn't prove NYU has no peers. Given the previous section, it more likely means none of its peering links are visible from where the data was collected.

Lumen's record shows how far the labels drift at the top of the hierarchy. AS3356 lists 6,544 downstreams and 185 upstreams. Its peers list opens with Gilead Sciences, Aflac, SpaceX, and ExxonMobil, which look a lot more like transit customers than settlement-free peers. And a Tier 1 network shouldn't have any upstreams at all. Either the inference is reading Lumen's peers as providers, or some of those links are the hybrid relationships CAIDA describes. I don't know which method produces these lists, and the docs don't say. From the outside, you can't tell the two apart.

This script runs the subtraction for any list of ASNs:

import os
import sys

import requests

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


def neighbor_sets(asn):
    """Return (upstreams, downstreams, lateral peers) as sets of AS numbers, or None."""
    try:
        resp = requests.get(
            API_URL,
            params={"apiKey": API_KEY, "asn": asn, "include": "peers,upstreams,downstreams"},
            # A Tier 1 record lists thousands of neighbors, so allow a long read.
            timeout=(2.0, 15.0),
        )
        resp.raise_for_status()
        record = resp.json().get("asn") or {}
    except requests.HTTPError as exc:
        # Do not print the exception object: it may contain the URL and API key.
        status = exc.response.status_code if exc.response is not None else "unknown"
        print(f"AS lookup for {asn} failed: HTTP {status}", file=sys.stderr)
        return None
    except requests.RequestException as exc:
        # Log the exception type only, never the request URL.
        print(
            f"AS lookup for {asn} failed: {type(exc).__name__}",
            file=sys.stderr,
        )
        return None
    except ValueError:
        print(f"AS lookup for {asn} returned invalid JSON", file=sys.stderr)
        return None

    def numbers(key):
        # A set dedupes on as_number, so one AS listed twice is counted once.
        return {n.get("as_number") for n in (record.get(key) or []) if n.get("as_number")}

    upstreams, downstreams = numbers("upstreams"), numbers("downstreams")
    # `peers` holds every neighbor, so what's left after both subtractions is the lateral set.
    return upstreams, downstreams, numbers("peers") - upstreams - downstreams


if __name__ == "__main__":
    if not API_KEY:
        sys.exit("Set IPGEO_API_KEY before running this.")
    for asn in sys.argv[1:] or ["12"]:
        result = neighbor_sets(asn)
        if result is None:
            continue
        up, down, lateral = result
        print(f"{asn}: {len(up)} upstreams, {len(down)} downstreams, {len(lateral)} lateral peers")

Save it as neighbors.py and run python neighbors.py 12 3356. AS12 comes back as 8 upstreams, 1 downstream, and 0 lateral peers. The lateral count is the closest this data gets to "who does this network peer with". Read it as a floor, not a total.

The ASN Pivot Playbook covers the same arrays from the investigation side: which pivots carry weight and which don't.

What this tells you about a network

A few readings hold up even with inferred data:

One upstream, no downstreams: a stub network. It goes down when that one provider does, which matters if you depend on it.
Hundreds or thousands of downstreams: it sells transit. An IP announced by that ASN may belong to the transit provider itself or sit in a customer's space announced on its behalf, so check routes before blaming the provider.
Zero upstreams: a Tier 1, or a gap in visibility. And as Lumen's 185 shows, upstream counts near the top of the hierarchy tell you less than they seem to. The relationship lists also pair well with the type field, covered in Classify an IP by ASN Type: Hosting, Business, ISP. A HOSTING network with thousands of downstreams is a different animal from a HOSTING network with none.

Treat every upstream, downstream, or peer label as a dated hint, not a fact about a contract. Re-pull it before a decision depends on it, and when two datasets disagree about a relationship, assume both are partly right.

What Is CGNAT and Why It Breaks IP Geolocation

ABDULLAH AFZAL — Tue, 13 Oct 2026 14:21:40 +0000

Carrier-grade NAT (CGNAT) lets one public IPv4 address stand in for hundreds of people at once. It's why a phone in one town can geolocate to a city 200 km away, and why a rate limit aimed at one abuser can lock out a crowd of mobile users who did nothing.

Most code that touches IP data quietly assumes one IP is one place and one IP is one user. CGNAT breaks both. A 2026 measurement study of four geolocation databases put the median error for mobile connections at 179 to 207 km. On fixed broadband, the same databases were off by 3 to 16 km.

TL;DR

CGNAT is NAT run by your ISP or mobile carrier, so many unrelated customers share one public IPv4 address. The carrier side uses 100.64.0.0/10, the shared address space reserved by RFC 6598.
On mobile networks, the public IP reflects the carrier's gateway, not the phone. Median geolocation error was 179 to 207 km on mobile versus 3 to 16 km on fixed lines.
Country-level lookups still hold: fewer than 1% of observations landed in the wrong country.
Cloudflare found CGNAT addresses get rate-limited three times more often than other IPs, even though they carry proportionally less bot traffic.
On a CGNAT IP, trust the country, treat the city as a hint, and never treat the address as a user ID. CGNAT exists because IPv4 ran out, and it isn't going away soon. If your app geolocates, rate-limits, or bans by IP, assume a good part of your mobile traffic arrives through shared addresses. Country decisions survive that. City decisions and per-IP identity are where things go wrong.

What is CGNAT?

CGNAT (carrier-grade network address translation, also called large-scale NAT) is address translation performed inside the ISP's network rather than only on your home router. The carrier gives each customer a non-routable address, then maps traffic from many customers onto a small pool of shared public IPv4 addresses before it reaches the internet.

The usual setup stacks two translations. Your router maps 192.168.1.x devices to its WAN address, which under CGNAT is also non-routable, so the carrier translates it again into a public address other customers share. Engineers call this NAT444, after the three address realms involved.

Carriers do it because IPv4 has about 4.3 billion addresses and the regional registries had run through their free pools by the early 2010s, as Cloudflare's write-up on CGNAT detection explains. With IPv6 rollout slow, CGNAT lets an operator keep adding subscribers on addresses it already holds.

CGNAT vs NAT

	Home NAT	CGNAT
Who runs it	Your router	Your ISP or mobile carrier
Who shares one public IP	Devices in one household	Many unrelated customers
Port forwarding	Works	Not possible from your own router

Only the right column is a problem for your app. Home NAT puts a family behind one IP. CGNAT puts strangers behind one IP, and they don't have to live in the same city.

The CGNAT IP range: 100.64.0.0/10

RFC 6598 (April 2012) reserved 100.64.0.0/10, about 4.2 million addresses from 100.64.0.0 to 100.127.255.255, as "Shared Address Space" between a carrier's NAT and customer equipment. The RFC 1918 ranges were off the table because subscribers already use 10.x and 192.168.x at home, and the same address on both sides of a router breaks things.

If your router's WAN address falls anywhere from 100.64 to 100.127, you're behind CGNAT.

How one public IP ends up serving hundreds of users

The carrier's NAT tells customers apart by port, not by address. Every outbound connection gets a port on a shared public IP, and the NAT remembers which subscriber owns which port. One IPv4 address has 65,535 ports to hand out, so it can carry many households' connections at the same time. Cloudflare puts the count behind a single IPv4 address at hundreds, and sometimes thousands, of users.

Mobile networks add distance to the sharing. Your phone's traffic doesn't touch the public internet at the cell tower. The carrier carries it across its own network to a gateway, and that's where it gets a public source address. The IAB's workshop report on IP address geolocation describes the effect directly: a device can be in one place while its traffic exits through a gateway in a different region.

The sharing isn't spread evenly. Cloudflare's analysis found the highest ratios of internet users to IP addresses across large parts of Africa and South Asia, and the lowest in Australia, Canada, Europe, and the US. African networks also showed the most distinct user agents per CGNAT address. The regions with the fewest IPv4 addresses squeeze the most people behind each one.

It isn't only a mobile problem. Cloudflare describes CGNAT across broadband ISPs as well as mobile networks, and the IAB report lists satellite networks alongside mobile CGNAT among the biggest challenges for publishing accurate location data.

Why mobile users geolocate hundreds of kilometers away

An IP geolocation database maps address ranges to places. For a CGNAT range, the only stable fact about the address is where the carrier's gateway sits, so that's what ends up in the database. The IAB report puts it in one line: geolocating the IP "identifies the gateway, not the user."

The Lost in the Prefix study measured how far that drifts. Researchers at Virginia Tech compared four databases against 37,302 observations with known locations, drawn from RIPE Atlas probes and UNICEF Giga school connectivity tests across 175 countries. Median errors:

Database	Mobile networks	Fixed networks
IPinfo	179 km	8 km
IP2Location	186 km	3 km
MaxMind GeoLite2	204 km	13 km
DB-IP	207 km	16 km

The authors trace it to prefix granularity. About 70% of the database prefixes covering mobile networks span more than 100 km, so one database row has to pick one city for people spread across a region. In Africa, 66 to 72% of lookups missed by more than 100 km. In Asia, 53 to 61% did. Europe stayed between 9 and 20%.

The finding I'd underline: all four databases failed at similar rates on mobile, and the paper concludes that switching providers doesn't get you out of it. The MaxMind entry is GeoLite2, the free tier, so it isn't MaxMind's best data. Still, four independently built datasets agreeing on the same misses points at network structure, not at one vendor's sloppiness.

The IAB report adds a nastier edge case: phones near a national border whose IP geolocation keeps flipping between two countries.

What still works: the country

Wrong-country results were rare in the same study, at fewer than 1% of observations per provider. That makes IP-derived country useful for things like currency defaults, content catalogs, and other coarse regional decisions even where city accuracy falls apart. For tax, compliance, or legal-jurisdiction decisions, treat the IP country as one input rather than proof of where the person legally resides or which rules apply.

One IP is not one user

Location is the visible failure. Identity is the quieter one.

Cloudflare built a classifier to spot CGNAT addresses across its network, then looked at how customer security rules treated them. CGNAT IPs were rate-limited three times more often than non-CGNAT IPs. Their traffic wasn't especially bot-heavy, either: the mean bot rate was 7% for CGNAT addresses against 13.1% for everything else. Real people got throttled because they happened to share an address.

The same mistake shows up in ordinary app code:

Per-IP signup or trial caps. "Three accounts per IP" quietly becomes "three accounts per carrier gateway" for mobile users.
IP bans. Banning one abuser's mobile IP bans everyone currently behind it, and the abuser gets a different address the next time their connection is reassigned.
Per-IP login throttling. A credential-stuffing defense keyed only on IP can lock out unrelated users who share the address.
Impossible-travel rules. A user whose phone IP geolocates 200 km from their home broadband IP an hour later hasn't gone anywhere.
Unique-visitor counts. Counting distinct IPs undercounts people on mobile networks. An IP address was never a user ID. It was a convenient approximation that held up while one household got one address. CGNAT just made the shortcut visible.

How to tell if an IP is behind CGNAT

From the user's side

Check your router's WAN address. Anything from 100.64.0.0 to 100.127.255.255 means your ISP is doing CGNAT.

A traceroute tells the same story from the other direction. Cloudflare's detection pipeline treats a 100.64.0.0/10 hop between your first private hop and your public IP as a strong CGNAT indicator, and it ran that test from more than 9,000 RIPE Atlas probes.

From your server

Nothing in an HTTP request says "this is CGNAT." You infer it from signals:

The IP's ASN belongs to an ISP or mobile carrier, not a hosting or cloud provider.
Reverse DNS sometimes gives it away. Cloudflare matched PTR records containing cgnat, cgn, or lsn.
One IP shows a wide spread of user agents and devices over a day. That diversity is one of the strongest signals in Cloudflare's classifier.
Your geolocation provider labels the connection as mobile. That last one is where I'd start, because it's a single field. Disclosure: I work on ipgeolocation.io, so it's the provider I know best. On paid plans, its IP Geolocation API returns network.connection_type and asn.type, and include=geo_accuracy adds an accuracy_radius in kilometers plus a confidence of high, medium, or low. When I looked up ranges from T-Mobile USA, Verizon, AT&T, and Safaricom on October 13, 2026, all of them came back with connection_type: "Mobile" and asn.type: "ISP". Not every range carries the label: two other carrier ranges came back with an empty value. Read "Mobile" as a positive signal and an empty string as unknown, not as proof of a fixed line.

Read the radius carefully. The T-Mobile range came back in Fort Worth, Texas, with a 4.9 km radius and high confidence. That's the provider's estimate for the range. It can't tell you whether the phone using that address right now is in Fort Worth or 200 km away, because nothing upstream of the carrier's gateway is visible from outside the carrier. On a mobile range, a tight radius means "the gateway is here," not "the user is here." So treat the connection type as the switch: once a lookup says mobile, apply the country-yes, city-maybe rule whatever the radius says.

What your app should trust on a CGNAT IP

Here's how I'd split decisions when the traffic might be shared:

Use case	Safe on a CGNAT IP?	Do this instead
Currency, pricing region, content catalog	Yes	Use the country
Tax or legal jurisdiction	Not by IP alone	Use IP country as supporting context and confirm with the authoritative account, billing, or residency information your policy requires
City-level personalization	As a hint only	Fall back to region, or let the user pick
City-level geofencing	No	Use device location with consent
Distance and impossible-travel rules	Not on mobile	Relax thresholds for mobile connections, or skip the check
Rate limiting	Not by IP alone	Key on account, session, API token, or device
Bans and blocklists	Avoid on carrier ranges	Ban the account or device
Unique users in analytics	No	Count sessions or accounts

The pattern is short. Anything that needs a country is fine. Anything that needs a city or a person needs a second signal.

That 100.64.x.x address in your logs

If a 100.64.x.x address turns up where you expected a client IP, it isn't anyone's public address. The usual causes:

You read the wrong X-Forwarded-For entry and grabbed an internal hop.
Overlay networks such as Tailscale assign device addresses from 100.64.0.0/10, so traffic from inside a tailnet carries them.
Your own infrastructure, or a provider's, uses the range internally. A geolocation lookup won't rescue it. ipgeolocation.io answers 100.64.1.1 with HTTP 423 and a message that it's a bogon address, which is the right answer: there's no location to give.

The obvious filter for this is if ip.is_private: skip. That lets CGNAT addresses straight through, because Python's ipaddress module returns False for is_private on 100.64.0.0/10. Its documentation calls out the exception: that range is neither private nor global. Check is_global instead.

import ipaddress
import logging
from typing import Optional

logger = logging.getLogger(__name__)


def client_ip(xff_header: Optional[str], remote_addr: str, trusted_hops: int = 1) -> Optional[str]:
    """Return the client IP only when the app is reached through the expected proxy path.

    This hop-count approach is safe only when every request reaches the app through
    exactly trusted_hops proxies and clients cannot connect to the origin directly.
    If your topology has multiple paths, validate proxy IPs/CIDRs instead.
    """
    chain = [hop.strip() for hop in (xff_header or "").split(",") if hop.strip()]
    chain.append(remote_addr)

    if len(chain) <= trusted_hops:
        return None

    candidate = chain[-(trusted_hops + 1)]
    try:
        addr = ipaddress.ip_address(candidate)
    except ValueError:
        # "unknown", "ip:port", or garbage. Don't guess at a location.
        logger.debug("Unparseable client IP %r in X-Forwarded-For", candidate)
        return None

    # Some stacks hand you ::ffff:100.64.1.1 instead of the IPv4 form.
    if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped:
        addr = addr.ipv4_mapped

    # is_private is False for 100.64.0.0/10. is_global rejects shared
    # address space along with RFC 1918, loopback, and link-local.
    return str(addr) if addr.is_global else None

It returns None instead of guessing, so the caller can skip the lookup and fall back to defaults. That's fail-open by design: a missing location should never block a request. Set trusted_hops only when every request follows the same proxy path and the origin cannot be reached directly. Too low and you geolocate your own load balancer; too high, or allowing a direct path to the origin, can make you trust an address the client supplied. Where possible, configure your framework or proxy layer with explicit trusted proxy IPs/CIDRs instead of parsing X-Forwarded-For yourself.

Where this leaves you

If you run a network, the fix that helps everyone downstream is a geofeed: an RFC 8805 file that maps each regional address pool to where it actually reaches the internet. Our position paper for the IAB workshop argued for region-specific entries on large prefixes and a standard attribute for the last-mile connection type (mobile, fiber, satellite, VPN), so consumers can tell a gateway estimate from a real location. If you only consume IP data, decide per feature whether you need the city at all. Most of the time the country is enough, and the country is the part CGNAT leaves alone.

Enrich Kafka Events With IP Location and ASN at Ingest

ABDULLAH AFZAL — Mon, 12 Oct 2026 16:38:57 +0000

Kafka IP enrichment belongs at ingest: a consumer stamps each event with country, city, and ASN before it lands, so no query ever re-joins raw IPs against today's data. The part every example I found skips is the bill.

The usual version calls an IP geolocation API inside the per-message loop. Addresses repeat constantly on a busy topic, so you pay for every repeat, inherit the API's latency on every event, and turn the first slow response into consumer lag.

This post builds the other version in Python: batch a poll, dedupe the IPs, send the misses in one bulk request, produce, then commit. In the test run behind this post, 62 seeded events turned into one bulk request for 5 distinct public IPs, billed 5 credits. There's also a path that swaps the API for a local MMDB file once volume makes that cheaper.

TL;DR

Run the enricher as its own consumer group between events.raw and events.enriched, with a dead-letter topic for records you can't parse.
Price IP enrichment by distinct IPs per cache window, not by events. Duplicates in a bulk request are billed; private addresses are not.
Classify IPs locally first, dedupe each poll, and send cache misses in one bulk request of up to 50,000 addresses.
Commit offsets only after the enriched batch is acknowledged. Ship lookup failures with a status field instead of stalling the partition.
The API and a combined location + ASN MMDB return the same contract fields in different shapes. Normalize both into one event contract. The enricher below is about 270 lines of Python across nine blocks. It runs against plain Apache Kafka or Redpanda, keeps per-user ordering, and survives a dead API by shipping events marked unavailable instead of blocking. Every block ran against a real Kafka broker, and the API path ran against the live lookup endpoint.

Where the enricher sits

The enricher is a consumer group with one job. It reads raw events, adds geo, asn, and an enrichment block, and writes them to a second topic. Anything that isn't JSON goes to a third topic untouched.

producers ──> events.raw ──> [ ip-enricher group ] ──> events.enriched ──> sinks
                                       │
                                       └──> events.dlq   (unparseable records)

I've made the case for log enrichment at write time instead of query time twice already, once for nginx access logs and once for Elasticsearch ingest pipelines. The short version: an IP's network owner and location drift, so an event should carry the answer that was true when it happened. Kafka adds the reason that matters here. Every downstream consumer, sink, and replay reads the enriched topic, so the lookup happens exactly once per event instead of once per reader.

Create the three topics. Match the raw topic's partition count on the enriched one, so a consumer instance's output lines up with its input:

kafka-topics.sh --bootstrap-server localhost:9092 --create --topic events.raw --partitions 3
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic events.enriched --partitions 3
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic events.dlq --partitions 1

The raw events in this post look like {"event_id": "e1", "user": "u1", "path": "/checkout", "client_ip": "91.128.103.196"}, keyed by user.

Kafka IP enrichment is priced by distinct IPs

An IP lookup API bills per address looked up, so events per second is the wrong number to plan with. The number that matters is how many distinct addresses you see per cache window.

A rough monthly bill, in credits, at one credit per address:

credits/month ≈ distinct IPs per TTL window × (30 ÷ TTL in days) × instances that see the same IP

At a 24-hour TTL with one consumer instance, 5,000 distinct IPs a day is 150,000 credits a month, which is exactly the entry paid tier.

About 33,000 a day is roughly 1,000,000 credits. The last factor is the one people miss. Each consumer instance has its own cache, so an address whose events spread across partitions gets looked up by every instance that sees it.

Three details from the live bulk endpoint shape the code below. Duplicate addresses inside one request are billed again, so dedupe before you send. Private and bogon addresses cost nothing and come back as an error entry, so filter them locally anyway and skip the round trip. And the bulk endpoint needs a paid key: a free key gets a 401, and free responses also omit asn.type, which is the field that tells HOSTING from ISP.

	API bulk + TTL cache	Local MMDB file
Cost	One credit per distinct IP per window	A fixed licence, nothing per lookup
Lookup	One HTTPS round trip per batch with misses	In-process, no network
Freshness	Whatever the API answers today	The build you downloaded, daily or weekly
Ops work	An API key	Shipping a large file to every node and reloading it
Pick it when	You're under about 1M credits a month	You're above that, or the stream tier has no internet egress

I can't give you the exact crossover, because database licences are quote-based. What I'd do: start on the API, watch the credit counter for a week of real traffic, and ask for a database quote the month you pass a million.

The enriched event contract

This is what lands on events.enriched for one real event from the test run:

{
  "event_id": "e1",
  "user": "u1",
  "path": "/checkout",
  "client_ip": "91.128.103.196",
  "geo": {"country_code": "SE", "city": "Stockholm", "lat": 59.4051, "lon": 17.9551},
  "asn": {"number": 1257, "org": "Tele2 Sverige AB", "type": "ISP"},
  "enrichment": {"status": "ok", "source": "api", "as_of": "2026-10-12T12:50:10+00:00"}
}

Coordinates are normalized to floats and the AS number to an integer. The API sends these values as strings, while the MMDB may return numeric values directly. enrichment.status is one of ok, not_found, private, invalid_ip, no_ip, or unavailable, so a downstream query can tell "no data" from "lookup failed". as_of is the lookup time on the API path and the database build date on the MMDB path. That field is what makes an ingest-time answer defensible six months later.

The lookup returns far more than the contract keeps. Here's the complete record the API returns for that address, for reference:

Full API record for 91.128.103.196

{
  "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": "\ud83c\uddf8\ud83c\uddea"
  },
  "country_metadata": {
    "calling_code": "+46",
    "tld": ".se",
    "languages": [
      "sv-SE",
      "se",
      "sma",
      "fi-SE"
    ]
  },
  "network": {
    "connection_type": "",
    "route": "91.128.0.0/14",
    "is_anycast": false,
    "is_cdn": false,
    "cdn_provider_name": ""
  },
  "currency": {
    "code": "SEK",
    "name": "Swedish Krona",
    "symbol": "kr"
  },
  "asn": {
    "as_number": "AS1257",
    "organization": "Tele2 Sverige AB",
    "country": "SE",
    "type": "ISP",
    "domain": "tele2.se",
    "date_allocated": "2002-09-19",
    "rir": "RIPE"
  },
  "company": {
    "name": "Tele2 Sverige AB",
    "type": "ISP",
    "domain": "tele2.se"
  },
  "time_zone": {
    "name": "Europe/Stockholm",
    "offset": 1,
    "offset_with_dst": 2,
    "current_time": "2026-10-12 14:39:15.199+0200",
    "current_time_unix": 1791808755.199,
    "current_tz_abbreviation": "CEST",
    "current_tz_full_name": "Central European Summer Time",
    "standard_tz_abbreviation": "CET",
    "standard_tz_full_name": "Central European Standard Time",
    "is_dst": true,
    "dst_savings": 1,
    "dst_exists": true,
    "dst_tz_abbreviation": "CEST",
    "dst_tz_full_name": "Central European Summer Time",
    "dst_start": {
      "utc_time": "2026-03-29 TIME 01:00",
      "duration": "+1.00H",
      "gap": true,
      "date_time_after": "2026-03-29 TIME 03:00",
      "date_time_before": "2026-03-29 TIME 02:00",
      "overlap": false
    },
    "dst_end": {
      "utc_time": "2026-10-25 TIME 01:00",
      "duration": "-1.00H",
      "gap": false,
      "date_time_after": "2026-10-25 TIME 02:00",
      "date_time_before": "2026-10-25 TIME 03:00",
      "overlap": true
    }
  }
}

That record is about 1.8 KB. Asking for only the contract's fields with the fields parameter cuts it to about 240 bytes, which matters at 50,000 addresses per request: by my per-record measurements, roughly 92 MB of response versus 12 MB.

The API and a combined location + ASN MMDB carry the contract fields under different paths and types. This is the mapping the normalizer handles, and the reason a consumer written against one source silently produces empty fields on the other:

Contract field	API (`/v3/ipgeo-bulk`)	MMDB file
`geo.country_code`	`location.country_code2`	`location.country.code2`
`geo.city`	`location.city`	`location.city.name.en`
`geo.lat / geo.lon`	`location.latitude` (string)	`location.coordinates.latitude` (number)
`asn.number`	`asn.as_number`, `"AS1257"`	`asn.as_number` (1257)
`asn.org`	`asn.organization`	`asn.organization`
`asn.type`	`asn.type` (paid plans only)	`asn.type`

Building the consumer

You'll need pip install confluent-kafka requests cachetools maxminddb and Python 3.9 or newer. The blocks below go into one file, enricher.py, in order. Each one repeats the imports it uses, so you can read them in isolation. It was tested against Apache Kafka 4.2.2 in KRaft mode. The client is Confluent's Python client, which talks to Kafka and Redpanda alike.

Classify every IP before you spend anything

import ipaddress
import logging
import os

log = logging.getLogger("ip-enricher")

BOOTSTRAP = os.environ.get("KAFKA_BOOTSTRAP", "localhost:9092")
RAW_TOPIC = os.environ.get("RAW_TOPIC", "events.raw")
ENRICHED_TOPIC = os.environ.get("ENRICHED_TOPIC", "events.enriched")
DLQ_TOPIC = os.environ.get("DLQ_TOPIC", "events.dlq")
API_KEY = os.environ.get("IPGEO_API_KEY")  # bulk lookups need a paid key; never hardcode it


def classify_ip(raw):
    """Return (cache_key, status). status is None when the IP is worth looking up."""
    if not isinstance(raw, str) or not raw.strip():
        return None, "no_ip"
    try:
        ip = ipaddress.ip_address(raw.strip())
    except ValueError:
        return None, "invalid_ip"
    # ::ffff:8.8.8.8 and 8.8.8.8 are the same host. Key them the same way.
    if ip.version == 6 and ip.ipv4_mapped:
        ip = ip.ipv4_mapped
    if not ip.is_global:
        # RFC 1918, CGNAT, loopback, link-local. Nothing to look up, nothing to pay for.
        return str(ip), "private"
    return str(ip), None

is_global does the heavy lifting. It's False for RFC 1918 ranges, CGNAT's 100.64.0.0/10, loopback, link-local, and the documentation ranges, which is everything you'd otherwise pay a round trip to hear rejected. The IPv4-mapped unwrap matters more than it looks: a server listening on :: sees IPv4 clients as ::ffff:8.8.8.8, and without the unwrap the same client gets two cache entries and two credits.

One bulk request per batch

I'm using ipgeolocation.io for bulk IP lookups because its bulk lookup endpoint docs cover the shape this needs (up to 50,000 addresses per POST) and the same data ships as an MMDB file, so both paths in this post produce identical events. MaxMind and IP2Location also sell both an API and a downloadable database, and the cost model above applies to them unchanged.

The session, cache, and error types come first:

import requests
from cachetools import TTLCache
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

BULK_URL = "https://api.ipgeolocation.io/v3/ipgeo-bulk"
BULK_MAX = 50_000  # hard per-request limit; one more and the API returns 400
FIELDS = ("ip,location.country_code2,location.city,location.latitude,"
          "location.longitude,asn.as_number,asn.organization,asn.type")

# Location and network ownership drift slowly, so a day is a sane TTL. Each entry costs
# about 1 KB in CPython, so 100,000 entries is roughly 100 MB. Size it to distinct IPs per day.
cache = TTLCache(maxsize=100_000, ttl=24 * 3600)

session = requests.Session()
# Retry connection failures and explicit gateway errors, but never a read
# failure after the POST was sent: the server may already have processed it.
session.mount("https://", HTTPAdapter(max_retries=Retry(
    total=None,
    connect=2,
    read=0,
    status=2,
    other=0,
    backoff_factor=0.5,
    status_forcelist=(502, 503, 504),
    allowed_methods=frozenset({"POST"}),
)))


class FatalLookupError(RuntimeError):
    """Bad key or a free-plan key. Stop the consumer rather than ship blank events forever."""


class LookupFailed(RuntimeError):
    """Transient failure. The caller fails open."""

A 100,000-entry cache is my starting point, not a rule. Size maxsize to the distinct addresses you see per TTL window, because an evicted entry is a re-bought one.

import ipaddress
import logging
import requests

log = logging.getLogger("ip-enricher")


def bulk_lookup(ips, api_key):
    """ips: distinct public IPs missing from the cache. Returns {ip: record or None}."""
    found = {}
    for start in range(0, len(ips), BULK_MAX):
        chunk = ips[start:start + BULK_MAX]
        try:
            resp = session.post(BULK_URL, params={"apiKey": api_key, "fields": FIELDS},
                                json={"ips": chunk}, timeout=(2, 10))
        except requests.RequestException as exc:
            # requests puts the full URL, apiKey included, in exception text. Don't log it.
            raise LookupFailed(type(exc).__name__) from None
        if resp.status_code == 401:
            raise FatalLookupError(resp.text[:200])
        if resp.status_code != 200:
            raise LookupFailed(f"HTTP {resp.status_code}: {resp.text[:200]}")
        log.info(
            "bulk: %d ips, %s credits",
            len(chunk),
            resp.headers.get("X-Credits-Charged"),
        )

        # Match valid results by canonical IP rather than depending on response order.
        # IPv6 may be returned in a different textual form from the request.
        for rec in resp.json():
            if not isinstance(rec, dict) or "ip" not in rec:
                continue

            try:
                returned = ipaddress.ip_address(rec["ip"])
                if returned.version == 6 and returned.ipv4_mapped:
                    returned = returned.ipv4_mapped
                found[str(returned)] = rec
            except ValueError:
                continue

        # Rejected or missing records become not_found.
        for ip in chunk:
            found.setdefault(ip, None)

    return found

Two response details are worth handling explicitly. A rejected entry contains only a message and no ip field, while a valid IPv6 address may be returned in a different textual form from the one you sent. The code therefore canonicalizes returned IPs with ipaddress and maps valid records by address instead of depending on array position.

Third, the except clause is there because requests puts the full URL into its exception text, query string and apiKey included. Log that message once on a connection error and your key is in your log pipeline. I confirmed it by pointing the client at a closed port: the ConnectionError text contained the key.

Normalize, then resolve with a fail-open path

def _float(value):
    try:
        return float(value)
    except (TypeError, ValueError):
        return None


def _asn_int(value):
    # The API sends "AS1257"; the MMDB file sends "1257". Store one integer type.
    digits = str(value or "").upper().removeprefix("AS")
    return int(digits) if digits.isdigit() and int(digits) > 0 else None


def _contract(country, city, lat, lon, asn):
    return {
        "geo": {"country_code": country or None, "city": city or None,
                "lat": _float(lat), "lon": _float(lon)},
        "asn": {"number": _asn_int(asn.get("as_number")),
                "org": asn.get("organization") or None,
                "type": asn.get("type") or None},
    }


def from_api(rec):
    loc = rec.get("location") or {}
    return _contract(loc.get("country_code2"), loc.get("city"),
                     loc.get("latitude"), loc.get("longitude"), rec.get("asn") or {})


def from_mmdb(rec):
    # Same data, different paths: nested names, a coordinates group, unprefixed AS numbers.
    loc = rec.get("location") or {}
    coords = loc.get("coordinates") or {}
    city = ((loc.get("city") or {}).get("name") or {}).get("en")
    return _contract((loc.get("country") or {}).get("code2"), city,
                     coords.get("latitude"), coords.get("longitude"), rec.get("asn") or {})

_contract is the single place the event shape is defined. Both sources feed it, so a schema change happens once. The > 0 check on AS numbers is deliberate: some records come back as AS0 with empty organization fields, and storing 0 as if it were a real network causes confusing joins later.

from datetime import datetime, timezone


def resolve_api(keys, api_key):
    """keys: set of public IPs. Returns {ip: (status, data, as_of)}."""
    now = datetime.now(timezone.utc).isoformat(timespec="seconds")
    out = {ip: cache[ip] for ip in keys if ip in cache}
    misses = [ip for ip in keys if ip not in out]
    if not misses:
        return out
    try:
        for ip, rec in bulk_lookup(misses, api_key).items():
            out[ip] = cache[ip] = (("ok", from_api(rec), now) if rec
                                   else ("not_found", None, now))
    except LookupFailed as exc:
        # Fail open: the events still ship, marked unavailable. Failures are never cached.
        log.warning("lookup failed for %d ips, shipping un-enriched: %s", len(misses), exc)
        out.update({ip: ("unavailable", None, now) for ip in misses})
    return out

This is the whole caching policy. Hits skip the network. Misses go out in one call. A transient failure marks the affected addresses unavailable for this batch only, and failures are never cached, so the next batch tries again.

Failing open is the right default for analytics and observability topics, where a gap is better than a stall. If this topic feeds a fraud decision, you'd rather pause than ship blanks, and that's a different design.

Process a batch, then commit

import json


def process_batch(msgs, producer, on_delivery, resolve, source):
    """Parse, dedupe, resolve once per distinct IP, then produce one enriched event per message."""
    parsed = []
    for msg in msgs:
        try:
            event = json.loads(msg.value())
            if not isinstance(event, dict):
                raise ValueError("not a JSON object")
        except (TypeError, ValueError):
            # Unparseable records go to the DLQ untouched, so nothing is silently dropped.
            producer.produce(DLQ_TOPIC, key=msg.key(), value=msg.value(),
                             headers={"error": "bad_json"}, on_delivery=on_delivery)
            continue
        key, status = classify_ip(event.get("client_ip"))
        parsed.append((msg, event, key, status))

    # 500 messages from a busy topic are often a few dozen distinct IPs.
    results = resolve({key for _, _, key, status in parsed if status is None})

    for msg, event, key, status in parsed:
        data, as_of = None, None
        if status is None:
            status, data, as_of = results[key]
        event.update(data or {"geo": None, "asn": None})
        event["enrichment"] = {"status": status, "source": source if as_of else None,
                               "as_of": as_of}
        # Keep the original key: per-user ordering survives enrichment.
        producer.produce(ENRICHED_TOPIC, key=msg.key(), value=json.dumps(event),
                         on_delivery=on_delivery)

The comment about distinct IPs is the point of the whole post. The test seed was 12 client_ip values repeated five times: repeats, an IPv4-mapped duplicate, two private addresses, a garbage string, and one missing field, plus two records that weren't JSON objects. After classify_ip and the set comprehension, the lookup saw five addresses.

import signal

from confluent_kafka import Consumer, KafkaException, Producer


def run(resolve, source):
    consumer = Consumer({"bootstrap.servers": BOOTSTRAP, "group.id": "ip-enricher",
                         "enable.auto.commit": False, "auto.offset.reset": "earliest"})
    producer = Producer({"bootstrap.servers": BOOTSTRAP,
                         "enable.idempotence": True, "linger.ms": 20})
    failed = []
    stopping = []
    signal.signal(signal.SIGTERM, lambda *_: stopping.append(True))
    signal.signal(signal.SIGINT, lambda *_: stopping.append(True))

    def on_delivery(err, _msg):
        if err is not None:
            failed.append(err)

    consumer.subscribe([RAW_TOPIC])
    try:
        while not stopping:
            msgs = consumer.consume(num_messages=500, timeout=1.0)
            data_msgs = []
            for msg in msgs:
                if msg.error():
                    if msg.error().fatal():
                        raise KafkaException(msg.error())
                    log.warning("consumer error: %s", msg.error())
                    continue
                data_msgs.append(msg)
            if not data_msgs:
                continue
            process_batch(data_msgs, producer, on_delivery, resolve, source)
            # Commit only after every enriched record is acknowledged. A crash before this
            # line replays the batch: at-least-once, so downstream must tolerate duplicates.
            if producer.flush(30) > 0 or failed:
                raise KafkaException(f"{len(failed)} deliveries failed; not committing")
            consumer.commit(asynchronous=False)
    finally:
        consumer.close()

enable.auto.commit is off, and the commit sits after flush(). If the process dies anywhere above that line, the group replays the batch from the last committed offset. That's at-least-once delivery. The idempotent producer stops retry duplicates within a session, but a restart can still re-emit a batch, so give downstream something to dedupe on. event_id is that something here.

Wire it up

import functools
import logging
import os
import sys

if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
    mmdb_path = os.environ.get("IPGEO_MMDB_PATH")
    try:
        if mmdb_path:
            run(MmdbLookup(mmdb_path).resolve, source="mmdb")
        elif API_KEY:
            run(functools.partial(resolve_api, api_key=API_KEY), source="api")
        else:
            sys.exit("Set IPGEO_MMDB_PATH or IPGEO_API_KEY")
    except FatalLookupError as exc:
        # Exit non-zero with offsets uncommitted. Fix the key, restart, nothing is lost.
        sys.exit(f"lookup configuration error: {exc}")

This block goes last in enricher.py, after the MmdbLookup class from the next section. Run it with IPGEO_API_KEY set for the API path, or IPGEO_MMDB_PATH for the file path covered next. A bad or free-plan key raises FatalLookupError, and the process exits non-zero before committing anything. That's the one failure that should stop the stream, because failing open on a misconfigured key ships blank events forever. In testing, a bad key exited with status 1 and left the batch uncommitted. On the next start, the group picked those events up from the last committed offset, with nothing lost.

Swapping in a local MMDB

Once the credit counter says it's time, the same consumer can read a local MMDB instead. The implementation below expects one combined file containing both location and ASN data. A standalone city database does not contain asn.*, and a standalone ASN database does not contain location.*. If your subscription provides separate files, open both and merge their records before passing them to the normalizer. Every enricher node needs local access to the required file or files.

import os
from datetime import datetime, timezone

import maxminddb


class MmdbLookup:
    """Lookups from a local IPGeolocation MMDB, reopened when the file is replaced."""

    def __init__(self, path):
        self.path = path
        self.reader = None
        self._open()

    def _open(self):
        st = os.stat(self.path)
        new = maxminddb.open_database(self.path)  # MODE_AUTO: C extension and mmap when available
        old, self.reader = self.reader, new
        self.identity = (st.st_ino, st.st_mtime_ns)
        built = datetime.fromtimestamp(new.metadata().build_epoch, timezone.utc)
        self.as_of = built.isoformat(timespec="seconds")  # the build date, not the lookup time
        if old is not None:
            old.close()

    def resolve(self, keys):
        # Updates rename a new file over the old one, so a new inode means a new build.
        try:
            st = os.stat(self.path)
            if (st.st_ino, st.st_mtime_ns) != self.identity:
                self._open()
                log.info("reloaded %s, build %s", self.path, self.as_of)
        except (FileNotFoundError, maxminddb.InvalidDatabaseError) as exc:
            log.warning("keeping current database, reload failed: %s", exc)
        out = {}
        for ip in keys:
            rec = self.reader.get(ip)
            out[ip] = ("ok", from_mmdb(rec), self.as_of) if rec else ("not_found", None, self.as_of)
        return out

Read the file with a generic MMDB reader such as the maxminddb package, not MaxMind's typed GeoIP2 classes from the geoip2 package. The typed classes map MaxMind's own keys (country.iso_code, city.names) onto models. Against a file in this layout, city() returns a model with every field set to None, or raises TypeError on its database-type check, depending on the file's metadata. Anything built on those classes inherits that, including Kafka Connect transforms written for GeoLite2.

Two details keep the reload safe. Database updates are installed by renaming a new file over the old one, so a changed inode is a reliable "new build" signal, and a file that's missing mid-swap just means "keep the reader you have". And as_of here is the build date, not the lookup time. A replay next month should tell you which build answered.

In testing, I renamed a new file into place while the consumer was running. The next batch logged the reload and picked up the new data, with no restart.

Things that bite in production

The lookup's worst case has to fit inside the poll interval. Keep your connect/read timeout plus any safe retry backoff well under max.poll.interval.ms, or the group can rebalance you out mid-batch and replay it. The retry policy above does not retry a POST after a read timeout, because the server may already have processed that batch. If you'd rather stop than fail open, consumer.pause() the assignment until the API recovers.

Keying by user and keying by IP pull in opposite directions. Keying the raw topic by client IP pins each address to one partition and one cache, which cuts credits. It also breaks per-user ordering if anything downstream relies on it. I keep the user key and accept the duplicate lookups until the bill says otherwise. A shared Redis cache is the next step after that, not before.

The IP has to be the client's. If your producers sit behind a load balancer, client_ip must come from a trusted X-Forwarded-For hop at the edge. Otherwise your entire user base appears to live wherever your load balancer does.

Schema Registry users: add the new fields with defaults. In Avro, adding geo, asn, and enrichment as nullable fields with a null default keeps the change backward compatible. Without defaults, old readers break the day you deploy.

When not to build this

Not every Kafka data enrichment job needs its own consumer. If Fluent Bit or Vector already sits in front of Kafka, enrich there. Both have MMDB lookups, and the events arrive enriched without a consumer to run. If your data enters through Kafka Connect and you're on MaxMind or IP2Location data, single message transforms do this job inside Connect: IP2Location publishes its own, and the MaxMind one is a community project. If you already run Flink for streaming data enrichment elsewhere, its async I/O operator handles API lookups with backpressure built in.

The consumer above earns its keep when you want lookups batched and priced deliberately, a contract that doesn't change when the data source does, and failure behavior you chose rather than inherited.

Before you ship it, set the cache TTL to how fast your answer actually goes stale. Then alert on the ratio of unavailable to ok in enrichment.status rather than on exceptions, and re-check the credit counter after the first week of real traffic, because distinct-IP counts are the one number nobody guesses right up front.

IP Risk Score Widget: Show Visitors What You See

ABDULLAH AFZAL — Thu, 08 Oct 2026 16:53:18 +0000

An IP risk score decides whether your login form waves someone through or throws a challenge, and the person it describes never gets to see it. Meanwhile your status page says All Systems Operational to a user whose sign-in just failed because their IP sits on a residential proxy list.

Netflix's own help page, for people who get the VPN error with their VPN off, ends with resetting the router and calling the ISP. That's the state of the art. This post builds the alternative: a small "Your connection" widget that tells visitors what your systems see about their IP, in plain language.

It drops into a hosted status page with one script tag. And it leaves out the score on purpose, because a public score checker is exactly what proxy sellers want.

TL;DR

Look up only the caller, on your server: read the client IP yourself and pass it to GET /v3/security. Never accept an IP from the browser.
Request only the fields you'll use with fields=, then send the browser sentences, not data.
Show flags a visitor can act on (VPN, relay, residential proxy, abuse history, corporate gateway). Hide the 0 to 100 score, every confidence value, and every last-seen date.
Cache per IP, limit per IP, cap the daily total, and fail quietly. Each lookup costs 2 credits.
Optional: a browser-side live check behind a button separates "this IP has VPN history" from "this session is on a VPN right now." The widget answers the question your support inbox keeps getting, "why am I blocked?", without turning your status page into a free proxy grader. The server keeps the score and turns flags into plain sentences. The browser only ever sees what you decided to show, and the visitor can act on all of it.

What the widget shows, and what it hides on purpose

The IP reputation API used here returns 27 fields in its security object for one address. Most of them help a person understand their own connection. A handful mainly help someone testing a proxy pool. The rule I use: show a flag when knowing it helps the visitor fix something, and hide anything that measures how sure the detection is or how recently it fired.

Field(s)	What the visitor sees	Why
`is_vpn`, `vpn_provider_names`	"This IP is listed as a VPN exit (SurfShark VPN)"	Naming the provider tells them what to switch off
`is_relay`, `relay_provider_name`	"You're using iCloud Private Relay. It isn't a VPN."	Relays and VPNs deserve different copy and different rules
`is_tor`	"This IP is a Tor exit node"	Honest, and the Tor user already knows
`is_residential_proxy`, `is_proxy`	"Seen in residential proxy networks," plus what usually causes it	The one finding innocent users rarely know about
`is_spam`, `is_known_attacker`	"A recent history of abuse," plus shared-network and malware notes	Common on mobile and shared IPs
`is_corporate_gateway`, `corporate_gateway_provider_name`	"Your employer's security gateway (Zscaler)"	Reassurance; one gateway IP fronts a whole company
`is_cloud_provider`, `cloud_provider_name`	"Comes from a hosting provider (UpCloud)"	The usual false positive for people on cloud desktops
`threat_score`	Hidden. A three-state summary only	The number is the gradient an attacker tunes against
`_confidence_score`, `_last_seen`	Hidden	Freshness tells a proxy operator when to rotate
`is_bot`, `bot_type`, `bot_operator_name`, `is_known_good_bot`	Hidden	Internal classification, meaningless to a person
`proxy_provider_names`	Hidden	Nine proxy brands is noise to a homeowner and a receipt to a proxy user
`is_anonymous`	Not shown separately	It's derived from the flags already shown

The residential proxy row is the one that justifies the whole widget. A home IP lands on those lists when something on the network is selling its bandwidth, often without the owner knowing. When Google disrupted the IPIDEA network in January 2026, its threat intelligence team described devices joining through proxy code embedded in apps, and researchers finding proxy payloads preinstalled on off-brand Android TV boxes. Those people deserve a sentence that says so.

None of this is new for VPN companies. Mullvad's connection check has printed lines like "Your IP is not blacklisted" for years. Your app can do the same for its own rules.

Why the IP risk score never leaves your server

A public IP risk check that prints a number is a tool for whoever owns the proxies. That's not hypothetical. Evomi, a residential proxy seller, lets customers append _fraudscore-0 to the proxy password so they only get exits with a clean Scamalytics score. Show a 0 to 100 number on your status page and you've built the same filter for free, tuned to your own rules.

If you only do one hardening step, drop the score. A yes/no flag tells a proxy operator one exit is burned. A number tells them which exits are almost good enough, and the confidence and last-seen fields tell them when to rotate. IPQS and Scamalytics already publish scores in their public checkers. Your site doesn't need to be another one.

Hiding a field in the UI hides nothing, because the full response sits in the browser's network tab. That rules out the shortcut the API offers. Register your status page as a Request Origin and the browser can call the security endpoint directly, no key required. Tempting for a static page, but every view costs 2 credits, the browser receives whatever you requested, and an Origin header is just a header that anything outside a browser can set. The provider's own auth docs say to prefer a backend proxy in production. That's what we'll build.

Step 1: An endpoint that only looks up the caller

Four small files: the route, the lookup, a cache with limits, and a mapper from flags to sentences. Node 18+ for the built-in fetch, Express 4 or 5, and the cors package.

Read the client IP you can actually trust

The browser can't reliably tell you its own public IP, which is why so many "javascript get client ip" answers call an echo service and post the result back to the server. Don't. An endpoint that accepts an IP from the client will look up any IP anyone sends it, on your credits. Read the address on the server.

Behind exactly one reverse proxy (nginx, a load balancer, a PaaS router), app.set("trust proxy", 1) makes req.ip the address that proxy saw, but only if every request reaches the app through that one-hop path and clients cannot reach the origin directly. If your topology has multiple paths, trust the proxy's actual IPs or CIDRs instead of a numeric hop count. Otherwise a client can supply X-Forwarded-For and turn your caller-only endpoint into an arbitrary-IP lookup.

// server.js: Node 18+, Express 4 or 5
import express from "express";
import cors from "cors";
import { lookupSecurity } from "./ipgeo.js";
import { toFindings } from "./findings.js";
import { getCached, setCached, allowRequest, spendBudget } from "./limits.js";

const app = express();
const UNAVAILABLE = { summary: "unknown", findings: [] };

// Exactly one proxy sits in front of this app. Trusting one hop makes req.ip
// the address that proxy saw, not whatever the client wrote into X-Forwarded-For.
app.set("trust proxy", 1);
app.use(express.static("public")); // serves public/widget.js
app.use("/api", cors({ origin: "https://status.example.com", methods: ["GET"] }));

app.get("/api/connection", async (req, res) => {
  res.set("Cache-Control", "no-store"); // a per-visitor answer must never be shared by a CDN

  // No ?ip= parameter, ever. IPv4 clients can arrive in IPv6-mapped form.
  const ip = req.ip?.replace(/^::ffff:/, "");
  if (!ip) return res.status(400).json(UNAVAILABLE);
  if (!allowRequest(ip)) {
    return res.status(429).json({ ...UNAVAILABLE, message: "Too many checks. Try again in a few minutes." });
  }

  const cached = getCached(ip);
  if (cached) return res.json(cached);
  if (!spendBudget()) return res.status(503).json(UNAVAILABLE);

  try {
    const result = await lookupSecurity(ip);
    const body = result.private
      ? { summary: "unknown", findings: [{ tone: "info", text: "You're on a private network address, so there's nothing to check." }] }
      : { ip, ...toFindings(result.security) };
    setCached(ip, body);
    return res.json(body);
  } catch (err) {
    // Fail open: the widget explains, it never gates. Log it, don't cache it.
    console.error("connection check failed:", err?.message);
    return res.status(503).json(UNAVAILABLE);
  }
});

app.listen(Number(process.env.PORT ?? 3000));

The order matters: rate limit, then cache, then budget. A cached answer never spends credits, and a blocked caller never touches the cache.

Ask the security endpoint for only the fields you'll show

I'm using IPGeolocation's IP Security API because its response keeps relay, corporate gateway, and residential proxy as separate flags, which is exactly what plain-language copy needs. IPQS, IPinfo, and proxycheck.io all do VPN and proxy detection too, so swap freely; findings.js is the only file that knows field names. Security data needs a paid plan, and each lookup costs 2 credits.

One gotcha. If you omit ip, the endpoint looks up the caller. That's handy from a browser and useless from a server, where the caller is you. Server-side, always pass it.

curl -s "https://api.ipgeolocation.io/v3/security?apiKey=$IPGEO_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": [
      "ProxyScrape", "DataImpulse", "Oxy Labs", "ProxyEmpire", "Proxy-Store",
      "SpyderProxy", "FleetProxy", "Proxy4u", "FlashProxy"
    ],
    "proxy_confidence_score": 99,
    "proxy_last_seen": "2026-10-05",
    "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": ""
  }
}

That's a live response from October 2026: a residential IP that's also a listed SurfShark exit, flagged for attacks and spam, with nine proxy providers attached. Every field is useful to your fraud rules. The lookup below requests 14 of the 27, and the visitor sees sentences built from 13 of those.

// ipgeo.js
const API_KEY = process.env.IPGEO_API_KEY;

// Only what findings.js reads. Confidence scores and last-seen dates never
// reach this server, so a careless log line can't leak them either.
const FIELDS = [
  "security.threat_score",
  "security.is_vpn", "security.vpn_provider_names",
  "security.is_relay", "security.relay_provider_name",
  "security.is_tor", "security.is_proxy", "security.is_residential_proxy",
  "security.is_spam", "security.is_known_attacker",
  "security.is_cloud_provider", "security.cloud_provider_name",
  "security.is_corporate_gateway", "security.corporate_gateway_provider_name",
].join(",");

// Throws on failure; the route's try/catch turns that into a quiet 503.
export async function lookupSecurity(ip) {
  if (!API_KEY) throw new Error("IPGEO_API_KEY is not set");

  const url =
    "https://api.ipgeolocation.io/v3/security" +
    `?apiKey=${encodeURIComponent(API_KEY)}` +
    `&ip=${encodeURIComponent(ip)}` + // omit this server-side and you look up yourself
    `&fields=${FIELDS}`;

  // 1.5s is plenty for a status widget. A slow answer is worse than "try again".
  const res = await fetch(url, { signal: AbortSignal.timeout(1500) });

  // 423 Locked: a private or bogon address, i.e. you're testing from localhost or a LAN.
  if (res.status === 423) return { private: true };
  // 401 usually means a free-plan key; security data needs a paid plan.
  if (!res.ok) throw new Error(`security lookup failed: HTTP ${res.status}`);

  const body = await res.json();
  return { private: false, security: body?.security ?? null };
}

fields here is doing privacy work, not payload trimming. Whatever this server never receives, it can't accidentally return.

Cache per IP, and cap the whole thing

Security data refreshes at least twice a day, so a 30-minute cache costs almost nothing in freshness and turns a visitor mashing the button into one lookup. Then two limits: five checks per IP per ten minutes, and a daily budget that stops spending once it's hit.

// limits.js: in-memory, single instance. Behind several instances, move all of
// this to Redis or your gateway, or each instance quietly gets its own budget.
const TTL_MS = 30 * 60 * 1000;   // security data refreshes at least twice a day
const WINDOW_MS = 10 * 60 * 1000;
const PER_IP_LIMIT = 5;          // checks per IP per window
const DAILY_BUDGET = 5000;       // lookups, i.e. 10,000 credits at 2 each

const results = new Map();       // ip -> { value, expires }
const hits = new Map();          // ip -> { count, resetAt }
let spentToday = 0;
let budgetDay = new Date().toISOString().slice(0, 10);

export function getCached(ip) {
  const entry = results.get(ip);
  if (!entry) return null;
  if (entry.expires < Date.now()) {
    results.delete(ip);
    return null;
  }
  return entry.value;
}

export function setCached(ip, value) {
  if (results.size > 50_000) results.clear(); // crude ceiling; swap in an LRU if this ever fires
  results.set(ip, { value, expires: Date.now() + TTL_MS });
}

export function allowRequest(ip) {
  const now = Date.now();
  if (hits.size > 100_000) hits.clear();      // same ceiling idea for the limiter
  const entry = hits.get(ip);
  if (!entry || entry.resetAt < now) {
    hits.set(ip, { count: 1, resetAt: now + WINDOW_MS });
    return true;
  }
  entry.count += 1;
  return entry.count <= PER_IP_LIMIT;
}

export function spendBudget() {
  const today = new Date().toISOString().slice(0, 10);
  if (today !== budgetDay) {
    budgetDay = today;
    spentToday = 0;
  }
  if (spentToday >= DAILY_BUDGET) return false;
  spentToday += 1;
  return true;
}

At 2 credits a lookup, that budget caps the widget at 10,000 credits a day no matter who's hammering it. A status page with 3,000 unique visitors who all click would use 6,000.

Be honest about what this buys. A proxy user can still check each exit once: the limit is per IP, and they have thousands of IPs. What they can't get is a score to optimize against, and they can't run your bill past the budget.

Turn flags into findings, not data

This is where the transparency actually happens, so spend your editing time on the strings, not the code. Two choices matter.

First, describe the IP, not the person. The data is the address's history, and on a shared or reassigned IP it isn't about them at all.

Second, the summary collapses the score into three states. IPGeolocation's bands run 1 to 19 low observed risk, 20 to 44 use with context, 45 to 79 elevated, and 80 to 100 high risk (what to do at each level). The widget folds the top two into one state on purpose, because "elevated" versus "high" is a gradient again.

// findings.js: flags in, sentences out. Nothing numeric leaves this function.
// The copy describes YOUR policy, so edit it to match what your rules actually do.
export function toFindings(security) {
  if (!security) return { summary: "unknown", findings: [] };
  const s = security;
  const findings = [];
  const add = (tone, text) => findings.push({ tone, text });

  if (s.is_corporate_gateway) {
    const vendor = s.corporate_gateway_provider_name || "a corporate security gateway";
    add("info", `You're browsing through your employer's security gateway (${vendor}). That's normal on a work network.`);
  }
  if (s.is_relay) {
    add("info", `You're using ${s.relay_provider_name || "a privacy relay"}. It hides your address, but it isn't a VPN.`);
  }
  if (s.is_vpn) {
    const name = s.vpn_provider_names?.[0];
    // IP history, not this session: an address can stay listed after it changes hands.
    add("warn", `This IP is listed as a VPN exit${name ? ` (${name})` : ""}. If you're not using a VPN right now, the address may have been reassigned to you.`);
  }
  if (s.is_tor) add("warn", "This IP is a Tor exit node.");
  if (s.is_residential_proxy) {
    add("warn", "This IP has been seen in residential proxy networks. If you're not running a proxy, check for 'bandwidth sharing' apps, free VPN apps, or no-name streaming boxes on your network.");
  } else if (s.is_proxy) {
    add("warn", "This IP has been seen working as a proxy.");
  }
  if (s.is_spam || s.is_known_attacker) {
    add("warn", "This IP has a recent history of abuse. On mobile or shared networks that's usually someone else's traffic. On a home connection, a malware scan is worth ten minutes.");
  }
  // Skip "hosting" when another finding already explains the address, or the copy contradicts itself.
  if (s.is_cloud_provider && !s.is_corporate_gateway && !s.is_residential_proxy) {
    add("info", `This connection comes from a hosting provider${s.cloud_provider_name ? ` (${s.cloud_provider_name})` : ""}, not a home or mobile network.`);
  }

  const rawScore = s.threat_score;
  const score = Number(rawScore);
  const hasScore =
    rawScore !== null &&
    rawScore !== undefined &&
    rawScore !== "" &&
    Number.isFinite(score);

  const summary = !hasScore
    ? "unknown"
    : score >= 45
      ? "attention"
      : score >= 20
        ? "notice"
        : "clear";
    return { summary, findings };
}

For 145.223.7.7, this is everything the browser receives:

{
  "ip": "145.223.7.7",
  "summary": "attention",
  "findings": [
    { "tone": "warn", "text": "This IP is listed as a VPN exit (SurfShark VPN). If you're not using a VPN right now, the address may have been reassigned to you." },
    { "tone": "warn", "text": "This IP has been seen in residential proxy networks. If you're not running a proxy, check for 'bandwidth sharing' apps, free VPN apps, or no-name streaming boxes on your network." },
    { "tone": "warn", "text": "This IP has a recent history of abuse. On mobile or shared networks that's usually someone else's traffic. On a home connection, a malware scan is worth ten minutes." }
  ]
}

No score, no confidence, no dates, no proxy brands. Brander Group's hosting flag got dropped too, because "residential proxy" and "not a home network" in the same card would read as a bug.

Step 2: The widget is one script tag

The widget runs on click, not on page load. Status pages get hit by uptime monitors, link previews, and crawlers, and none of them need a lookup. It renders with textContent only, because provider names are third-party strings and innerHTML turns them into a script injection waiting to happen.

// public/widget.js: loaded by the status page, talks only to your endpoint.
(() => {
  const ENDPOINT = "https://api.example.com/api/connection";
  const root = document.getElementById("connection-check");
  if (!root) return;

  // Edit these to match what your rules actually do to each state.
  const HEADLINES = {
    clear: "Nothing unusual about your connection.",
    notice: "A few things about your connection are worth knowing.",
    attention: "Some actions from this connection will ask for extra verification.",
    unknown: "We couldn't check your connection right now.",
  };

  const button = document.createElement("button");
  button.type = "button";
  button.textContent = "Check my connection";
  const output = document.createElement("div");
  output.setAttribute("aria-live", "polite");
  root.append(button, output);

  button.addEventListener("click", async () => {
    button.disabled = true;
    output.replaceChildren(line("Checking..."));
    try {
      const res = await fetch(ENDPOINT, { credentials: "omit", signal: AbortSignal.timeout(4000) });
      render(await res.json().catch(() => ({ summary: "unknown" })));
    } catch (err) {
      // Network error or timeout: say so plainly, never guess a verdict.
      console.warn("connection check failed:", err?.message);
      render({ summary: "unknown" });
    } finally {
      button.disabled = false;
    }
  });

  function render(data) {
    const items = [line(HEADLINES[data?.summary] ?? HEADLINES.unknown)];
    if (data?.ip) items.push(line(`We see your connection as ${data.ip}.`));
    for (const f of data?.findings ?? []) items.push(line(f?.text, f?.tone));
    if (data?.message) items.push(line(data.message));
    output.replaceChildren(...items);
  }

  // textContent, never innerHTML: provider names come from third-party data.
  function line(text, tone = "info") {
    const p = document.createElement("p");
    p.className = `cc-${tone === "warn" ? "warn" : "info"}`;
    p.textContent = String(text ?? "");
    return p;
  }
})();

On failure it says it couldn't check, and nothing else. The widget is informational, so a broken lookup should never look like a verdict.

Dropping it into Atlassian Statuspage

Statuspage lets you inject custom header and footer HTML, which is all this needs. The catch, per Atlassian's custom HTML docs: custom HTML only renders on a custom domain like status.example.com. Custom HTML also isn't on every plan, so check yours before you promise this to support. Paste this into the custom footer:

<div id="connection-check"></div>
<script src="https://api.example.com/widget.js" defer></script>

Self-hosted status pages (Upptime, Cachet, a /status route in your own app) take the same two lines. The script loads from your API's domain, and only the fetch needs CORS, which the server already scopes to the status page origin.

Optional: a live check for "I'm not on a VPN, I swear"

Everything so far is IP history. The 145.223.7.7 copy admits it: the address is listed as a VPN exit, and that may say nothing about whoever is using it today. For that complaint, the useful question is what this session is doing right now.

IPGeolocation's Real-Time Proxy & VPN Detection is a browser-only script that runs live tests against the connection itself. There's no API key; it's authorized by Request Origin, so register the status page's origin first. A verdict takes 1 to 5 seconds and costs 3 credits, or 5 with the security data attached, which the server already has, so skip it. It's a paid feature. Because it runs in the visitor's browser, your server's limits don't apply to it. It gets its own button and never runs on load, even though the docs suggest starting early.

// public/live-check.js: optional second button inside the same widget.
(() => {
  const SCRIPT = "https://static.ipgeolocation.io/web-assets/static/security/session-analysis.js";
  const root = document.getElementById("connection-check");
  if (!root) return;

  const button = document.createElement("button");
  button.type = "button";
  button.textContent = "Run a live test (a few seconds)";
  const out = document.createElement("p");
  out.setAttribute("aria-live", "polite");
  root.append(button, out);

  const loadScript = () => new Promise((resolve, reject) => {
    if (window.Analysis) return resolve();
    const el = document.createElement("script");
    el.src = SCRIPT;
    el.onload = () => resolve();
    el.onerror = () => reject(new Error("live-check script failed to load"));
    document.head.append(el);
  });

  button.addEventListener("click", async () => {
    button.disabled = true;
    out.textContent = "Testing your connection...";
    try {
      await loadScript();
      // No key here: the request is authorized by the page's registered origin.
      const result = await window.Analysis.startMonitoring().get();
      out.textContent = describe(result?.live_vpn_proxy_detection);
      button.remove(); // one live test per page view; each run costs credits
      // visitor_actual_location is ignored on purpose. Never print the real IP behind a VPN.
    } catch (err) {
      console.warn("live check failed:", err?.message);
      out.textContent = "The live test couldn't run in this browser.";
      button.disabled = false;
    }
  });

  function describe(live) {
    if (!live) return "The live test didn't return a result.";
    // Below 30 the docs call the signal very weak, so claim nothing.
    if ((live.confidence_score ?? 0) < 30) return "The live test was inconclusive.";
    if (!live.is_anonymous) return "Right now, your connection looks direct: no VPN or proxy detected.";
    return (live.proxy_score ?? 0) >= (live.vpn_score ?? 0)
      ? "Right now, your traffic looks like it's going through a proxy."
      : "Right now, your traffic looks like it's going through a VPN.";
  }
})();

Put this next to the server result and you get the sentence support actually needs: listed as a VPN exit, but direct right now. That usually means the address changed hands, and it's the screenshot that closes the ticket.

Pitfall: treat the live verdict as display-only. It runs in the visitor's browser, so anyone can edit what it reports. Never post it back to your server as a trust signal.

A few extra notes

Mobile carriers put many subscribers behind one CGNAT address, so abuse history on a phone connection is rarely about the phone in your hand. That's why the copy says "this IP" everywhere and "you" almost nowhere.

The cache is keyed by exact IP, so a visitor who turns their VPN off gets a fresh lookup the moment their address changes. IPv6 privacy addresses rotate on their own, which can mean more cache misses than you'd expect. Keep security results keyed to the exact address rather than broadening one verdict across a /64; if the budget starts tripping, increase the TTL, tighten rate limits, or raise the budget instead.

Testing on localhost hits the 423 path, because 127.0.0.1 and LAN addresses are bogons. Expose the server through a tunnel, or hardcode a test IP in lookupSecurity and delete it before you commit.

You're showing someone data about their own IP, which is the friendly direction. Don't undo that by logging the findings next to user IDs. The lookup itself is the only record you need.

Ship the server endpoint first, with the score already stripped, and watch the X-Credits-Charged header for a week before adding the live button. If the number surprises you, raise the cache TTL before you touch the budget. And link the widget from your block page, because the people who need it most won't think to open your status page.

Build a Slack Bot That Investigates Any IP You Paste

ABDULLAH AFZAL — Tue, 06 Oct 2026 18:50:48 +0000

A Slack bot that investigates a pasted IP needs three things in one reply: a threat score, the provider behind the address, and the abuse contact to report it to. The first two are one API call. The third is the one everyone skips.

That skip is why a lot of abuse never reaches the network that could actually stop it. Finding an abuse address means a WHOIS query, reading an RIR record, and guessing which of four email addresses is the live one. Nobody does that at 4pm on a Friday.

Most IP lookup bots stop at the score. This one ends at a sendable report, and it handles corporate gateways, known-good bots, and bogons separately so a raw score does not become the whole verdict.

TL;DR

One slash command, two API calls, three credits per investigation.
Returns threat score, VPN and proxy provider names, bot type, and the abuse contact email in a single Block Kit reply.
Uses a slash command rather than a message listener, so the bot only spends credits when someone asks.
Refuses to score three address types that break naive triage: corporate gateways, declared good bots, and bogons.
Full Bolt for Python code, with the ack() timing gotcha that breaks this on Lambda. You'll end up with a /ip command that takes an address, returns a structured verdict in about a second, and tells you exactly who to email if the answer is bad. The triage thresholds are mine, not a vendor's, and I'll show you where to move them.

What the bot does, and what it deliberately doesn't

The output contract is four lines: a score with a band, the flags that explain the score, the provider name where one exists, and an abuse email. Anything else is noise in a channel.

The design decision worth arguing about is the trigger. The obvious build listens for message events and auto-replies whenever an IP appears in text. One of the few existing open-source versions does exactly that. I think that's the wrong call, for three reasons.

It spends credits uninvited. Someone pastes a log excerpt with forty addresses in it and you've just burned 120 credits on data nobody asked for. It's noisy, because half of those addresses are your own load balancers. And it quietly enriches customer IPs that happened to land in a support thread, which is a privacy conversation you don't want to have retroactively.

A slash command is explicit. Someone types /ip 145.223.7.7 because they want to run the lookup. That's intentional invocation, cost control, and a clean audit line in one design choice.

Pitfall: slash-command responses are ephemeral by default, which is exactly what you want for customer IP investigations. Keep them that way unless you deliberately need an in_channel response, and avoid putting the raw enrichment payload into Slack. More on that at the end.

Two calls, three credits

The risk score and the abuse contact live on different endpoints. That sounds like a drawback until you look at what each one costs.

I'll use IPGeolocation for the examples because it returns both from the same key, and the abuse record is the part that's genuinely hard to find elsewhere. IPQualityScore and ipinfo both do risk scoring well; AbuseIPDB is a reporting database rather than a registry lookup; MaxMind GeoIP2 covers anonymity but not abuse contacts. If you already pay for one of those, the Slack and triage code below works unchanged, you'll just need a second source for the abuse address.

Start with the risk call.

curl -s -X GET \
  "https://api.ipgeolocation.io/v3/security?apiKey=$IPGEO_API_KEY&ip=145.223.7.7"

That returns the complete security object. This is the full shape, not a trimmed version, because the fields you ignore today are the ones you'll need the first time a verdict looks wrong:

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

Two things to notice before you write any parsing code. proxy_provider_names and vpn_provider_names are arrays, not strings, and they're frequently empty. And the confidence scores default to 0 when their flag is false, so printing "VPN confidence: 0" next to "VPN: no" makes your bot look broken when it's working correctly.

The abuse call is separate and cheaper.

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

{
  "ip": "49.12.0.0",
  "abuse": {
    "route": "49.12.0.0/20",
    "country": "DE",
    "name": "Hetzner Online GmbH - Contact Role",
    "organization": "Hetzner Online GmbH",
    "kind": "group",
    "address": "Hetzner Online GmbH, Industriestrasse 25, D-91710 Gunzenhausen, Germany",
    "emails": ["abuse@hetzner.com"],
    "phone_numbers": ["+4998315053", " +4998315050"]
  }
}

Every field in the IP abuse contact record can be empty, including abuse.emails. abuse.route gives you the CIDR range the contact covers, which is what you quote in the report. Plan for "no abuse contact on record" as a normal outcome rather than an exception, because it's the single most common runtime surprise in this build.

You can get both objects from the unified /v3/ipgeo endpoint with include=security,abuse. The docs recommend against it when you only want those two, and they're right: the dedicated endpoints return smaller payloads and charge predictably. Security costs 2 credits, abuse costs 1. Three credits per investigation, 150,000 credits on the $19 Starter plan, so roughly 50,000 investigations a month before you spend another cent.

Heads up: the free plan returns 401 Unauthorized on both of these endpoints. Not a rate limit, not a trimmed response, a flat 401. If you want to follow along end to end you need a paid key. Worth knowing before you copy the code and spend twenty minutes debugging your signing secret.

Setting up the Slack app

Create the app at api.slack.com/apps, then three things matter.

Slash command. Under Features, add a command. Name it /ip, point the Request URL at https://your-host/slack/events, and write a usage hint. Saving the command adds the commands OAuth scope automatically.

Signing secret. Basic Information, App Credentials. This is how you verify that requests actually came from Slack. Bolt checks it for you, including the timestamp freshness check that blocks replay attacks, but only if you pass it in.

Bot token. OAuth & Permissions, after installing to a workspace. Starts with xoxb-.

Then grab an API key for the IP data and put all three in the environment:

export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_SIGNING_SECRET="..."
export IPGEO_API_KEY="..."

pip install slack_bolt requests

The enrichment client

Both calls go through one function. Timeouts are short on purpose: this runs inside a three-second budget and a hung connection is worse than a missing field.

import os
import logging
import requests

log = logging.getLogger(__name__)

API_BASE = "https://api.ipgeolocation.io/v3"
API_KEY = os.environ["IPGEO_API_KEY"]  # fail loudly at boot, not mid-request

# One session for the whole process. Connection reuse saves roughly a
# round trip per call, which matters inside a 3 second budget.
_session = requests.Session()


def _lookup(path: str, ip: str) -> dict | None:
    """Call one IPGeolocation endpoint. Returns None on any failure."""
    try:
        resp = _session.get(
            f"{API_BASE}/{path}",
            params={"apiKey": API_KEY, "ip": ip},
            timeout=(1.0, 1.5),  # connect, read
        )
    except requests.RequestException as exc:
        log.warning("lookup %s failed for %s: %s", path, ip, exc)
        return None

    if resp.status_code == 423:
        return {"_bogon": True}  # private or reserved, costs no credits
    if resp.status_code == 401:
        log.error("401 on %s. Security and abuse need a paid key.", path)
        return None
    if resp.status_code != 200:
        log.warning("lookup %s returned %s for %s", path, resp.status_code, ip)
        return None

    try:
        return resp.json()
    except ValueError:
        log.warning("non-JSON response from %s for %s", path, ip)
        return None

The 423 branch is worth keeping even though we validate before calling. It's the API telling you the address is a bogon or private, and those don't count against your quota, so the failure is free. Catching it explicitly means a /ip 10.0.0.5 from someone pasting an internal address gets a useful answer instead of a shrug.

Fail open, not closed. Both lookups returning None should produce "I couldn't check this one" in the channel, never a blocked user. A chat bot is not an enforcement point.

Parse the IP before you spend a credit

Slash command text is whatever the user typed, and Slack mangles it before you see it.

In several clients, a bare IPv4 address gets auto-linked, so your handler receives <http://145.223.7.7|145.223.7.7> rather than the address. Strip that before anything else touches the string. The first bug report you get will be this one.

import ipaddress
import re

IP_PATTERN = re.compile(r"[0-9a-fA-F:.]{3,45}")


def extract_ip(text: str) -> tuple[str | None, str | None]:
    """Return (ip, error). Strips Slack's auto-linking and rejects non-public IPs."""
    if not text or not text.strip():
        return None, "Usage: `/ip 8.8.8.8`"

    # Slack wraps things that look like links in <...>, sometimes as <http://1.2.3.4|1.2.3.4>
    cleaned = text.strip().strip("<>").split("|")[0]
    cleaned = cleaned.replace("http://", "").replace("https://", "").rstrip("/")

    match = IP_PATTERN.search(cleaned)
    if not match:
        return None, f"`{text[:40]}` doesn't look like an IP address."

    try:
        addr = ipaddress.ip_address(match.group(0))
    except ValueError:
        return None, f"`{match.group(0)}` isn't a valid IPv4 or IPv6 address."

    if not addr.is_global:
        return None, f"`{addr}` is private or reserved. Nothing to look up."

    return str(addr), None

Validating locally rather than letting the API reject the input is partly about speed and partly about the message the user sees. A 400 from an upstream service turns into "lookup failed", which tells nobody anything. \bananadoesn't look like an IP address tells them they typo'd.

addr.is_global covers RFC 1918 space, loopback, link-local, carrier-grade NAT, and the documentation ranges in one check. That last one matters more than it sounds: if a colleague tests your bot with 192.0.2.1 from an RFC, the API would reject it as a bogon anyway, and catching it locally saves the round trip and gives a clearer message.

Ack first, enrich second

Slack gives you three seconds to return HTTP 200 on a slash command. Two API calls plus formatting will usually fit, but "usually" is how you end up with intermittent timeout errors that nobody can reproduce.

from slack_bolt import App

app = App(
    token=os.environ["SLACK_BOT_TOKEN"],
    signing_secret=os.environ["SLACK_SIGNING_SECRET"],
)


@app.command("/ip")
def handle_ip_command(ack, command, respond, logger):
    ack()  # HTTP 200 goes out here, before any network work

    ip, error = extract_ip(command.get("text", ""))
    if error:
        respond(text=error, response_type="ephemeral")
        return

    try:
        security = _lookup("security", ip)
        abuse = _lookup("abuse", ip)
    except Exception:
        logger.exception("enrichment failed for %s", ip)
        respond(text=f"Lookup failed for `{ip}`. Try again shortly.")
        return

    if security is None:
        respond(text=f"No security data for `{ip}` right now.")
        return
    if security.get("_bogon"):
        respond(text=f"`{ip}` is a bogon or private address.")
        return

    respond(
    blocks=build_blocks(ip, security, abuse),
    text=f"IP report for {ip}",
    response_type="ephemeral",
)


if __name__ == "__main__":
    app.start(port=int(os.environ.get("PORT", 3000)))

ack() first is the whole trick. In the default Bolt configuration, calling it flushes the HTTP 200 immediately and the rest of the function runs after Slack has already stopped counting. respond() then posts the real answer through the response_url that came with the payload.

Pitfall: this pattern breaks on AWS Lambda and other FaaS runtimes, where you can't keep working after returning an HTTP response. There you need App(process_before_response=True) plus Bolt's lazy listener mechanism, which splits the handler into an ack function and a lazy list. Same three-second rule, different plumbing. If you deploy this to Lambda with the code above, the ack will be late and users will see a timeout even though the lookup succeeded.

One more constraint on response_url: Slack allows five responses within 30 minutes of the original payload. Plenty for one reply, not enough to build a progress indicator out of.

Reading the response like an analyst

Here's where most tutorials stop, and where the actual work starts. A score on its own doesn't tell anyone what to do.

Score	Check these flags first	Suggested action
0 to 19	`is_corporate_gateway`, `is_known_good_bot`	Allow. Treat gateway and good-bot hits as explicit allow signals, not merely low risk
20 to 44	`is_bot`, `bot_type`	Log it. Rate limit if `bot_type` is `scraper` or `scanner`
45 to 79	`is_vpn`, `is_residential_proxy`, confidence scores	Step up: MFA, email verification, hold the transaction
80 to 100	`is_known_attacker`, `is_spam`, `is_residential_proxy`	Block or queue for manual review, and file the abuse report

Those bands are mine, not the vendor's. The documentation deliberately doesn't publish thresholds, and that's the honest position, because the right cut depends entirely on what a false positive costs you. A blocked signup is cheap. A blocked checkout is not. Start with these numbers, watch a week of real traffic, then move the lines.

What the score can't do is tell you why, which is why the flags sit next to it in the reply. Four real addresses, four correct but completely different outcomes:

IP	Score	What it actually is	Right call
`145.223.7.7`	90	Residential proxy and VPN, 99 confidence on both, known attacker, spam	Block
`223.197.196.92`	40	Bot, `bot_type: brute_force`, confidence 95, known attacker	Rate limit and alert
`4.227.36.0`	15	Bot, operator OpenAI, `bot_type: ai_crawler`, known good bot	Allow, apply crawler policy
`87.58.66.106`	5	Corporate gateway, Zscaler, `secure_web_gateway`	Never block

Notice the middle two. Both are bots. One is trying passwords against your login endpoint, the other is indexing your docs. A bot flag alone would treat them identically.

The corporate gateway trap

87.58.66.106 scores 5 and belongs to Zscaler. It's the egress address of an enterprise secure web gateway, which means employee traffic gets proxied through the vendor's cloud and arrives at your site from their address space.

Block that IP and you lock out an entire company. Not a user, a customer.

The flag exists specifically to stop you doing that, and it carries two more consequences your fraud rules need to know about. Never use a gateway IP for per-user identity or deduplication, because one address legitimately fronts thousands of people. And expect the geolocation to resolve to the vendor's nearest point of presence rather than the user's actual city, so impossible-travel rules will fire on perfectly normal logins.

is_anonymous stays false on these, which is the correct behaviour. The range is published, the organisation is identifiable, and nobody is hiding. It's shared, not anonymous, and those are different problems.

Good bots score low for a reason

4.227.36.0 comes back with is_bot: true, bot_operator_name: "OpenAI", bot_type: "ai_crawler", and is_known_good_bot: true. It's also flagged as cloud provider space, because crawlers run on Microsoft infrastructure like everything else.

The useful pair is bot_type plus is_known_good_bot. The type describes what the automation does, not whether it's welcome, and the same value can appear on both sides. scanner covers both Censys doing published internet-wide research and someone probing your admin paths; is_known_good_bot is what separates them. Four types (exploit, credential_stuffing, brute_force, worm) always arrive with is_known_attacker: true, so those need no interpretation at all.

Treat bot_type as a plain string. New values get added, and a strict enum in your code will throw on the first one that ships.

Formatting the reply

Block Kit sections, not attachments. Attachments are legacy and render inconsistently in newer Slack clients.

BAND = {
    (0, 19): "Low",
    (20, 44): "Watch",
    (45, 79): "Elevated",
    (80, 100): "High",
}


def _band(score: int) -> str:
    for (low, high), label in BAND.items():
        if low <= score <= high:
            return label
    return "Unknown"


def _signals(sec: dict) -> str:
    """Only report flags that are true. A wall of 'false' teaches nobody anything."""
    out = []
    if sec.get("is_residential_proxy"):
        out.append(f"Residential proxy ({sec.get('proxy_confidence_score', 0)}%)")
    elif sec.get("is_proxy"):
        out.append(f"Proxy ({sec.get('proxy_confidence_score', 0)}%)")
    if sec.get("is_vpn"):
        names = ", ".join(sec.get("vpn_provider_names") or []) or "unnamed"
        out.append(f"VPN: {names}")
    if sec.get("is_tor"):
        out.append("Tor exit node")
    if sec.get("is_relay"):
        # Private Relay and WARP are privacy features, not evasion. Flag, don't punish.
        out.append(f"Relay: {sec.get('relay_provider_name') or 'unnamed'}")
    if sec.get("is_spam"):
        out.append("Spam source")
    if sec.get("is_corporate_gateway"):
        vendor = sec.get("corporate_gateway_provider_name") or "unknown vendor"
        out.append(f"Corporate gateway: {vendor}. Do not block")
    if sec.get("is_bot"):
        kind = sec.get("bot_type") or "unclassified"
        good = "declared" if sec.get("is_known_good_bot") else "undeclared"
        out.append(f"Bot: {kind} ({good})")
    if sec.get("is_known_attacker"):
        out.append("Known attacker")
    return "\n".join(f"- {s}" for s in out) or "- No anonymity or abuse signals"

Reporting only the true flags is a small decision that changes how the message reads. Twenty-seven fields rendered as a label-value grid is a data dump. Four lines that each say something is a report.

Two inclusions worth defending. is_spam belongs in a bot whose output feeds an abuse report, because spam is the complaint most networks actually act on. And is_relay is in there separately from is_vpn because iCloud Private Relay and Cloudflare WARP are privacy defaults that ordinary customers have switched on without thinking about it, not evasion tooling. Collapsing relay into VPN is how you end up treating half your iPhone users as suspicious.

def build_blocks(ip: str, sec_payload: dict, abuse_payload: dict | None) -> list:
    sec = sec_payload.get("security", {})
    score = sec.get("threat_score", 0)

    blocks = [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": f"*`{ip}`*\nThreat score *{score}/100* ({_band(score)})",
            },
        },
        {
            "type": "section",
            "text": {"type": "mrkdwn", "text": _signals(sec)},
        },
    ]

    abuse = (abuse_payload or {}).get("abuse", {})
    emails = abuse.get("emails") or []
    if emails:
        org = abuse.get("organization") or abuse.get("name") or "unknown network"
        route = abuse.get("route") or "unknown range"
        blocks.append({
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": f"*Report to:* {', '.join(emails)}\n{org} ({route})",
            },
        })
    else:
        blocks.append({
            "type": "context",
            "elements": [{"type": "mrkdwn", "text": "No abuse contact on record."}],
        })

    return blocks

Note emails[0] rather than joining the list. Registry records sometimes carry three addresses, and the first is almost always the one the operator actually monitors. Dumping all of them invites someone to CC a role account that bounces.

From flag to sent report

The abuse email is the point of the whole build, and it's the step most teams never automate because finding the address is tedious.

A word on what you actually get back. For 49.12.0.0 the record resolves to abuse@hetzner.com, a hosting provider that reads its abuse mailbox. For 1.0.0.0 it resolves to helpdesk@apnic.net, which is APNIC's own helpdesk rather than any network operator, because that range is registry research space. Same field, very different usefulness. The data is accurate; what varies is whether anyone on the other end can act.

Response rates vary enormously, and I'd rather say that plainly than imply a lookup guarantees a takedown. Large hosting providers generally act. Some networks have never replied to anything.

What makes a report someone can act on:

Subject: Abuse report: credential stuffing from 145.223.7.7

Source IP:   145.223.7.7
Range:       145.223.7.0/24
Activity:    Automated login attempts against our authentication endpoint
Window:      2026-10-04 02:11:07 UTC to 2026-10-04 02:48:31 UTC
Volume:      ~4,100 requests across 38 accounts
Reply to:    security@yourcompany.example

Sample log lines:
2026-10-04T02:11:07Z POST /api/v1/login 401 145.223.7.7 "python-requests/2.32"
2026-10-04T02:11:09Z POST /api/v1/login 401 145.223.7.7 "python-requests/2.32"

Timestamps in UTC with the timezone written out. A window, not a single moment. Raw log lines, because the operator needs to match them against their own records. And a reply address that a human reads.

If your bot has the data for the top half of that template already, generating it is a formatting exercise. That's the actual return on this build.

Things that will bite you

Caching. Someone pastes the same IP four times while a thread argues about it. That's 12 credits for one answer. A TTL cache fixes it in about fifteen lines:

import time

_cache: dict[str, tuple[float, dict]] = {}
CACHE_TTL = 900  # 15 minutes. Security data refreshes at least twice a day.


def cached_lookup(path: str, ip: str) -> dict | None:
    key = f"{path}:{ip}"
    hit = _cache.get(key)
    if hit and time.monotonic() - hit[0] < CACHE_TTL:
        return hit[1]

    result = _lookup(path, ip)
    if result is not None:  # never cache a failure
        _cache[key] = (time.monotonic(), result)
    return result

Fifteen minutes is deliberately well under the refresh cadence. Use Redis instead of a dict the moment you run more than one process, or your cache hit rate quietly drops to nothing.

Who can run it. Slash commands are available to everyone in the workspace by default. If you're on a paid plan with a real credit budget, check command["user_id"] against an allowlist, or restrict the app to specific channels. Otherwise someone will discover it and loop it over a subnet.

Privacy. A public channel is not where customer IP addresses should live. Use response_type="ephemeral" for anything triggered outside a dedicated security channel, and never log the full enrichment payload where support staff can read it. The address is personal data in several jurisdictions and your retention policy probably didn't anticipate a Slack message.

Bogons are free. Private and reserved addresses return 423 and cost nothing. That makes this API safe to point at raw log data without filtering first, though validating locally is still faster.

The 401 again. Free keys can't call either endpoint. If you're prototyping and everything else is wired correctly, that's the first thing to check.

Where to take it next

Add a button to the Block Kit message that drafts the abuse email into a thread, because the gap between knowing the address and sending the report is where this workflow still leaks. Swap the dict cache for Redis before you run a second worker. And once you've watched a week of real traffic, move those score bands, since the ones above are a starting point rather than a policy.

If your team is pasting more than a few hundred addresses a month, batch the ones that arrive in log excerpts instead of running them one at a time. The bulk endpoint takes up to 50,000 addresses per request at the same credit rate, which turns a noisy channel habit into a scheduled job.

Enrich Nginx Access Logs With Geo and ASN at Write Time

ABDULLAH AFZAL — Fri, 02 Oct 2026 19:18:01 +0000

Your nginx access log format can carry the client's country, city, and ASN. The lookup happens at write time, against a local database file, with no API call in the request path.

Most writing on this treats it as a module install. That is the wrong frame. The two modules worth using read the same file format, so the module is plumbing. The database you load is what decides which fields exist.

TL;DR

Two nginx modules, one file format. Both read MMDB through libmaxminddb.
The database decides which fields you get. GeoLite2 covers country, city, and the ASN number and organization, and it is free.
ASN type, company, hosting provider, and threat flags need a richer database.
Quote every variable in a JSON log format. An unquoted empty value writes "threat":, and hard-fails the parser. I tested this.
Fix the client IP before you log it. One module trusts a client-controlled header by default.
Swap database files with mv, never cp. The module has the file memory mapped. Pick the database for the fields you actually need, point whichever module you already have at it, then quote everything in the log format. The failure modes are all in the last two steps, not the install.

Which database gives you which field

This is the table I wanted when I started and could not find anywhere.

Field	GeoLite2 City	GeoLite2 ASN	IPGeolocation Geo	IPGeolocation ASN	IPGeolocation Security
Country code	yes	no	yes	no	no
City, latitude, longitude	yes	no	yes	no	no
Currency, timezone, calling code	no	no	yes	no	no
ASN number	no	yes	no	yes	no
ASN organization	no	yes	no	yes	no
ASN type (ISP, HOSTING)	no	no	no	yes	no
ASN RIR, allocation date	no	no	no	yes	no
Company name, domain, type	no	no	no	no	separate Company DB
Hosting provider	no	no	no	no	separate Hosting DB
Threat score, VPN, proxy, Tor flags	no	no	no	no	yes

Two things to know before you build a log format around this.

Everything arrives as a string. A threat score of 80 is the text 80, coordinates are text, and booleans come through as 1 or 0. Nginx variables have no other type, so whatever consumes the log does the casting.

ASN number formatting is not consistent across sources. GeoLite2 stores autonomous_system_number as an integer. Ours is documented as a bare integer in the database field reference, while the module docs show the variable rendering as AS1257. That difference decides whether your parser needs to strip a prefix, so check your own file rather than trusting either of us.

Two modules, one file format

Both candidates read MMDB files through libmaxminddb. That is the whole reason the database is the real decision.

	ngx_http_geoip2_module	ngx_http_ipgeolocation_module
Install	Distro package on most systems	Build nginx from source
Field access	You write the path mapping yourself	Ready-made `$ip_*` variables
Multiple databases	One block per file	Repeat the directive, first match wins
Reload on update	`auto_reload`	Reload nginx
Stream module	Yes, with `--with-stream`	HTTP only

On Ubuntu 24.04 the first one is one command:

# Pulls libmaxminddb as a dependency and drops a load_module line
# into /etc/nginx/modules-enabled/ for you.
sudo apt-get install -y libnginx-mod-http-geoip2

That installed cleanly for me at version 1:3.4-5build2 alongside nginx 1.24.0.

Pick by what you already have. If the packaged module is there, keep it and write the mappings. If you are compiling nginx anyway and want ASN type or threat flags without hand-writing a path for every field, the ready-made variables save real config. Rebuilding a working nginx purely to avoid writing ten mapping lines is not a trade I would make.

There is a third module, the original ngx_http_geoip_module in the nginx tree. It reads MaxMind's retired legacy format and is not built by default. Do not start anything new on it.

Recipe A: map the fields yourself

The packaged module takes a file and a set of paths into it. Each path is a sequence of keys, space separated, and the module's directive reference covers the rest.

load_module modules/ngx_http_geoip2_module.so;  # skip if your package enabled it

http {
    geoip2 /etc/nginx/ipgeo/GeoLite2-City.mmdb {
        auto_reload 5m;                        # re-reads the file without a reload
        $geo_country default=ZZ country iso_code;
        $geo_city    city names en;
    }

    geoip2 /etc/nginx/ipgeo/db-ip-asn.mmdb {
        auto_reload 5m;
        $geo_asn      asn as_number;
        $geo_asn_org  asn organization;
        $geo_asn_type asn type;                # not present in GeoLite2-ASN
    }
}

The paths differ per file because the schemas differ, and that is the only thing you change when you swap databases. GeoLite2 nests country data under country and the ASN fields at the top level as autonomous_system_number and autonomous_system_organization. Ours nests everything under asn.

I checked that the packaged module handles an arbitrary nested schema rather than only MaxMind's own, because Recipe A falls apart otherwise. Building a small MMDB with the asn nesting above and pointing the stock Ubuntu module at it returned asn=15169 org=Google LLC type=BUSINESS on a hit. A miss and an RFC 1918 address both came back as empty strings for every variable, with no error and no refusal to start.

Tip: default= only fires when the lookup misses, so default=ZZ gives you a sentinel country you can filter on later instead of a silent empty string. Useful on the country field, noise everywhere else.

Recipe B: use ready-made variables

The other module skips the mapping. You load files, it exposes variables.

http {
    # Declaration order is priority order: the first database
    # containing a requested field answers for it.
    ipgeolocation_db /etc/nginx/ipgeo/db-ip-geolocation.mmdb;
    ipgeolocation_db /etc/nginx/ipgeo/db-ip-asn.mmdb;
    ipgeolocation_db /etc/nginx/ipgeo/db-ip-security.mmdb;

    # Default is `on`, which reads the leftmost X-Forwarded-For value.
    # See the client IP section below before you leave it that way.
    ipgeolocation_trust_forwarded_header off;
}

That gives you $ip_country_code, $ip_city_name, $ip_asn, $ip_asn_organization, $ip_asn_type, $ip_threat_score and about seventy more, with no paths to maintain. Booleans normalise to 1 and 0, and array fields like VPN provider names join into one comma-separated string. Build steps and the full variable list are in the module's build and variable docs.

The cost is the build. It compiles into nginx against libmaxminddb, and a dynamic build has to match your running binary exactly or nginx rejects it as not binary compatible. Reuse the flags from nginx -V and add --with-http_realip_module, which is not built by default and which you will want in a moment.

One genuinely nice property: if a database fails to open, nginx refuses to start. A typo in a path is caught at deploy rather than becoming empty columns you notice three weeks later.

A JSON access log format that survives empty values

An nginx log_format is a string template with no idea what JSON is. That is where these setups break, and it has nothing to do with geolocation.

log_format geo_json escape=json '{'
    '"time":"$time_iso8601","ip":"$remote_addr","status":"$status",'
    '"country":"$geo_country","city":"$geo_city",'
    '"asn":"$geo_asn","asn_org":"$geo_asn_org","asn_type":"$geo_asn_type"'
'}';

access_log /var/log/nginx/access.geo.log geo_json;

Every value is quoted, including the ones that look numeric. That is deliberate. Private addresses, unlisted ranges, and any miss resolve to an empty string, and an unquoted empty value produces this:

{"ip":"127.0.0.1","threat":,"ok":"US"}

That is not valid JSON. I ran it through a parser to be sure, and it fails outright at the empty value. Quoted, the same miss writes "threat":"", which parses and lets you decide what an empty score means downstream.

escape=json handles the other half. City names and organisation names contain quotes, backslashes and non-ASCII characters, and without it one Turkish city name corrupts the line for every parser reading that file.

One subtlety worth knowing, because the nginx log module docs blur it. Their note that a hyphen is logged when the variable value is not found applies to variables that are genuinely unset, like $upstream_addr on a request that never reached an upstream. A geo module on a miss gives you a variable that exists and is empty, which is a different case and logs as empty. I tested both under each escape mode. The practical upshot: under escape=default an unset variable becomes the string -, which sails through a JSON parser and then poisons anything casting that field to a number. Under escape=json you get "" instead.

Get the client IP right before you log it

If nginx sits behind a load balancer, everything above geolocates your load balancer.

The fix differs by module, and one of the defaults is dangerous.

Module	Default source	How to correct it
`ngx_http_geoip2_module`	`$remote_addr`	Set `geoip2_proxy` for trusted ranges, or `source=$variable`
`ngx_http_ipgeolocation_module`	Leftmost `X-Forwarded-For`	Set `ipgeolocation_trust_forwarded_header off` and use realip

The second default is the one to watch. The leftmost X-Forwarded-For value is written by the client. Plenty of proxies append to that header instead of replacing it, so a visitor can send their own and choose which country they appear from. If your log is decorative, that costs you nothing. If anything reads it to make a decision, it is a hole.

http {
    ipgeolocation_trust_forwarded_header off;  # ignore the client-supplied header

    set_real_ip_from 10.0.0.0/8;               # your load balancer CIDR, nothing wider
    real_ip_header   X-Forwarded-For;
    real_ip_recursive on;                      # walk back past trusted hops
}

The realip module rewrites $remote_addr to the real client before the geo lookup runs, using only hops you named. Both modules then geolocate the right address. Get the trusted range wrong and you are back to trusting the client, so keep it tight.

Derive fields at write time

Once the variables exist you can compute things before the line is written, which beats doing it in every query later.

# ASN type casing varies between sources, so match case-insensitively.
map $geo_asn_type $is_hosting {
    default      0;
    "~*hosting"  1;
    "~*business" 0;
}

# Strip an AS prefix if your database renders one, so the field is
# always a bare number for whatever parses the log.
map $geo_asn $asn_num {
    default   $geo_asn;
    "~^AS(?<n>\d+)$"  $n;
}

# Datacenter traffic into its own file. A request is skipped when the
# condition is 0 or empty, so misses stay in the main log.
access_log /var/log/nginx/access.hosting.log geo_json if=$is_hosting;

Splitting hosting traffic out is useful because ASN type tells you whether an address belongs to a hosting network. It does not tell you whether the request is human or automated, so treat it as context rather than identity.

Keeping databases fresh without dropping requests

Both modules memory map the file. Overwriting it in place is how you get workers reading half a file.

#!/bin/sh
set -e
DIR=/etc/nginx/ipgeo
curl -fsSL "$DOWNLOAD_URL" -o "$DIR/db-ip-asn.mmdb.tmp"

# Same filesystem, so mv is atomic. cp and wget -O are not.
mv "$DIR/db-ip-asn.mmdb.tmp" "$DIR/db-ip-asn.mmdb"

# Never reload onto a truncated download.
nginx -t && nginx -s reload

With auto_reload set, the packaged module picks the new file up on its own and you can drop the reload line. Without it, reload. Either way the atomic mv is not optional.

If you are on GeoLite2, the licence terms require you to keep the data current, and geoipupdate is the supported path. Update cadence varies by database: IPGeolocation publishes refreshed databases daily, while MaxMind currently publishes GeoLite ASN every weekday and GeoLite City and Country on Tuesdays and Fridays.

Write time, ingest time, or query time

Doing this in nginx is one of three places, and it is not always the right one.

	Write time (nginx)	Ingest time (pipeline)	Query time (dashboard)
Request latency	none, local lookup	none	none
Database lives on	every web node	one pipeline node	one place
Re-enrich old logs	not possible	reprocess	free
Reflects	the moment of the request	the moment of ingest	today's data

The trade is historical accuracy against flexibility. A write-time country is what that address resolved to when the request happened, which is what you want for an incident review and wrong when an address changes hands and you need to re-attribute.

My rule: enrich at write time when nginx already needs the data to make a decision, because the lookup is happening anyway and the log line is free. Otherwise enrich at ingest, where one node holds the database and you can reprocess. If you are running the Elastic Stack there is a companion piece on enriching at ingest instead, and if you want these fields on a map there is one on shipping them to Loki and plotting them in Grafana.

What to do with the ASN column

A country column gets looked at. An ASN column mostly does not, which is a waste, because it is the field that tells you who actually owns the traffic.

Start by ranking:

jq -r '.asn_org // empty' /var/log/nginx/access.geo.log \
  | sort | uniq -c | sort -rn | head -20

Your top twenty organisations usually cover most of your traffic. That is a small enough set to enrich properly, once, instead of per request:

import os
import sys
import requests

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


def describe(asn):
    """Fetch routing context for one ASN. Returns None on any failure."""
    if not API_KEY:
        raise RuntimeError("IPGEO_API_KEY is not set")

    try:
        resp = requests.get(
            ASN_URL,
            params={
                "apiKey": API_KEY,
                "asn": asn,
                # Relationships cost nothing extra; the charge is per ASN.
                "include": "upstreams,peers",
            },
            timeout=(2.0, 10.0),
        )
        resp.raise_for_status()
    except requests.RequestException as exc:
        print(f"lookup failed for {asn}: {exc}", file=sys.stderr)
        return None

    data = (resp.json() or {}).get("asn") or {}
    return {
        "number": data.get("as_number"),
        "org": data.get("organization"),
        "type": data.get("type"),
        "rir": data.get("rir"),
        "ipv4_routes": data.get("num_of_ipv4_routes"),
        "upstreams": [u.get("as_number") for u in data.get("upstreams") or []],
    }

Twenty organisations is twenty lookups, once, cached in whatever you already run. The response carries more than the database does, including the official ASN handle, allocation status, announced route counts, and the upstream and peer relationships:

{
  "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": "91",
    "num_of_ipv6_routes": "5",
    "rir": "RIPE"
  }
}

Note the route counts and as_number come back as strings here too. Consistency, at least.

A few extra notes

IPv6. Both modules look up whichever address the client connects with, so the only thing that usually goes wrong is nginx not listening on v6 at all. Check for listen [::]:80;.

Private addresses. Internal health checks and anything behind a NAT will log empty geo fields forever. That is correct behaviour, not a misconfiguration, and it is the main reason the quoting rule above matters.

Retention. An IP address can be personal data, and in access logs where it can reasonably be linked to a visitor it should generally be treated that way. Adding city-level geolocation is additional processing. Enriching at write time means that data lands in a file that may have a longer retention period than your application database, so check the retention policy before turning this on fleet-wide.

Stream traffic. The packaged module works in stream blocks if you compiled with --with-stream, so TCP proxying can carry the same data. The other module is HTTP only.

Decide what an empty value means to you before you write a single if against these variables, because nginx treats both 0 and empty as false and that turns a missing database into a silently permissive rule. And pin your module build to your nginx version in CI. The one that bites is a routine package upgrade moving nginx out from under a dynamic module that was compiled against the old one.

Build a Grafana Geomap of Traffic and Threat Score

ABDULLAH AFZAL — Mon, 28 Sep 2026 16:31:11 +0000

A Grafana Geomap showing traffic by country and coloured by threat score takes about an hour to build. Almost none of that hour is the map.

The map is a built-in panel and it does what you'd expect. The work is upstream: getting a country code and a risk score onto every log line, cheaply enough that you're not paying per request for the privilege. And if you search for this, you'll find a pile of tutorials that solve it with a panel that stopped loading in May 2025.

TL;DR

Use the Geomap panel. The Worldmap plugin is AngularJS, and Angular support was removed outright in Grafana 12.
Enrich the log line at the edge with an Nginx module reading local MMDB files, or batch-enrich unique IPs through an API and cache the result. Both work. They fail at different scales.
Ship with Alloy, not Promtail. Promtail was removed from Loki in 3.7.3.
Colour the map by max threat score, size markers by request count. Don't average them.
The gotchas that will eat your afternoon: latitude and longitude come back as strings, Geomap only auto-detects a field literally named lookup, and X-Forwarded-For is spoofable. You'll end up with one panel that answers two questions at once: where is my traffic from, and how much of it should I be worried about. The second question is the one nobody's dashboard answers.

What you're building

One Geomap panel. Countries shaded by the highest threat score seen from that country in the window, with a circle marker sized by request volume sitting on top. A country that's big and green is fine. A country that's small and red is the one you want to click into.

The pipeline is four pieces: Nginx writes a JSON access log that already contains the country and the risk score, Alloy tails it, Loki stores it, Grafana queries it. Nothing here is exotic. The only decision that matters is how the country and score get into that log line, which is the next section and the bulk of the article.

I'm using Nginx because it's what most people reading this have in front of them. Traefik, Caddy, or an ALB with structured logs all work the same way once the fields exist; only the enrichment step changes.

Why the tutorial you found doesn't work

Worth two minutes before you copy anything from elsewhere.

Worldmap is gone, not deprecated

The Worldmap Panel plugin page says it's deprecated and points you at Geomap, now the only world map panel Grafana ships. The repo was archived on January 23, 2025. More importantly, Worldmap is an AngularJS plugin, and Angular support was removed entirely in Grafana 12. There's no config toggle to bring it back.

So this isn't a "you should migrate eventually" situation. On any supported Grafana, a Worldmap panel doesn't render. Dashboards on grafana.com still ship it, blog posts from December 2025 still teach it, and if you ask ChatGPT this question it'll tell you to install the plugin. I tried. It did.

Promtail was deleted

The Loki 3.7 release notes put it plainly: Promtail was deprecated in Loki 3.0 and has been removed as of 3.7.3. The code lives in Alloy now.

If you've got a promtail-config.yaml you like, alloy convert --source-format=promtail --output=config.alloy promtail-config.yaml will port it. One command, and then you never think about it again.

Getting country and threat score into the log line

Two ways to do this. They're genuinely different architectures, not variations, and the right answer depends entirely on how many unique IPs you see.

For the data itself, the usual suspects are IPGeolocation, MaxMind GeoIP2, ipinfo, ip-api, IP2Location, and IPLocate. They'll all give you a country. Where they diverge is risk: a composite threat score with VPN, proxy, residential proxy, Tor, and known-attacker flags behind it is a narrower field, and it's the reason I'm using ipgeolocation.io for the examples here. Swap in whatever you already pay for; the panel work at the end is identical.

Path A: enrich at the edge

An Nginx module reads MMDB files off local disk and exposes the data as native $ip_* variables. No outbound request, no per-request cost, lookups happen in-process against a memory-mapped file.

http {
    # Declaration order is priority order. First DB with the field wins.
    ipgeolocation_db /etc/nginx/ipgeo/db-ip-geolocation.mmdb;
    ipgeolocation_db /etc/nginx/ipgeo/db-ip-security.mmdb;

    # Off, because the leftmost X-Forwarded-For value is client-controlled.
    # See the note below before you flip this.
    ipgeolocation_trust_forwarded_header off;

    # Let realip establish the true peer from trusted proxies only.
    set_real_ip_from  10.0.0.0/8;
    real_ip_header    X-Forwarded-For;
    real_ip_recursive on;

    # escape=json stops a quote in a city name from breaking every downstream parser.
    log_format geo_json escape=json '{'
        '"time":"$time_iso8601","ip":"$remote_addr","status":"$status",'
        '"country":"$ip_country_code","city":"$ip_city_name",'
        '"asn":"$ip_asn","org":"$ip_asn_organization",'
        '"vpn":"$ip_is_vpn","proxy":"$ip_is_proxy","tor":"$ip_is_tor",'
        '"threat":"$ip_threat_score"}';

    access_log /var/log/nginx/access.geo.log geo_json;
}

Every variable resolves from whichever database contains it, so $ip_country_code comes from the geolocation file and $ip_threat_score from the security file, automatically. Build instructions and the full variable list are in the Nginx module docs; you compile it into Nginx against libmaxminddb, which is the main friction in this path.

The ipgeolocation_trust_forwarded_header off line is the one people get wrong. Default is on, which reads the leftmost X-Forwarded-For address. Plenty of load balancers append to that header rather than replacing it, which means a visitor can send their own X-Forwarded-For and pick which country they show up as on your map. If your map is decorative, fine. If you're going to make decisions from it, turn it off and let realip work out the true client from proxies you actually trust.

Pitfall: never overwrite a live .mmdb in place with cp or wget -O. The module memory-maps the file and workers can read a half-written one. Download to a temp file in the same directory, mv it over, then nginx -t && nginx -s reload.

The trade-off, stated once: this costs nothing per request and adds no latency, but you're rebuilding Nginx from source and licensing a database. That's a real tax if you've got one small VPS. It's nothing if you've got forty.

Path B: batch-enrich unique IPs through an API

No Nginx rebuild. Log the raw IP, then enrich out of band on a schedule and join at query time.

The trick is that you enrich unique IPs, not requests. A million requests a day from twelve thousand distinct addresses is twelve thousand lookups, not a million.

import os
import logging
import requests

API_KEY = os.environ.get("IPGEO_API_KEY")
BULK_URL = "https://api.ipgeolocation.io/v3/ipgeo-bulk"

# The endpoint takes 50,000 IPs per call. Smaller chunks fail cheaper and retry faster.
CHUNK = 1000

log = logging.getLogger(__name__)

Now the enrichment itself. The two things doing real work here are the bogon skip and the X-Credits-Charged header, and neither is obvious until the first time you get a surprise invoice.

def enrich(ips):
    """Return {ip: {"country": str, "threat": int}} for a list of unique IPs."""
    if not API_KEY:
        raise RuntimeError("IPGEO_API_KEY is not set")

    out = {}

    for i in range(0, len(ips), CHUNK):
        batch = ips[i:i + CHUNK]
        try:
            resp = requests.post(
                BULK_URL,
                params={
                    "apiKey": API_KEY,
                    "include": "security",
                    # Trim the payload. Bulk responses get large fast.
                    "fields": "location.country_code2,security.threat_score",
                },
                json={"ips": batch},
                timeout=(3.0, 30.0),
            )
            resp.raise_for_status()
        except requests.RequestException as exc:
            # Fail open: a missing enrichment loses map detail, it doesn't drop logs.
            log.warning("Enrichment batch %d failed: %s", i // CHUNK, exc)
            continue

        # Actual charge, not your estimate of it.
        log.info("Batch %d charged %s credits",
                 i // CHUNK, resp.headers.get("X-Credits-Charged", "?"))

        for rec in resp.json():
            # Private and bogon IPs come back as {"message": "... is a bogon IP address."}
            # and aren't billed. Access logs are full of them.
            if "message" in rec or "ip" not in rec:
                continue

            country = (rec.get("location") or {}).get("country_code2")
            threat = (rec.get("security") or {}).get("threat_score")
            if country:
                out[rec["ip"]] = {"country": country, "threat": threat or 0}

    return out

Write that output to Redis or a Postgres table keyed on IP, run it every fifteen minutes against IPs you haven't seen before, and join it in at query time.

Two things to know before you commit to this path. Bulk and include=security are both paid-only; a free key returns 401 on either. And geolocation plus security is 3 credits per IP, so the $19 Starter plan's 150,000 credits buys you about 50,000 unique IPs a month. That's a comfortable fit for a mid-sized site and completely wrong for a big one.

So which one

If you see under about 50,000 unique IPs a month and you don't control the Nginx build, Path B. It's less setup and the cost is predictable.

Above that, Path A, and it stops being close. At a million unique IPs the API path is a line item and the database path is the same price it was at ten thousand. The Nginx rebuild feels like the complicated option right up until the moment it's the only one that makes sense.

Either way, the log line you end up with is the same shape, and everything below this point doesn't care which one you picked.

Shipping to Loki with Alloy

local.file_match "nginx" {
  path_targets = [{
    "__path__" = "/var/log/nginx/access.geo.log",
    "job"      = "nginx",
  }]
}

loki.source.file "nginx" {
  targets    = local.file_match.nginx.targets
  forward_to = [loki.process.nginx.receiver]
}

loki.process "nginx" {
  stage.json {
    expressions = {
      country = "country",
      status  = "status",
    }
  }

  // Label only what you group by. threat stays in the line on purpose.
  stage.labels {
    values = {
      country = "",
      status  = "",
    }
  }

  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = sys.env("LOKI_PUSH_URL")
  }
}

Save as config.alloy, run alloy run config.alloy.

That comment about labels is the important line in the file. country and status are bounded sets, so they make fine labels. threat is an integer from 0 to 100, and promoting it to a label would multiply your stream count by up to a hundred for no benefit. Leave it in the log line and let the query parse it. Same goes for ip, which is the single fastest way to melt a Loki instance.

Building the panel

Three settings decide whether a Grafana map renders anything useful: the shape of the query, the location mode, and what you bind colour and size to. In that order.

The queries

Two queries, both set to Instant rather than Range. A map wants one value per country, not a time series per country.

Query A, the colour:

max_over_time(
  {job="nginx"}
  | json
  | unwrap threat
  | __error__=""
  [$__range]
) by (country)

Query B, the size:

sum by (country) (
  count_over_time({job="nginx"}[$__range])
)

A few things worth knowing here. max_over_time needs an unwrap to get a number out of a log line, and count_over_time breaks if you give it one. That asymmetry catches people. The | __error__="" after the unwrap is doing real work: when an IP isn't in the database the field comes back empty, unwrap fails on it, and without the filter those errors poison the result. It has to sit after the unwrap, because only label filters can follow one.

Query B doesn't need | json at all, since country is already a stream label. Parsing you don't need is parsing you pay for.

Then add a Join by field transformation on country to merge the two results into one frame. Without it, Geomap sees two unrelated tables and draws nothing useful.

Location mode, and the trap

This is the step that silently produces an empty map.

Geomap's Auto location mode only detects fields named exactly geohash, latitude / lat, longitude / lng / lon, or lookup. Our field is called country, so Auto finds nothing and you get a basemap with no markers and no error message.

Set it explicitly instead: Lookup mode, with Lookup field country and Gazetteer Countries. The built-in gazetteer takes ISO 3166 alpha-2 and alpha-3 codes, and $ip_country_code / country_code2 are both alpha-2, so they map straight through.

You could also just name the field lookup in your LogQL and let Auto handle it. I'd rather have a readable field name and two extra clicks.

Heads up: if you're tempted to use coordinates instead of country codes, note that the API returns location.latitude and location.longitude as strings, not numbers. Geomap's Coords mode wants numeric fields. You'll need a Convert field type transformation, and for a country-level map the coordinates buy you nothing anyway.

Colour and size

Marker colour from the threat field, marker size from the count field.

For thresholds, the bands I use:

Score	Read it as
0-19	Background noise
20-44	Worth context before acting
45-79	Add friction, don't block
80-100	Manual review territory

And the opinion this whole panel rests on: use max, not mean.

An average threat score per country is worse than no score. A country sending you 40,000 clean requests and 60 requests from a residential proxy network averages out to roughly zero, the map goes green, and the thing you built this to see is the thing it hides. Max surfaces it. Then the size marker tells you whether that max came from a country sending you real traffic or from three requests you can ignore.

If max feels too jumpy once you've watched it for a week, quantile_over_time(0.95, ...) is the sensible next stop. Mean isn't.

Basemap

Default basemap is CARTO, and it's the right default. Set the theme to match your dashboard rather than leaving it on auto, because auto-switching a basemap under a fixed threshold palette makes your reds look different depending on someone's OS setting.

Turn showLabels off. Country names printed under semi-transparent markers is a mess, and the tooltip already tells you which country you're hovering.

Reading the threat map without overreacting

A red country is not an attack. It's a signal that something in that country's traffic tripped a detection, and the detections cover a lot of ground.

is_relay fires on iCloud Private Relay. is_corporate_gateway fires on Zscaler and similar egress. is_anonymous fires on all of it. Those are your customers: someone on an iPhone with Private Relay on, or an employee behind their company's secure web gateway. Blocking on those flags means blocking paying users, and you'll find out slowly through support tickets rather than quickly through an alert.

What's actually interesting is shape. A country with a high max threat score and low volume is usually one scanner and not worth your morning. A country with a high max score, high volume, and a sudden change from yesterday is the one to click into, and that's where the asn, org, and proxy fields you logged start paying off: residential proxy traffic spread across dozens of consumer ISPs in one country looks very different from one datacenter ASN hammering /wp-login.php.

Use the map for triage. Enforce somewhere with more context.

A few extra notes

IPv6 works but the country labels get patchy. Both paths handle v6 addresses fine. Coverage on recently allocated v6 blocks is thinner than v4 across every provider I've used, so expect a few empty country values in a v6-heavy audience. They'll drop out via the __error__ filter rather than breaking anything.

Refresh the databases on a schedule. Path A databases publish daily. A cron entry doing the atomic-swap dance and a reload is enough. Stale security data degrades quietly, which is the worst way for data to degrade.

Empty countries usually mean private IPs. If a chunk of traffic has no country, check whether you're geolocating your load balancer instead of your visitors. That's the realip config, not the database.

Log retention is a GDPR question now. An IP plus a city is personal data in most of the jurisdictions that care. Whatever retention policy you have for access logs already applies; just don't accidentally give this one a longer one because it's in a nicer dashboard.

Where this breaks first

Cardinality, and sooner than you'd think. country and status as labels are fine. The first time someone adds ip or asn to stage.labels because they want to filter on it in the panel, your stream count explodes and query times go with it. Filter on parsed fields at query time instead; it's slower per query and enormously faster overall.

If you're standing this up on a single node, the panel will feel instant for months and then won't. That's the moment to look at what you labelled, not at your Loki resources.

Route Risky Signups Automatically With n8n

ABDULLAH AFZAL — Mon, 28 Sep 2026 08:15:22 +0000

A signup fraud check in n8n often comes down to one IF node: if is_vpn is true, block. It runs, it looks reasonable on the canvas, and it still gets the decision wrong in both directions.
It blocks legitimate VPN users, including employees whose company routes traffic through a corporate VPN. It misses privacy relays such as iCloud Private Relay, and it can wave through a residential proxy that is not also classified as a VPN.

The fix isn't a better boolean. It's a score with four branches under it.

TL;DR

One lookup returns a 0 to 100 threat score plus 28 fields explaining how it got there
Route on the score, override on the flags. Corporate gateway and relay traffic needs handling before the score is read, not after
The published bands are 1-19 allow, 20-44 add context, 45-79 add friction, 80-100 block or send to review
A Switch node with four outputs does the routing. No Code node required
Security lookups cost 2 credits, so a 150,000 credit month covers 75,000 scored signups The workflow is a webhook, one lookup node, one override check, and a Switch with four outputs. Every signup gets a number, every number gets a branch, and the two categories that break naive VPN rules get handled before the score is read. Build time is under an hour.

What one IF node gets wrong

Three failure cases, and they're not edge cases.

Corporate gateways. Zscaler, Netskope and other secure web gateways route an entire workforce through a handful of egress IPs. Take 87.58.66.106: threat score 5, is_corporate_gateway: true, corporate_gateway_provider_name: "Zscaler". And is_anonymous stays false, because a gateway isn't hiding anyone. It's an identifiable company inspecting its own employees' traffic. Block that IP and you haven't blocked a fraudster, you've blocked a company. If you sell B2B, that's the buyer evaluating your product from inside their own network.

Privacy relays. iCloud Private Relay and Cloudflare WARP set is_relay, not is_vpn. A rule written against is_vpn won't catch them, which is the right outcome. Catching them means turning away iOS users who never opted into anything unusual.

Residential proxies. 145.223.7.7 sits on an ASN registered as an ISP. It's also a residential proxy with four provider names attached, a VPN exit, a spam source and a known attacker, scoring 90. A "is this a datacenter range" check clears it. An is_vpn check happens to catch this particular one, but only because it doubles as a VPN. A residential proxy that doesn't would sail straight through.

The pattern in all three: the flag tells you what the IP is. It doesn't tell you what to do. Those are different questions and the second one needs more than one bit.

The signals you actually route on

Here's the complete security object for that residential proxy IP. Not a trimmed version, because the fields you ignore today are the ones you'll want when you start tuning.

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

Twenty-eight fields. Three of them change how you build this.

The confidence scores

proxy_confidence_score and vpn_confidence_score grade each detection 0 to 100 independently of the threat score. A VPN detection at 99 with a vpn_last_seen of last week is not the same signal as one at 40 last seen in March. If you're going to add friction at a threshold, the confidence score is what tells you whether to make that friction an OTP or a hard stop.

The two flags that outrank the score

is_corporate_gateway and is_relay both need special handling, but for different reasons. A corporate gateway is shared enterprise egress and is not treated as anonymous. A relay is an anonymizing privacy route such as iCloud Private Relay or Cloudflare WARP, but relay use alone is normally a low-risk signal. Neither should be blocked simply because of what it is. Check explicit attacker or attack-bot signals first, then use these flags to avoid unnecessary friction from the generic score.

That also means the workflow should not blindly send is_relay: true straight to Allow if is_known_attacker is also true.

bot_type, if you care about automation

is_bot alone treats Googlebot and a credential-stuffing script identically. bot_type separates them by activity: search_engine, ai_crawler, scanner, scraper, brute_force, credential_stuffing, exploit, worm. Pair it with is_known_good_bot and you can allow declared crawlers while blocking the four attack types, which always come back with is_known_attacker: true already set.

For a signup flow this matters less than it does at your edge, since bots rarely complete a signup form. Worth knowing the field exists before you write a rule against a bare is_bot.

The routing matrix

These bands are the published threat score scale, not thresholds I made up. Start here, then tune against your own traffic.

Score	Published guidance	Your branch	What actually happens
1-19	Allow with standard controls	Allow	Create the account. Log the score
20-44	Combine with other signals before acting	Verify	Email verification before first login
45-79	Add friction before allowing access	Review	Create the account, flag it, hold trial credits
80-100	Block, hard challenge, or manual review	Block	Reject, alert, log everything

A worked example per band, using real addresses you can check yourself:

IP	Score	Why	Branch
`87.58.66.106`	5	Zscaler gateway, not anonymous	Allow
2.56.188.35	35	Known attacker history, so the attacker override applies	Block
223.197.196.92	40	bot_type: brute_force, which also sets is_known_attacker	Block
`145.223.7.7`	90	Residential proxy, VPN, spam, attacker	Block

I don't have a verified sample in the 45-79 range to show you. The band exists and the guidance is published, but I'd rather say that than invent a payload that looks authoritative and isn't. If you run this on real traffic you'll find your own inside a week, and those are the ones worth studying anyway.

Pitfall: don't copy those four branch actions as-is. A consumer app and a fintech onboarding flow have different tolerances for a false positive at 40. Run the workflow in log-only mode for a week first, look at where your actual signups cluster, then set the boundaries.

Building it

Send the IP from your app

The first mistake is trying to work out the signup IP from inside n8n. Your webhook sees whatever hop reached it, which behind a proxy or load balancer is the proxy. Capture the client IP in your app, where you already know your own trust-proxy configuration, and send it in the webhook payload.

That makes the IP available as {{ $json.body.ip }} in the node that follows.

Add the lookup node

Search for IPGeolocation in the node panel. It's verified by n8n, so it installs from search in one click with no npm setup. On self-hosted, an instance owner does that once and everyone on the instance gets it.

Pick the Get IP Security action and paste your API key into the credential once. That key then works across every operation from the same node, which matters later if you add an ASN or abuse-contact lookup to the same flow.

One thing to know up front: Get IP Security is a paid operation. The free tier covers geolocation, timezone, time conversion and astronomy, and a free geolocation lookup does still return the ASN and the network owner. That's enough for a crude hosting-versus-ISP split if you want to prototype the shape of the workflow before paying for anything, but it won't give you a threat score.

I'm using IPGeolocation here because the security response carries provider names and confidence scores in the same call as the score, which is what makes a four-branch route possible without a second lookup. Greip has an n8n node with IP scoring, IPQualityScore and AbuseIPDB are both common in n8n fraud templates, and MaxMind minFraud is the enterprise option. They return different shapes. If you swap one in, the routing logic holds and the field names won't.

Override before you score

Add an IF node between the lookup and the Switch. Condition: {{ $json.security.is_corporate_gateway }} is true, or {{ $json.security.is_relay }} is true.

True output goes straight to Allow. These are shared addresses belonging to identifiable organisations, and the useful move is the opposite of blocking: relax your per-IP rate limits, and stop using the IP as a deduplication key. One Zscaler egress will happily produce forty signups from forty real employees, and any "more than three accounts from one IP" rule will read that as an attack.

False output continues to the Switch.

The Switch

Add a Switch node in Rules mode with four outputs, reading {{ $json.security.threat_score }}:

Output	Condition
Allow	less than 20
Verify	20 to 44
Review	45 to 79
Block	80 or above

Set a fallback output and send it to Verify. If the score is missing or arrives as something unexpected, a new signup getting an email verification is a cheap wrong answer. Silently allowing it is not.

Wire whatever you already use to each output. Slack alert on Block, a row in your review sheet on Review, your normal welcome sequence on Allow. The routing is the article; the destinations are yours.

When the lookup fails

Every node that calls an external service will eventually not get an answer. In n8n that's the On Error setting in the node's settings tab, and the choice you make there is a policy decision, not a config detail.

For signups, fail open. Set the lookup node to continue using its error output, wire that output to Verify, and log it. A scoring API being unreachable should never stop someone creating an account, and email verification is a reasonable default for a signup you couldn't score.

For anything where money moves, flip it. A payment or payout flow should fail closed and hold the transaction for review, because the cost of letting one through unscored is higher than the cost of making someone wait.

Say which one you picked in a sticky note on the canvas. Six months from now, when someone asks why unscored signups end up in the verification queue, that note is the answer.

Fraud detection automation without an LLM in the decision path

n8n's template gallery has several fraud workflows that pass the event to a language model and ask it to assess risk. I'd push back on that for this job.

A threat score is a number produced by enumerating proxy infrastructure, running honeypots and watching behaviour over time. Asking a model to look at that number and decide adds latency, cost per signup, and non-determinism to a decision that was already made. It also destroys your audit trail. When a customer emails asking why their signup was blocked, "the model thought it was risky" is not an answer you can defend, and in some jurisdictions it's not an answer you're allowed to give.

Score deterministically. Branch deterministically. Then, if you want, let a model write the Slack message that explains the block in plain English to whoever's on duty. Explanation is a good use of a model. Adjudication isn't.

This is the part of n8n fraud detection people get backwards most often, and it's understandable, because the LLM node is the interesting one on the canvas. The boring Switch is the one doing the work.

What it costs

Billing is in credits rather than requests, and the arithmetic is worth doing before you build.

A security lookup costs 2 credits. The free tier gives you 1,000 credits a day but excludes security entirely, so this workflow needs a paid plan. Starter is $19 a month for 150,000 credits, which is 75,000 scored signups. If you're processing more signups than that you have problems this article can't help with.

If you want location alongside the score, the unified endpoint charges 1 credit for the lookup plus 2 for the security module, so 3 total. Worth it when you're also routing on country. Wasteful when you only need the number.

For backfilling accounts you already have, the bulk security operation takes up to 50,000 IPs in one call at the same 2 credits per valid IP. Bogons and private addresses aren't charged, which makes it safe to throw a messy export at it.

A few extra notes

IPv6 works on every operation, so you don't need a separate path for it. Worth confirming your app is actually capturing the v6 address rather than a mapped form.

If you're storing threat scores against user records and you serve EU users, that's IP data linked to an identifiable person. Set a retention window based on how long the data is actually needed for fraud prevention, document that choice, and make sure your privacy disclosures cover the processing. Scores are cheap to recompute and expensive to hold.

The bogon response is HTTP 423 rather than a 200 with empty fields, which means a private IP leaking into your webhook shows up as an error rather than a silent zero. Route that error output to Verify along with the other failures and you'll spot the leak in your logs instead of scoring 10.0.0.1 as clean forever.

Run this in log-only mode first. Connect all four Switch outputs to the same "create account" path plus a logging step, leave it a week, then look at the distribution before you turn on the branching. If a tenth of your legitimate signups land at 30, your Verify boundary is in the wrong place, and you'd rather learn that from a spreadsheet than from a support queue.

If you'd rather have this as middleware than as a workflow, the same scoring logic in Express and Flask covers the code version, including Redis caching. You'll need an API key with security access either way.

Start with the override IF node even if you skip everything else. Most of the damage a fraud rule does isn't the fraud it misses, it's the customer it turns away at the door.

DEV Community: ABDULLAH AFZAL

What Is Google's ASN? Why the Answer Is a List

TL;DR

Google ASN list, sorted by job

Why one company ends up with multiple ASNs

An AS is a routing policy, not a company

Customer traffic gets its own number

Legal entities live in different registries

Regulated and private networks

Acquisitions keep their numbers, or get folded in

How Google, Amazon, and Microsoft lay it out

Google splits by who's on the other end

Amazon runs one giant ASN and a few specialists

Microsoft: one 1997 block and a long tail

How to group IP traffic by organization

Name matching breaks on the first comma

Pick a key that survives

Group twice: parent for reporting, function for policy

Check who's behind the prefix

A few extra notes

EU Geo-Blocking Regulation: Redirects, Forms, Payments

What the EU geo-blocking regulation actually covers

Three articles, three places in your stack

Article 3 is your front door

Article 4 is your checkout form

Article 5 is your payment step

The copyright carve-out most developers misread

When is geo-blocking legal in the EU?

When another law requires it

What the July 2026 Anne Frank ruling changed

Patterns that keep your country checks legal

Suggest, don't redirect

Forms, payments and legally required blocks

How seriously is this enforced?

What's changing in 2026

How Does an IP to Company Lookup Actually Work?

TL;DR

What an IP to company lookup actually returns

How an IP address gets matched to a company

Registry records: who was given the block

Reassignment filings: the only place a customer's name appears

Routing data: who actually carries the traffic

Enrichment: name, domain, and type

Why the company and the network owner disagree

Where IP to company attribution breaks

Remote workers on home internet

Cloud servers and shared hosting

VPNs and privacy relays

Old, missing, and moved records

How to read a company match before you act on it

Questions to ask an IP to company vendor

How to Detect In-App Browsers: Instagram, TikTok, Facebook

TL;DR

What an in-app browser actually is

In-app browser vs WebView vs Custom Tabs

What breaks inside Instagram, TikTok, and Facebook WebViews

The user-agent tokens each app sends

Which detection checks actually work (tested October 2026)

Why the "iPhone without Safari" check fails now

Why the Android wv check misses Facebook

Detecting in-app browsers in JavaScript

Detecting on the server

Express middleware with the token check

Using a UA parser's type as a second signal

What to do once you know

How long this will keep working

Peering vs Transit vs IXPs: How Networks Actually Connect

TL;DR

Peering vs transit in one table

Transit: renting the rest of the internet

What a transit provider actually sells

Tier 1 is a peering club, not a size

Peering: trading your customers' routes, not the internet

Settlement-free, paid, and why big networks refuse to peer down

Bilateral, private, and route-server peering

An IXP is a place, not a relationship

What a route server does

Why IXPs vanish from AS paths

The rules that make it work: valley-free routing

You never see the contract

Why the Android `wv` check misses Facebook

Using a UA parser's `type` as a second signal