Быстрая и точная IP-геолокация — интегрируйте API за считанные минуты с ответами в JSON, XML или CSV.
Вступление
Этот API создан для разработчиков, которым необходимы высокая производительность, низкая задержка и надёжность. Наша платформа работает на собственной Anycast-сети с глобально распределённой, отказоустойчивой и самомасштабируемой инфраструктурой, обеспечивающей низкую задержку по всему миру. Ядро построено на высокооптимизированном стеке OpenResty и Rust, разработанном для максимальной пропускной способности и минимальных накладных расходов. Базы данных IP-геолокации хранятся в компактном двоичном формате и загружаются непосредственно в высокоскоростную память, что позволяет выполнять поиск за постоянное время без обращения к диску. Такая архитектура, работающая в оперативной памяти, позволяет API обрабатывать более 1 миллиарда запросов в день с неизменно стабильной производительностью. Наша база данных обновляется несколько раз в день и дополнительно совершенствуется с использованием AI-алгоритмов агрегации и валидации данных, повышая точность за счёт непрерывного анализа сигналов из множества надёжных источников. Благодаря чистому и удобному для разработчиков интерфейсу, гибким возможностям интеграции и предсказуемой производительности при высокой нагрузке, API легко интегрируется в современные production-среды.
Вы можете вызвать API, отправив GET запрос http://ipwhois.pro/[IP address]?key=YOUR_API_KEY
[IP address] может быть IPv4 или IPv6 адресом, оставьте параметр пустым чтобы использовать текущий IP-адрес.
# Получить подробности для 8.8.4.4
$ curl"http://ipwhois.pro/8.8.4.4?key=YOUR_API_KEY"# Get details for your own IP address
$ curl"http://ipwhois.pro/?key=YOUR_API_KEY"
Наш API доступен через защищённое соединение HTTPS. Просто добавьте https:// к URL-адресам запросов.
Обратите внимание: для наглядности мы включили все доступные поля в приведённый выше ответ API. В зависимости от вашего плана подписки ответ API может отличаться.
Возвращаемые данные
В зависимости от вашего плана подписки и параметров, выбранных вами для запроса API, ответ будет содержать несколько разных полей. Ниже приведён список всех доступных полей ответа API:
название
описание
ip
Запрашиваемый IP адрес (например 8.8.4.4)
success
В случае успешного выполнения запроса будет возвращено значение true, а в случае неудачи — значение false.
message
Включается только в том случае, если success равен false Может быть одним из следующих: Смотри коды ошибок
type
Тип IP адреса (IPv4 или IPv6)
continent
Название континента (например North America)
continent_code
Двухбуквенный (ISO 3166-1) код континента (например NA)
country
Название страны (например United States)
country_code
Двухбуквенный (ISO 3166-1) код страны (например US)
region
Название региона/штата (например California)
region_code
Код штата/региона (ISO 3166-2), если он доступен (например CA)
city
Название города (например Mountain View)
latitude
Приблизительная (WGS84) широта местоположения, связанного с IP (например 37.3860517)
longitude
Приблизительная (WGS84) долгота местоположения, связанного с IP (например -122.0838511)
is_eu
Возвращает true или false в зависимости от того, находится ли страна, связанная с IP, в Европейском союзе.
postal
Почтовый индекс, связанный с местоположением.
calling_code
Телефонный код страны (например 1)
capital
Столица страны (например Washington)
borders
Двухбуквенный (ISO 3166-1) код стран, граничащих со страной, связанной с этим IP (например CA,MX)
flag > img
Возвращает URL-адрес, ведущий к SVG изображению флага страны.
flag > emoji
Эмодзи-версия флага страны (например 🇺🇸)
flag > emoji_unicode
Юникод значение значка эмодзи для флага.
connection > asn
Номер автономной системы (AS) (например 15169)
connection > org
Название организации, владеющей AS для анализируемого IP-адреса (например Google LLC)
connection > isp
Имя провайдера, связанного с IP (например Google LLC)
connection > domain
Доменное имя, связанное с организацией, которой принадлежит IP-адрес (например google.com)
timezone > id
Идентификатор часового пояса, связанного с местоположением (например America/Los_Angeles)
timezone > abbr
Аббревиатура часового пояса (например PDT)
timezone > is_dst
true или false в зависимости от того, учитывался ли переход на летнее время.
timezone > offset
Смещение от UTC (в секундах) для данного местоположения (например -25200)
timezone > utc
Смещение часового пояса UTC (например -07:00)
timezone > current_time
Точная текущая дата и время (в формате ISO 8601), связанные с местоположением (например 2022-04-22T14:31:48-07:00)
currency > name
Название валюты (например US Dollar)
currency > code
Трехбуквенный (ISO 4217) код валюты (например USD)
currency > symbol
Родной (местный) символ данной валюты (например $)
currency > plural
Множественная версия названия валюты (например US dollars)
currency > exchange_rate
Текущий курс по отношению к доллару США.
security > anonymous
Логическое значение со значением true, если proxy, vpn или tor равны true.
security > proxy
true или false в зависимости от того, является ли IP-адрес известным прокси-сервером или любым другим типом.
security > vpn
Возвращает true, если искомый IP-адрес используется VPN, и false в противном случае.
security > tor
true или false в зависимости от того, является ли IP-адрес известным выходным узлом или принадлежит сети Tor.
security > hosting
true или false в зависимости от того, используется ли IP-адрес для хостинга.
rate > limit
Общее количество запросов к API, которым ограничена ваша учетная запись за указанный период времени (месяц).
rate > remaining
Количество запросов к API, оставшихся за указанный период времени (месяц).
Указать формат вывода
Используя параметр GET output, вы можете переключать формат результатов API между JSON (по умолчанию), XML и CSV. Если вы используете JSON, этот параметр можно не указывать.
Например:
output=xml
output=csv
output=json
Указать поля ответа
Вы можете ограничить результаты API определёнными полями данных, если вам не нужно отслеживать все данные. В этом случае вам нужно добавить параметр GET fields к URL-адресу API-запроса и указать определённое поле или список полей через запятую.
Например:
fields=country,city,flag.emoji
fields=city,timezone
fields=ip,timezone.current_time
JSONP Callback
API поддерживает функцию обратного вызова (JSONP). Просто добавьте параметр GET callback к URL-адресу запроса API и задайте для него имя вашей функции.
Например:
callback=getIPinfo
Локализация
Локализацию city, region, country, capital и continent можно запросить, установив для GET параметра lang одно из следующих значений:
язык
описание
демо
en
English (по умолчанию)
ru
Русский (Russian)
de
Deutsch (German)
es
Español (Spanish)
pt-BR
Português - Brasil (Portuguese)
fr
Français (French)
zh-CN
中国 (Chinese)
ja
日本語 (Japanese)
Включить обнаружение угроз
Доступно в планах: Бизнес и Безлимитный
Включение полей данных безопасности (proxy, vpn, tor, hosting) для обнаружения угроз. Это позволит защитить ваш сайт или приложение от злоупотреблений в виде обхода бана, сокрытия реального IP-адреса, парсинга сайта и т.д. Для того, чтобы использовать эту возможность, добавьте GET-параметр security к URL-адресу запроса API и установите для него значение 1.
Чтобы использовать эту возможность, добавьте GET-параметр rate к URL-адресу запроса API и установите для него значение 1. Ниже приведён пример (в формате JSON) этой информации в теле ответа API:
{"success":false,"message":"Bulk lookup accepts up to 100 IP addresses per request"}
401
Неавторизован
{"success":false,"message":"Invalid API key or subscription expired"}
403
Доступ запрещён
{"success":false,"message":"The current subscription plan does not support this API endpoint"}
403
Источник не разрешён
{"success":false,"message":"API key not allowed access from this source. Please check your API key security rules: https://ipwhois.io/dashboard/settings"}
404
URL не найден
{"success":false,"message":"404 not found"}
405
Метод HTTP не разрешен
{"success":false,"message":"HTTP method is not allowed"}
414
Слишком длинный URI запроса
{"success":false,"message":"URI Too Long"}
429
Превышен лимит
{"success":false,"message":"You've hit the monthly limit"}
В общем случае статус-код 2xx HTTP означает, что запрос был успешно обработан.
Однако в некоторых случаях API может вернуть ответ 200 OK, указывая при этом на ошибку на уровне приложения в теле ответа. В таких случаях запрос был технически корректным, но операция не могла быть выполнена.
Такие ответы содержат JSON-объект с "success":false и поясняющим полем "message", например:
HTTP статус-код
Причина
Ответ
200
Некорректный IP-адрес
{"success":false,"message":"Invalid IP address"}
200
Зарезервированный IP-адрес
{"success":false,"message":"Reserved range"}
Примеры кода
Ниже приведены простые примеры кода на популярных языках:
package main
import (
"encoding/json""fmt""net/http"
)
funcmain() {
url := "https://ipwhois.pro/8.8.8.8?key=YOUR_API_KEY"resp, _ := http.Get(url)
deferresp.Body.Close()
data := map[string]any{}
json.NewDecoder(resp.Body).Decode(&data)
fmt.Println(data["country"], data["flag"].(map[string]any)["emoji"]) // Output: United States 🇺🇸
}
import requests
ip = '8.8.8.8'url = 'https://ipwhois.pro/' + ip + '?key=YOUR_API_KEY'response = requests.get(url)
data = response.json()
print(data['country'], data['flag']['emoji']) # Output: United States 🇺🇸
import org.json.JSONObject;
import java.net.URI;
import java.net.http.*;
public class Main {
public static void main(String[] args) throws Exception {
var client = HttpClient.newHttpClient();
var url = "https://ipwhois.pro/8.8.8.8?key=YOUR_API_KEY";
var request = HttpRequest.newBuilder()
.uri(URI.create(url))
.build();
var body = client.send(request, HttpResponse.BodyHandlers.ofString()).body();
var data = new JSONObject(body);
System.out.println(data.getString("country") + " " + data.getJSONObject("flag").getString("emoji")); // Output: United States 🇺🇸
}
}
require'net/http'require'json'require'uri'ip = '8.8.8.8'url = 'https://ipwhois.pro/' + ip + '?key=YOUR_API_KEY'response = Net::HTTP.get(URI(url))
data = JSON.parse(response)
puts data['country'] + ' ' + data['flag']['emoji'] # Output: United States 🇺🇸
import Foundation
letip = "8.8.8.8"leturl = "https://ipwhois.pro/\(ip)?key=YOUR_API_KEY"letsem = DispatchSemaphore(value: 0)
URLSession.shared.dataTask(with: URL(string: url)!) { data, _, _ in
guard let data = data else { sem.signal(); return }
let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
let country = json?["country"] as? String ?? ""
let flag = (json?["flag"] as? [String: Any])?["emoji"] as? String ?? ""
print(country, flag) // Output: United States 🇺🇸
sem.signal()
}.resume()
sem.wait()
use reqwest;
use serde_json::Value;
#[tokio::main]async fnmain() -> Result<(), Box<dyn std::error::Error>> {
letip = "8.8.8.8";
leturl = format!("https://ipwhois.pro/{ip}?key=YOUR_API_KEY");
letdata: Value = reqwest::get(url).await?.json().await?;
letcountry = data["country"].as_str().unwrap_or("");
letflag = data["flag"]["emoji"].as_str().unwrap_or("");
println!("{country} {flag}"); // Output: United States 🇺🇸
Ok(())
}