Skip to main content

Looking addresses up

Everything except /health needs the X-Api-Key header.

The routes​

RouteWhat it answers
GET /lookup/{address}Country and continent
GET /details/{address}Everything the databases hold: ASN, city, network, coordinates
POST /lookup/batchAddresses and host names, mixed. Names are resolved and every address they answer with is looked up
GET /statusDatabase state, build dates, sizes, SHA-256, entity tag, last refresh
GET /databases/{edition}The .mmdb file itself
POST /updateRefreshes the databases now

Every lookup route answers whether or not the service is licensed. Unlicensed, the answers are a recognisable placeholder rather than real data, and the databases are neither downloaded nor served. See Licensing. The management routes are listed in the reference.

Looking one up by hand​

The console's Lookup page asks the same question a caller would and shows exactly what the databases hold. It is the fastest way to answer "would a rule matching Germany catch this address", without writing the rule first.

Batches​

One call, addresses and host names mixed. Host names are resolved, and every address they answer with is looked up - a name with four A records produces four answers, not one. One call answers up to 1,000 distinct addresses; beyond that the response is cut off there and says so (truncated). The full record is returned by default; details: false keeps every answer to country and continent.

When a round trip is too expensive​

If your lookups sit on a request path, calling this service per request buys nothing and adds an outage mode: every request now depends on another service being up.

Mirror the file instead. The recipe is in Installing GeoIP - poll /status, conditional GET, verify the digest, atomic rename. Almost every poll answers 304 and transfers nothing.

Rate limits​

Off by default, and per API key rather than per address: the callers here are machines, several can sit behind one NAT, and the key is the only identity this service has.

A caller over the limit gets 429 with a Retry-After, so a client knows when to come back instead of retrying straight into the limit again.

It covers the lookup surface - /lookup, /details, /lookup/batch and /databases - and nothing else:

  • /health is never limited, so an orchestrator's health probe cannot get the container restarted.
  • The management surface is never limited, so a limit set too low can always be raised again, from the Options page or with PUT /options/ratelimit.

Before you switch it on, measure your callers' real traffic and set the limit above it: a limit set too low refuses real lookups with 429, and the callers see only the refusal.

Last updated on