IP geolocation API

Quick start

1. Create an independent ip.uk.app account and verify your email.
2. Open Keys in your dashboard and create a key. Copy it immediately; it is shown only once.
3. Send the key in the Authorization header from your server.

curl 'https://ip.uk.app/api/v1/lookup?ip=1.1.1.1' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Never include your API key in a URL, public frontend bundle, screenshot or shared log. Store it in an environment variable on your server.

Endpoints

Add the optional lang parameter for names: en, uk, es, pt, de or fr. Missing translations fall back to English.

curl 'https://ip.uk.app/api/v1/bulk?lang=uk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"ips":["1.1.1.1","2001:4860:4860::8888"]}'

Response format

The data field is an object for lookup and me, and an array for bulk. Unavailable fields are null. Example values below illustrate the schema and are not a location guarantee.

{
  "data": {
    "ip": "1.1.1.1",
    "version": 4,
    "country": {"code": "AU", "name": "Australia"},
    "region": "New South Wales",
    "city": "Sydney",
    "location": {"latitude": -33.8688, "longitude": 151.209, "accuracy": "approximate"},
    "asn": {"number": 13335, "organization": "Cloudflare, Inc.", "prefix_length": 24},
    "source": {"name": "DB-IP Lite", "url": "https://db-ip.com/", "license": "CC BY 4.0", "updated": "2026-10"}
  }
}

Free quota and limits

• 10,000 successful IP lookups per account per calendar month, resetting at 00:00 UTC on the first day.
• 60 IP lookups per minute, shared across all of your keys.
• Up to five active keys, with an expiry of 30, 90 or 365 days.
• Each successful address costs one credit, including repeated addresses in a batch. A batch of 50 costs 50 credits.
• Invalid input and failed lookups do not consume monthly credits. Temporary failures may still count toward the minute limit.
• The whole batch is validated and checked against the quota before processing. A batch is not partially charged.
• Additional network limits protect service availability.

Responses include X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. Reset is a Unix timestamp. X-Request-ID identifies an authenticated request. A 429 response includes Retry-After in seconds.

Paid monthly plans are available in your dashboard. Paid quotas follow the subscription period. No automatic overage charges.

Error handling

{"error":{"code":"invalid_ip","message":"Provide a public IPv4 or IPv6 address."}}

JavaScript · server-side

const response = await fetch(
  'https://ip.uk.app/api/v1/lookup?ip=1.1.1.1',
  { headers: { Authorization: `Bearer ${process.env.IP_API_KEY}` } }
);
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.data);

Python

import json, os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request('https://ip.uk.app/api/v1/lookup?ip=1.1.1.1',
    headers={'Authorization': 'Bearer ' + os.environ['IP_API_KEY']})
try:
    with urlopen(request, timeout=15) as response:
        print(json.load(response)['data'])
except HTTPError as error:
    print(error.code, json.load(error))

PHP

$ch = curl_init('https://ip.uk.app/api/v1/lookup?ip=1.1.1.1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('IP_API_KEY')],
]);
$body = curl_exec($ch);
if ($body === false) { throw new RuntimeException(curl_error($ch)); }
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200) { throw new RuntimeException($result['error']['message']); }

Data quality and attribution

Geolocation is approximate. An IP may identify a network gateway or data centre, especially for mobile networks, anycast, VPNs and proxies. Coordinates are not a person's precise location. ASN organization identifies the network operator and is not a verified residential ISP classification.

Data comes from the monthly DB-IP Lite database under CC BY 4.0. Preserve appropriate attribution in applications using this data. There is no VPN, proxy or fraud classification in v1.

Privacy and key security

Full API keys are shown once and stored only as keyed hashes. Request statistics retain the endpoint, status, duration, credit count and masked key identifier for 30 days. Lookup targets and full keys are not stored in this request history. Monthly aggregate counters are retained for 12 months. Separate infrastructure logs follow our Privacy Policy.

Revoke exposed keys immediately in your dashboard. Blocking or deleting an account disables its keys. Your account is independent from other uk.app projects.

Privacy Policy · Terms · support@uk.app