Locate any IP address with one request
A self-hosted geolocation API that returns country, city, coordinates, time zone and network owner as JSON. Lookups run against a local copy of MaxMind GeoLite2, so no query ever leaves your server.
Try it
Press Send to look up an address.
Endpoint
GET /json/{ip-or-hostname}?fields={fields}&lang={lang}&callback={fn}
Leave the address out (GET /json) to look up the caller's own IP. Hostnames are resolved to their first address before lookup.
| Parameter | Description |
|---|---|
fields | Which keys to return. Either a comma-separated list (country,city,lat,lon) or a single number: the sum of the field codes in the table below. Use the field picker to build one. |
lang | Language for place names: . Defaults to en; names without a translation fall back to English. |
callback | Wraps the response as JSONP: fn({...}); |
Failures and limits
Lookups that cannot be answered still return HTTP 200 with "status": "fail" and a message: private range, reserved range or invalid query.
There is no request limit by default. To cap usage, set RATE_LIMIT to a number of requests per minute per client IP; responses then carry X-Rl (requests left) and X-Ttl (seconds until the window resets), and going over returns HTTP 429.
Fields
0
Tick a row to include it. Defaults are pre-selected.
| Name | Description | Example | Type | Code |
|---|
Examples
Browser (fetch)
const res = await fetch('/json/8.8.8.8?fields=country,city,lat,lon');
const geo = await res.json();
if (geo.status === 'success') console.log(geo.city, geo.country);
JSONP
<script>function showGeo(geo) { console.log(geo.country); }</script>
<script src="/json/1.1.1.1?callback=showGeo"></script>
curl
curl "http://localhost:3000/json/1.1.1.1?lang=de"