Reference
Reference
A JSON API over HTTP. Send an address, get back its network, continent, country, region, city and coordinates.
Endpoints(8)
- GET/v1/lookup/{ip}Locate one address
- GET/v1/lookup/meLocate the caller
- POST/v1/lookupLocate up to 100 addresses at once
- GET/v1/infoDatabase build, key limits, attribution
- GET/healthzLiveness
- GET/readyzReadiness: a database is loaded
- GET/metricsPrometheus metrics on port 9090
- GET/playground/lookup/{ip}Keyless lookups for the documentation
Guides(3)
Conventions
- Requests and responses are JSON (
application/json, UTF-8). Only the bulk endpoint takes a body. - Fields without data are left out, never sent as
null. Check for presence, not for null. - Every error has the same shape:
{"error": "<code>", "message": "<text>"}. Branch onerror; the message is for people. See Errors. - Responses are never cached (
Cache-Control: no-store) and carryX-Content-Type-Options,X-Frame-Optionsand a deny-all content security policy. - The server speaks HTTP/1.1, and cleartext HTTP/2 when
server.http2is on. Put a TLS-terminating proxy in front of it. - The API sends no CORS headers. Call it from your servers, not from browsers, so keys stay private.
- Results from the default database must credit DB-IP (CC BY 4.0). Lookups carry an
X-Data-Attributionheader with the required text.