Документация по API

Вступление

Этот 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-адресам запросов.

Живой пример

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

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

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

Вы можете ограничить результаты API определенными полями данных, если вам не нужно отслеживать все данные. В этом случае вам нужно добавить параметр GET fields к URL-адресу API-запроса и указать определенное поле или список полей через запятую.

JSONP Callback

API поддерживает функцию обратного вызова (JSONP). Просто добавьте параметр GET callback к URL-адресу запроса API и задайте для него имя вашей функции.

Локализация

Локализацию city, region, country, capital и continent можно запросить, установив для GET параметра lang одно из следующих значений:

Включить обнаружение угроз

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

Включение полей данных безопасности (proxy, vpn, tor, hosting) для обнаружения угроз. Это позволит защитить ваш сайт или приложение от злоупотреблений в виде обхода бана, сокрытия реального IP-адреса, парсинга сайта и т.д. Для того, чтобы использовать эту возможность, добавьте GET-параметр security к URL-адресу запроса API и установите для него значение 1.

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

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

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

{
    [...],
    rate {
        "limit": "250000",
        "remaining": 50155
    }
}

Лимиты

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

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

Примеры кода

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

$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'])

// Список 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);