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

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

Мы предлагаем Вам два варианта идентификации:

1. API_KEY из_профиля для обращения со стороны сервера из PHP. API_KEY может быть передан как GET так и POST запросом.
   Не размещайте ключ API_KEY в открытом доступе и в javascript. Он фактически заменяет ваши логин пароль и дает возможность использовать весь функционал Вашего аккаунта, включая платные функции.
2. HTTP_REFERER для обращения из javascript. Для этого необходимо добавить домен, с которого Вы будете обращаться в Мои сайты. При этом параметр API_KEY НЕ должен передаваться в запросе. Для исключения несанкционированного обращения и невозможности подмены HTTP_REFERER проверяется ip адрес домена, с которого идет обращение. При переносе сайта или при смене ip адреса не забудьте обновить данные в Мои сайты.

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

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_из_профиля

Пример для получения информации в html-формате с Вашим 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,
    '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/#История

Пример запроса на 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-запрос. В ответ вы получите следующую информацию:

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

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

С помощью данного запроса Вы можете определить существование и доступность абонента, отследить замену СИМ-карты, определить в домашней стране находится абонент или в роуменге.

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

Общие параметры для всех API сервисов

api_key - уникальный ключ, указан в вашем личном кабинете.

html или не задано - получить информацию в html формате, удобно для вывода в DIV-блок

json - получить информацию в json формате, удобно для заполнения INPUT-полей или преобразования в массив для дальнейшей обработки на Javascript или PHP.
Для Вашего удобства поддерживается формат JSONP. Вы можете добавить параметр &jsonp=ИМЯ_ФУНКЦИИ:
<script type="application/javascript"
src="http://htmlweb.ru/service/api.php?bic=043469751&json&jsonp=parseResponse"></script>
будет возвращен следующий код:

  parseResponse({"name":"ОАО КБ \"РЕГИОНАЛЬНЫЙ КРЕДИТ\"", "city":"КОСТРОМА", ...., "limit":50});

xml - получить информацию в xml формате, удобно для обращения из PHP

sql[=имя_таблицы] - получить информацию в sql формате. Удобно для вставки информации в базу MySql с помощью phpMyAdmin.

charset - по умолчанию все данные возвращаются в кодировке utf-8, Для получения любой другой кодировки передайте её в дополнительном, необязательном параметре charset: &charset=windows-1251 или любой из ISO-8859-1, ISO-8859-15, utf-8, cp866, cp1251, cp1252, and KOI8-R

fields - какие поля включать в ответ, например:
http://htmlweb.ru/geo/api.php?city=1&sql=pb_city&fields=id,name,english,area,rajon,country

limit - определяет количество оставшихся запросов до конца суток для бесплатных запросов или количество запросов до окончания тарифа при платных. Ограничения на бесплатные запросы и тарификация описана здесь.

Параметры можно передавать как GET, так и POST - запросом.

Запрос можно отправлять как по протоколу http:// так и по https://.

Если передан неверный запрос, возвращается HTTP-код ошибки: "400 Bad Request"

.