Developer guide · REST · JSON

API documentation

Resolve IPv4 and IPv6 addresses to location and network data. Customer API calls use your own account key and quota. Open the OpenAPI 3.1 specificationfor machine-readable schemas.

Download OpenAPI JSON Quickstart Endpoints

01 · Quickstart

Make your first lookup

Accounts are provisioned by the iplocus team. Contact sales to receive an account, plan, and initial password. Log in to get a short-lived JWT, then create an API key. Public self-registration is closed.

curl -X POST https://iplocus-backend.onrender.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"YOUR_PASSWORD"}'

Use the returned token as a Bearer token to create a key. The raw key is returned once; save it in a secret manager.

curl -X POST https://iplocus-backend.onrender.com/api/keys \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{"name":"production-server"}'

Keep API keys on a trusted server. Do not put a customer key in browser JavaScript, a mobile app bundle, a public repository, or a URL.

curl 'https://iplocus-backend.onrender.com/api/lookup/8.8.8.8' \
  -H 'X-Api-Key: YOUR_API_KEY'

02 · Authentication

Two credentials, two jobs

Lookup API key

Send X-Api-Key: … on lookup requests. All keys under an account share its plan quota. Keys are stored as hashes and listed by prefix only; the original secret cannot be retrieved after creation.

Account JWT

Send Authorization: Bearer … to manage keys and view account usage. Log in at POST /api/auth/login. Never expose the JWT in a public client.

03 · Endpoints

Customer API

Base URL: https://iplocus-backend.onrender.com. All endpoints exchange JSON over HTTPS. The OpenAPI file lists request and response schemas.

GET/api/lookup/{ip}X-Api-KeyLook up one IPv4 or IPv6 address.

GET/api/lookup/meX-Api-KeyLook up the public IP of the API caller.

POST/api/lookup/batchX-Api-KeyLook up up to 100 addresses in one request.

POST/api/auth/loginNoneExchange account credentials for a JWT.

GET/api/keysBearer JWTList your keys; raw key material is never returned.

POST/api/keysBearer JWTCreate a key; its raw value is shown once.

DELETE/api/keys/{id}Bearer JWTRevoke one of your keys.

GET/api/account/usageBearer JWTRead your plan and current-month usage.

One address

curl 'https://iplocus-backend.onrender.com/api/lookup/8.8.8.8' \
  -H 'X-Api-Key: YOUR_API_KEY'

GET /api/lookup/me resolves the public IP of the machine making the API request. If called from your server, that is your server’s IP, not an end user’s browser IP.

Batch addresses

curl -X POST 'https://iplocus-backend.onrender.com/api/lookup/batch' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '["8.8.8.8","1.1.1.1"]'

Send 1–100 addresses. Each submitted item uses one monthly lookup. Quota is reserved for the whole batch before processing; malformed entries return an item-level error.

04 · Response

Location is an estimate

Coordinates represent an approximate network location, not GPS or a street address. VPNs, proxies, mobile carriers, and the source dataset can affect the result. Nullable fields mean data is unavailable for that address. The current dataset has no US country ID row, so US addresses return countryId: 0.

ipstringCanonical IP address that was looked up.

ipDecimalinteger or null32-bit IPv4 integer; null for IPv6.

countryIdintegerInternal country identifier. US addresses currently return 0.

countrystring or nullCountry name in English.

countryCodestring or nullISO 3166-1 alpha-2 country code.

citystring or nullCity when available in the dataset.

regionstring or nullFirst-level subdivision such as a state or province.

postalstring or nullPostal or ZIP code when available.

latitudenumber or nullApproximate latitude; an area estimate, not GPS.

longitudenumber or nullApproximate longitude; an area estimate, not GPS.

timezonestring or nullIANA time zone, such as Europe/Belgrade.

asninteger or nullAutonomous system number.

asnOrgstring or nullNetwork or ASN organisation name.

demoboolean, optionalTrue only for the backend's local development fallback.

05 · Quotas and errors

Know what counts

Each successful single lookup uses one monthly unit. A batch costs one unit per submitted address.
Successful lookup responses include X-Quota-Limit and X-Quota-Remaining.
All API keys on an account share its plan’s calendar-month allowance. Contact sales for plan details or an increase.
The public website demo is separate: 50 requests per public IP in a rolling 24 hours, plus a shared 1,000-request monthly cap. Refreshing does not reset it. People sharing a public IP share that daily limit.
HTTP 400 means invalid input; 401 means missing or invalid credentials; 403 means the account action is not allowed; 404 means the resource is not found; 429 means a quota or abuse limit was reached; 5xx means a temporary service issue.

{
  "error": "Monthly quota exceeded.",
  "monthlyQuota": 1000,
  "used": 1000,
  "requested": 1
}

The website’s automatic self-lookup and manual demo searches also return a Retry-After header when the per-IP daily cap is full. The dedicated demo account protects customer quotas from public demo traffic.

06 · Examples

Call from your server

Node.js server-side JavaScript:

const response = await fetch(
  "https://iplocus-backend.onrender.com/api/lookup/8.8.8.8",
  { headers: { "X-Api-Key": process.env.IPLOCUS_API_KEY } }
);

if (!response.ok) {
  throw new Error((await response.json()).error ?? "Lookup failed");
}

const location = await response.json();
console.log(location.country, location.city, location.asnOrg);

Python:

import os
import requests

response = requests.get(
    "https://iplocus-backend.onrender.com/api/lookup/8.8.8.8",
    headers={"X-Api-Key": os.environ["IPLOCUS_API_KEY"]},
    timeout=10,
)
response.raise_for_status()
location = response.json()
print(location["country"], location["city"], location["asnOrg"])

Questions or need an account? Contact the iplocus team.