API геолокації IP

Швидкий старт

1. Створіть окремий акаунт ip.uk.app і підтвердьте свою електронну пошту.
2. У панелі керування відкрийте розділ «Ключі» та створіть ключ. Одразу скопіюйте його: повний ключ показується лише один раз.
3. Надсилайте ключ зі свого сервера в заголовку Authorization.

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

Ніколи не додавайте API-ключ до URL, публічного коду клієнтської частини, знімків екрана чи спільних журналів. Зберігайте його у змінній середовища на своєму сервері.

Методи API

Щоб вибрати мову назв, додайте необов’язковий параметр lang: en, uk, es, pt, de або fr. Якщо перекладу назви немає, вона повертається англійською.

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"]}'

Формат відповіді

Поле data містить об’єкт для методів lookup і me та масив для bulk. Недоступні значення повертаються як null. Наведені нижче значення пояснюють структуру відповіді й не гарантують фактичного розташування.

{
  "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"}
  }
}

Безкоштовна квота та ліміти

• 10 000 успішних перевірок IP на акаунт за календарний місяць. Квота оновлюється о 00:00 UTC першого числа.
• 60 перевірок IP на хвилину спільно для всіх ваших ключів.
• До п’яти активних ключів зі строком дії 30, 90 або 365 днів.
• Кожна успішно перевірена адреса витрачає один кредит, зокрема повтори адрес у пакеті. Пакет із 50 адрес витрачає 50 кредитів.
• Некоректні вхідні дані та невдалі перевірки не витрачають місячні кредити. Тимчасові збої все одно можуть враховуватись у хвилинному ліміті.
• Перед обробкою весь пакет проходить перевірку даних і доступної квоти. Часткове списання кредитів за пакет не виконується.
• Додаткові мережеві обмеження захищають доступність сервісу.

Відповіді містять заголовки X-Quota-Limit, X-Quota-Remaining та X-Quota-Reset. Час оновлення квоти — часова мітка Unix. X-Request-ID ідентифікує автентифікований запит. Відповідь 429 містить Retry-After із часом очікування в секундах.

Платні місячні тарифи доступні в кабінеті. Платні квоти діють протягом періоду підписки. Автоматичної оплати перевитрати немає.

Обробка помилок

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

JavaScript · на сервері

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']); }

Якість даних і зазначення джерела

Геолокація є приблизною. IP-адреса може вказувати на мережевий шлюз або датацентр, особливо в мобільних мережах, anycast, VPN і проксі. Координати не визначають точного місця перебування людини. Організація ASN позначає оператора мережі й не є підтвердженням того, що це домашній інтернет-провайдер.

Дані надходять зі щомісячної бази DB-IP Lite за ліцензією CC BY 4.0. У застосунках, що використовують ці дані, зберігайте належне зазначення джерела. Версія v1 не визначає VPN, проксі чи шахрайство.

Приватність і безпека ключів

Повні API-ключі показуються лише один раз і зберігаються тільки як хеші із серверним секретом. Статистика запитів протягом 30 днів містить шлях API, статус, тривалість, кількість кредитів і маскований ідентифікатор ключа. Перевірені IP-адреси й повні ключі до цієї історії не записуються. Місячні агреговані лічильники зберігаються 12 місяців. Окремі інфраструктурні журнали обробляються згідно з нашою політикою приватності.

Негайно відкликайте скомпрометовані ключі в панелі керування. Блокування або видалення акаунта вимикає його ключі. Ваш акаунт незалежний від інших проєктів uk.app.

Політика приватності · Умови · support@uk.app