Вступление

Используйте наш API для быстрой и простой интеграции определения местоположения посетителя по IP адресу, в ваш скрипт или веб-сайт. Избавьте себя от необходимости настраивать локальные библиотеки GeoIP и забудьте о регулярном обновлении данных. Наша нейросеть анализирует десятки источников и обновляет базу данных практически в режиме реального времени.


Конечные точки

Массовая геолокация

Доступно в планах: Бизнес и Премиум

Массовый поиск IP-адресов позволяет сгруппировать до 100 IP-адресов в один запрос (вы можете смешивать IPv4 и IPv6-адреса). Это действительно может ускорить обработку массового поиска IP-адресов.

Мы поддерживаем 2 метода передачи значений в пакетный запрос: разделенные запятой и JSON массив.

Параметр, разделенный запятыми

Для массовой обработки IP-адресов с помощью этого метода просто добавьте несколько IP-адресов, разделенных запятыми, к следующему URL-адресу API (метод HTTP GET):

$ curl "http://ipwhois.pro/bulk/8.8.4.4,1.1.1.1,2c0f:fb50:4003::?key=YOUR_API_KEY"

Массив JSON как тело POST

Чтобы сделать пакетный запрос, вы также можете отправить массив JSON, содержащий все IP-адреса, для которых вы хотите получить данные. Вот пример, который использует cURL и конечную точку пакета для получения информации о 3 разных IP-адресах с помощью одного вызова API:

$ curl --data '["8.8.4.4", "1.1.1.1", "2c0f:fb50:4003::"]' \
     --header "Content-Type: application/json" \
     --request POST "http://ipwhois.pro/bulk?key=YOUR_API_KEY"

Обратите внимание: Пакетный запрос на поиск IP стоит столько кредитов, сколько указано IP-адресов. Например, приведенный выше пример стоит 3 кредита.

Наш API доступен через защищенное соединение HTTPS. Просто добавьте https:// к URL-адресам запросов.


Живой пример

Вы можете отредактировать этот запрос и поэкспериментировать с параметрами:

GET
Actual response
{
    "ip": "8.8.4.4",
    "success": true,
    "type": "IPv4",
    "continent": "North America",
    "continent_code": "NA",
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "region_code": "CA",
    "city": "Mountain View",
    "latitude": 37.3860517,
    "longitude": -122.0838511,
    "is_eu": false,
    "postal": "94039",
    "calling_code": "1",
    "capital": "Washington D.C.",
    "borders": "CA,MX",
    flag {
        "img": "https://cdn.ipwhois.io/flags/us.svg",
        "emoji": "🇺🇸",
        "emoji_unicode": "U+1F1FA U+1F1F8"
    },
    connection {
        "asn": 15169,
        "org": "Google LLC",
        "isp": "Google LLC",
        "domain": "google.com"
    },
    timezone {
        "id": "America/Los_Angeles",
        "abbr": "PDT",
        "is_dst": true,
        "offset": -25200,
        "utc": "-07:00",
        "current_time": "2022-04-22T14:31:48-07:00"
    },
    currency {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "plural": "US dollars",
        "exchange_rate": 1
    },
    security {
        "anonymous": false,
        "proxy": false,
        "vpn": false,
        "tor": false,
        "hosting": false
    }
}

Обратите внимание: для наглядности мы включили все доступные поля в приведенный выше ответ API. В зависимости от вашего плана подписки ответ API может отличаться.


Возвращаемые данные

В зависимости от вашего плана подписки и параметров, выбранных вами для запроса API, ответ будет содержать несколько разных полей. Ниже приведен список всех доступных полей ответа API:

название описание
ip Запрашиваемый IP адрес (например 8.8.4.4)
success В случае успешного выполнения запроса будет возвращено значение true, а в случае неудачи — значение false.
message Включается только в том случае, если success равен false
Может быть одним из следующих: Invalid IP address, You've hit the monthly limit, Reserved range
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 > is_dst Смещение часового пояса 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-адрес для хостинга.

Указать поля ответа

Вы можете ограничить результаты 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.

Например:
security=1

Статистика запросов в ответе API

Доступно в планах: Базовый, Бизнес и Премиум

Чтобы использовать эту возможность, добавьте параметр GET rate к URL-адресу запроса API и установите для него значение 1.
Вот пример (в формате JSON) информации в теле ответа API:

{
    [...],
    rate {
        "limit": "250000",
        "remaining": 50155
    }
}
название описание
rate > limit Общее количество запросов к API, которым ограничена ваша учетная запись за указанный период времени (месяц).
rate > remaining Количество запросов к API, оставшихся за указанный период времени (месяц).

Лимиты

Вы можете пользоваться нашим API бесплатно до 10,000 запросов в месяц (идентификация по IP-адресу и заголовку Referer).

Мы против коммерческого использования бесплатного плана. Воспользуйтесь нашим профессиональным сервисом, чтобы получить доступ к массовой геолокации IP-адресов, статистике использования, расширенным возможностям и коммерческой поддержке.


Примеры кода

Ниже приведены простые примеры кода на популярных языках:

  • PHP
  • Javascript
  • jQuery
  • Python
$ip = '8.8.4.4';
$ch = curl_init('http://ipwhois.pro/'.$ip);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
$ipwhois = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $ipwhois['country'] . ' ' . $ipwhois['flag']['emoji']; // Выведет: United States 🇺🇸
var ip = '8.8.4.4'; // Оставьте пустым для поиска текущего IP-адреса
var XMLHttp = new XMLHttpRequest();
XMLHttp.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var ipwhois = JSON.parse(this.responseText);
		console.log(ipwhois.country + ' ' + ipwhois.flag.emoji); // Выведет: United States 🇺🇸
	}
};
XMLHttp.open('GET', 'https://ipwhois.pro/' + ip, true);
XMLHttp.send();
var ip = '8.8.4.4'; // Оставьте пустым для поиска текущего IP-адреса
$.ajax({
	method: 'GET',
	contentType: 'application/json',
	url: 'https://ipwhois.pro/' + ip,
	dataType: 'json',
	success: function(ipwhois) {
		console.log(ipwhois.country + ' ' + ipwhois.flag.emoji); // Выведет: United States 🇺🇸
	}
});
import re
import json
from urllib2 import urlopen
ip = '8.8.4.4';
response = urlopen('http://ipwhois.pro/'+ip)
ipwhois = json.load(response)

# Выведет: United States 🇺🇸
print '{0} {1}'.format(ipwhois['country'],ipwhois['flag']['emoji'])
  • PHP
  • Javascript
// Список IP-адресов для запроса, до 100
$ips = array('8.8.4.4','1.1.1.1','2c0f:fb50:4003::');
$endpoint = 'http://ipwhois.pro/bulk?key=YOUR_API_KEY';
$options = array(
	'http' => array(
		'method' => 'POST',
		'header' => 'Content-Type: application/json',
		'content' => json_encode($ips)
	)
);
$response = json_decode(file_get_contents($endpoint, false, stream_context_create($options)), true);
foreach($response as $ipwhois)
{
	echo $ipwhois['ip'] . ' - ' . $ipwhois['country'] . ' ' . $ipwhois['flag']['emoji']."\n";
	// Выведет:
	// 8.8.4.4 - United States 🇺🇸
	// 1.1.1.1 - Australia 🇦🇺
	// 2c0f:fb50:4003:: - Kenya 🇰🇪
}
// Список IP-адресов для запроса, до 100
var IPs = ['8.8.4.4','1.1.1.1','2c0f:fb50:4003::'];
var endpoint = 'https://ipwhois.pro/bulk?key=YOUR_API_KEY';
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		response.forEach(function(ipwhois) {
			console.log(ipwhois.ip + ' - ' + ipwhois.country + ' ' + ipwhois.flag.emoji);
			// Выведет:
			// 8.8.4.4 - United States 🇺🇸
			// 1.1.1.1 - Australia 🇦🇺
			// 2c0f:fb50:4003:: - Kenya 🇰🇪
		});
	}
};
var data = JSON.stringify(IPs);
xhr.open('POST', endpoint, true);
xhr.send(data);