API получения местонахождения по номеру телефона:
страны и города

Форма получения информации по номеру телефона здесь

Большинство API функций сервиса htmlweb.ru совершенно бесплатны. Идентификация нужна для исключения злоупотреблений и позволяет разделить количество запросов от разных пользователей. Ограничения на бесплатные запросы и тарификация описана здесь.

Для идентификации используется API_KEY из_профиля. API_KEY может быть передан как GET так и POST запросом.
Не размещайте ключ API_KEY в открытом доступе и в javascript. Он фактически заменяет ваши логин пароль и дает возможность использовать весь функционал нашего сайта от вашего аккаунта, включая платные функции.

Ключи выбора формата:

  1. html - HTML-формат.
  2. json - JSON-формат
  3. xml - XML-формат

Для указания кодирования ответа в нужном вам формате добавьте в запрос параметр html или json или xml, например:

http://htmlweb.ru/geo/api.php?telcod=НОМЕР_ТЕЛЕФОНА&html&charset=utf-8&api_key=xxxx

При возврате в формате JSON возврашается заголовок header('Access-Control-Allow-Origin: *') - разрешающий кроссдоменные запросы.

Ключ выбора кодировки charset=:

  1. windows-1251 по умолчанию всё отдается в кодировке utf-8
  2. utf-8 unicode - кодировка UTF-8. Пример: charset=utf-8
  3. а также другие: koi-8, ISO-8859-1, ISO-8859-15, cp866, cp1252, KOI8-R

fields - какие поля включать в ответ, например:
http://htmlweb.ru/geo/api.php?telcod=НОМЕР_ТЕЛЕФОНА&sql=pb_city&fields=id,name,english,area,rajon,country

Если Вам нужен другой формат или другая кодировка, а также обо всех найденных проблемах и пожеланиях сообщайте нам.



Структура API запроса для получения информации по номеру телефона:

http://htmlweb.ru/geo/api.php?html&telcod=НОМЕР_ТЕЛЕФОНА&api_key=API_KEY_из_профиля

Структура API запроса для получения информации по номеру телефона в json-формате:

http://htmlweb.ru/geo/api.php?json&telcod=НОМЕР_ТЕЛЕФОНА&api_key=API_KEY_из_профиля

Дополнительно возвращается несколько признаков:

  • mobile - Мобильный телефон
  • sip - IP телефония
  • free - Бесплатный, оплачивает владелец номера
  • sputnik - Спутниковый телефон, высокая стоимость
  • payment - Высокая дополнительная стоимость

Пример для получения информации в html-формате с Вашим API_KEY:

http://htmlweb.ru/geo/api.php?html&telcod=78632555555&api_key=НЕДОСТУПНО_БЕЗ_РЕГИСТРАЦИИ

Ответ для html:

Город: Ростов-на-Дону (rostov-na-donu) Wiki
Регион: Ростовская область Wiki, Областной центр: Ростов-на-Дону
Округ: Южный федеральный округ
Страна: Россия RU Wiki(Российская Федерация, Russia, iso:643) , Столица Москва 1
Часть света: Европа
Код страны(2): RU
Код страны(3): RUS
Широта: 47.233189
Долгота: 39.715000
Телефонный код страны: +7
Телефонный код города: 863
Автомобильный код региона: 61,161
Временная зона(Time Zone,UTC,GMT): +4
Осталось 50 запросов до 21:05:58 09.10.2013

Краткий (short) html-ответ:

Город: Ростов-на-Дону
Регион: Ростовская область
Округ: Южный федеральный округ
Страна: Россия

Краткий (short) html-ответ для мобильного телефона:

Мобильный оператор: Мобильные ТелеСистемы
Диапазон кодов: 918 500 0000 — 918 599 9999
Регион: Ростовская область
Страна: Россия

Ответ для json:

{   'ip':'93.178.64.171',
    'country_id':'RU',
    'country':'Россия',
    'region_id':49,
    'region':'Ростовская область',
    'region_iso':'',
    'okrug':'Южный федеральный округ',
    'rajon':'',
    'rajon_id':0,
    'city_id':1711,
    'city':'Ростов-на-Дону',
    'city_english':'rostov-na-donu',
    'city_telcod':863,
    'latitude':'47.233189',
    'longitude':'39.715000',
    'autocod':'61,161',
    'capital2_id':1711,
    'capital2':'Ростов-на-Дону',
    'fullname':'Российская Федерация',
    'english':'Russia','country_code3':'RUS',
    'iso':643,'country_telcod':7,
    'location':'Европа','capital_id':1,
    'capital':'Москва','time_zone':4,
    'charset':'','api':'\/geo\/api.php',
    'upd':'1373297221',
    'oper':'',
    'oper_id':0,
    'mobile':false,
    'limit':50
}

Краткий (short) json-ответ:

{   'country_id':'RU',
    'country':'Россия',
    'region_id':49,
    'region':'Ростовская область',
    'okrug':'Южный федеральный округ',
    'rajon_id':0,
    'rajon':'',
    'city_id':1711,
    'city':'Ростов-на-Дону',
    'oper':'',
    'oper_id':0,
    'limit':50
}

Если Вы хотите сразу сделать платный запрос к оператору для получения информации об абоненте, добавьте в запрос параметр hlr. Например:

https://htmlweb.ru/geo/api.php?html&telcod=НОМЕР_ТЕЛЕФОНА&hlr&api_key=API_KEY_из_профиля
Вы получите информацию из базы о привязке абонента и будет отправлен HLR-запрос оператору. Для отправки только HLR-запроса используйте следующий вызов:
https://htmlweb.ru/sendsms/api.php?hlr=НОМЕР_ТЕЛЕФОНА&json&api_key=API_KEY_из_профиля

Ответ от оператора получите через callback, указанный в вашем профиле или в https://htmlweb.ru/sendsms/#История

Обратите внимание, данный API возвращает базовое распределение номеров. Если Вам нужно получить информацию о текущем операторе с учетом MNP переноса, используйте другое API.

Пример запроса на PHP:

$s=file_get_contents('http://htmlweb.ru/geo/api.php?json&telcod=79774255596&charset=utf-8');
var_export(json_decode($s, true));

Ответ:

array('country' => array('name' => 'Россия', 'fullname' => 'Российская Федерация',
                        'english' => 'Russia', 'id' => 'RU', 'country_code3' => 'RUS',
                        'iso' => 643, 'telcod' => 7, 'location' => 'Европа', 'capital' => 1,),
    'region' => array('id' => 1, 'name' => 'Московская область',
                        'okrug' => 'Центральный федеральный округ',
                        'autocod' => '50,90,150,190,177,199', 'capital' => 1,
                        'english' => 'Moscow oblast', 'iso' => 'MOS', 'country' => 'RU',),
    'okrug' => 'Центральный федеральный округ', 'autocod' => '50,90,150,190,177,199',
                        'fullname' => 'Российская Федерация', 'english' => 'Russia',
                        'iso' => 643, 'country_telcod' => 7, 'location' => 'Европа',
    'capital' => array('id' => 1, 'name' => 'Москва', 'area' => 1, 'telcod' => '495,499',
                        'latitude' => 55.755800000000001, 'longitude' => 37.617600000000003,
                        'time_zone' => 3, 'english' => 'Moscow', 'rajon' => 3597,
                        'country' => 'RU', 'sound' => 'M210', 'level' => 1, 'iso' => 'MOW',
                        'vid' => 1,),
    'time_zone' => 3,
    'ImgFlag' => '<img src=\'http://htmlweb.ru/geo/flags/ru.png\'>',
    'limit' => 47,
    0 => array('id' => 1, 'name' => 'Москва', 'area' => 1, 'telcod' => '495,499',
                'latitude' => 55.755800000000001, 'longitude' => 37.617600000000003,
                'time_zone' => 3, 'english' => 'Moscow', 'rajon' => 3597, 'country' => 'RU',
                'sound' => 'M210', 'level' => 1, 'iso' => 'MOW', 'vid' => 1,
                'oper_id' => 3994, 'oper' => 'ООО "Т2 Мобайл"',
                'def' => '79772500000-79779999999',),)

HLR-запрос информации об абоненте

Вы можете отправить специальный запрос оператору для получения информации об абоненте, так называемый HLR-запрос. HLR (Home Location Register) — это база данных, которая содержит подробную информацию о каждом абоненте мобильных сетей GSM-операторов. Стоимость одного HLR-запроса составляет 1.6руб. В ответ вы получите следующую информацию:

В ответ на запрос информации от абоненте, оператор возвращает следующую информацию:

  • imsi - Уникальный код IMSI SIM-карты абонента. В случае смены сим-карты этот номер меняется. Некоторые операторы, например Yota, возвращают некорректный номер.
  • msc - Номер сервис-центра оператора, в сети которого находится абонент.
  • mcc - Числовой код страны абонента.
  • mnc - Числовой код оператора абонента.
  • cn - Название страны регистрации абонента.
  • net - Название оператора регистрации абонента.
  • rcn - Название роуминговой страны абонента при нахождении в чужой сети.
  • rnet - Название роумингового оператора абонента при нахождении в чужой сети.

С помощью данного запроса Вы можете определить существование и доступность абонента, отследить замену СИМ-карты, определить в домашней стране находится абонент или в роуминге. Банки по номеру симки определяют, что человек не менял сим-карту и ему можно отправлять кодовые СМС. Этот запрос чаще всего используется для чистки базы абонентов, чтобы удалить уже несуществующие из списка рассылок. Чтобы определить в сети или нет (ON Line) сейчас абонент, существует PING-запрос. Но его стоимость равна стоимости СМС по прямым каналам.

Российские операторы Мегафон, Yota и Тиньков-мобайл блокируют HLR-запросы информации о своих абонентах.

API запрос для получения HLR-информации:
https://htmlweb.ru/json/sms/hlr/79185558077?api_key=API_KEY_из_профиля
Ответ:

{"status":200,
 "message":"Статус доставки #840366 доставлено
    код IMSI SIM-карты: 250010076790077
    номер сервис-центра: 79184790007
    код страны регистрации: 250
    код оператора: 01
    название страны регистрации: Russia
    название оператора: Mobile TeleSystems MTS
    название роуминговой страны:
    название роумингового оператора: ",
 "id":840366,
 "hlr":{"imsi":"250010076790077","msc":79184790007,"mcc":250,"mnc":"01","cn":"Russia","net":"Mobile TeleSystems MTS"},
 "limit":598590,"balans":24780.46
}

Ответ на этот запрос поступает через некоторое время. Вы можете получить его с помощью Callback вызова адреса, указанного у вас в профиле или вызвать этот запрос ещё раз через некоторое время.

Скачать базу телефонных номеров распределенных операторам по регионам.

Общие параметры для всех API сервисов
Другие сервисы, доступные по API
Стоимость API запроса и тарифы
.