Developer API
Documentation
The Nishan geolocation API. A single clean JSON endpoint over HTTPS — no SDK required. Powered by the DB-IP databases.
Endpoint
GET /api/lookup?ip=<address>
Resolves an IPv4 or IPv6 address to its location and network. If ipis omitted, the caller's own address is used.
Query parameters
| Name | Type | Description |
|---|---|---|
ip | string | Optional. IPv4 or IPv6 address to look up. Defaults to the requesting client's IP. |
Sample response
{
"ip": "1.2.3.4",
"version": "IPv4",
"country": "Iraq",
"country_code": "IQ",
"region": "Erbil",
"city": "Erbil",
"latitude": 36.1911,
"longitude": 44.0094,
"timezone": "Asia/Baghdad",
"asn": "AS21277",
"isp": "Newroz Telecom",
"proxy": false
}Rate limits
Each client IP may make 10 requests per 5 minutes. Every response carries the current limit state in headers:
X-RateLimit-Limit— the per-window cap (10).X-RateLimit-Remaining— requests left in the current window.X-RateLimit-Reset— Unix time (seconds) when the window resets.
Exceeding the limit returns 429 Too Many Requests with a Retry-After header (seconds until you can retry).
Status codes
| Code | Meaning |
|---|---|
200 | Success — geolocation record returned. |
400 | Bad Request — the provided ip is not a valid address. |
429 | Rate limit exceeded — retry after the given delay. |
Access
The API is free for developers and hobby projects. To request an access key, email [email protected].