Наш чат в Telegram для обмена идеями, проектами, мыслями, людьми в сфере ИТ г.Ростова-на-Дону: @it_rostov

API данных о городах, областях, регионах, странах

Набор API для получения информации обо всех городах, областях, регионах, странах.

Получение частей света

Структура API запроса для получения всех частей света:

http://htmlweb.ru/geo/api.php?locations&json&api_key=API_KEY_из_профиля
Web форма

Получение всех стран или список стран указанной части света

Структура API запроса для получения всех областей(регионов, штатов) указанной страны:

http://htmlweb.ru/geo/api.php?location=ЧАСТЬ_СВЕТА&json&api_key=API_KEY_из_профиля

Для получения всех стран Европы:
http://htmlweb.ru/geo/api.php?location=Европа&json&api_key=API_KEY_из_профиля

Для получения всех стран передайте пустое location.

Для получения только кодов и названий, передайте параметр short.

Ответ:

{"0":{"name":"Австрия","fullname":"Австрийская Республика","english":"Austria","id":"AT","country_code3":"AUT","iso":"040","telcod":43,"location":"Европа","capital":2440,"mcc":232,"lang":"немецкий","langcod":"de"},
"1":{"name":"Албания","fullname":"Республика Албания","english":"Albania","id":"AL","country_code3":"ALB","iso":"008","telcod":355,"location":"Европа","capital":2593,"mcc":276,"lang":"албанский","langcod":"sq"},
...

Получение всех областей(регионов, штатов) указанной страны

Структура API запроса для получения всех областей(регионов, штатов) указанной страны:

http://htmlweb.ru/geo/api.php?country=КОД_СТРАНЫ&json&api_key=API_KEY_из_профиля

Например, для получения всех областей и округов России:

http://htmlweb.ru/geo/api.php?country=ru&json&api_key=API_KEY_из_профиля

Для получения одной записи "Республика Крым" в формате sql: http://htmlweb.ru/geo/api.php?country=ru&id=115&sql&api_key=API_KEY_из_профиля

Также вы можете задать альтернативные форматы xml, html или sql:

http://htmlweb.ru/geo/api.php?country=ru&xml&api_key=API_KEY_из_профиля
http://htmlweb.ru/geo/api.php?country=ru&html&api_key=API_KEY_из_профиля
http://htmlweb.ru/geo/api.php?country=ru&sql&api_key=API_KEY_из_профиля

Кодовая страница по умолчанию для sql формата utf-8. Для выгрузки в формате windows-1251 добавьте параметр &charset=windows-1251

Если формат не указан, формируется список option для select-запроса

* Ограничение


Получение всех районов указанной области(региона, штата)

Структура API запроса для получения всех областей(регионов, штатов) указанной страны:

http://htmlweb.ru/geo/api.php?area_rajon=КОД_ОБЛАСТИ&json&api_key=API_KEY_из_профиля

КОД_ОБЛАСТИ - поле id в ответе на запрос "Список всех областей"

Например, для получения всех областей и округов Амурской области России:

http://htmlweb.ru/geo/api.php?area_rajon=5&json&api_key=API_KEY_из_профиля

Получение всех городов указанного района внутри области

Структура API запроса для получения всех городов указанного района внутри области:

http://htmlweb.ru/geo/api.php?rajon_city=КОД_РАЙОНА&json&api_key=API_KEY_из_профиля

КОД_РАЙОНА - поле id в ответе на запрос "Список всех районов области"

* Ограничение


Получение всех городов указанной области(региона, штата) без деления на районы

Структура API запроса для получения всех городов :

http://htmlweb.ru/geo/api.php?area=КОД_ОБЛАСТИ&json&api_key=API_KEY_из_профиля

КОД_ОБЛАСТИ - поле id в ответе на запрос "Список всех областей"

Например, для получения всех городов Амурской области России:

http://htmlweb.ru/geo/api.php?area=5&json&api_key=API_KEY_из_профиля

Для включения в выборку только крупных городов добавьте параметр level=2. Если хотите получить только крупнейшие города, добавьте параметр level=1.

Для получения ответа в формате MySql используйте параметр sql[=имя_таблицы]:

Например, для получения всех городов Амурской области России:

http://htmlweb.ru/geo/api.php?area=5&sql&api_key=API_KEY_из_профиля
INSERT IGNORE INTO `region` ( `id`, `name`, `area`, `telcod`, `latitude`, `longitude`, `time_zone`, `english`, `rajon`, `country`, `sound`) VALUES ('288', 'Айгунь', '5', '', '49.978001', '127.489998', null, 'aygun\'', '0', 'RU', 'A250'); и т.д.

* Ограничение

Web форма

Получение полного списка населенных пунктов (городов) страны

Структура API запроса для получения всех городов :

http://htmlweb.ru/json/geo/city_list?country=СТРАНА&api_key=API_KEY_из_профиля
Входные параметры:
  • country - страна. Может быть задана кодом или названием

    Необязательные:

  • area - регион, если передан, то выводятся только населенные пункты этого региона
  • rajon - район, если передан, то выводятся только населенные пункты этого района
  • level - размер населенного пункта (0-4) Для включения в выборку только крупных городов добавьте параметр level=2. Если хотите получить только крупнейшие города, добавьте параметр level=1
  • p, perpage - с какой страницы и сколько на странице

* Ограничение

Информация о городе по id

Для получения информации о конкретном городе по id в формате json выполните следующий запрос:

https://htmlweb.ru/json/geo/city/1?api_key=API_KEY_из_профиля

В кратком формате:

https://htmlweb.ru/json/geo/city/1?short&api_key=API_KEY_из_профиля

Для получения строки в формате SQL для сохранения в базу выполните следующий запрос:

https://htmlweb.ru/api/geo/city/1?sql

или в старом формате:

http://htmlweb.ru/geo/api.php?city=1&json&api_key=API_KEY_из_профиля

Для получения краткой информации о конкретном городе по id в формате json выполните следующий запрос:

http://htmlweb.ru/geo/api.php?city=1&json&short&api_key=API_KEY_из_профиля

Для получения строки в формате SQL для сохранения в базу с указанием списка полей, выполните следующий запрос:

http://htmlweb.ru/geo/api.php?city=1&sql=pb_city&fields=id,name,english,area,rajon,country&api_key=API_KEY_из_профиля

Получение полного списка районов населенного пункта (города)

Структура API запроса для получения всех районов города:

http://htmlweb.ru/json/geo/rajon_city_list?city=КОД_ГОРОДА&api_key=API_KEY_из_профиля
Входные параметры:
  • city - код города

Пример для Ростова-на-Дону:

https://htmlweb.ru/json/geo/rajon_city_list/?city=1711&api_key=API_KEY_из_профиля

Для поиска города по части названия удобно использовать поиск. Пример для Ростова-на-Дону:

https://htmlweb.ru/json/geo/search/?tbl=city&search=ростов-на-дону&api_key=API_KEY_из_профиля

* Ограничение

Информация о стране по коду или названию

Для получения информации о стране по id в формате json выполните следующий запрос:

https://htmlweb.ru/geo/api.php?country=ru&info&json&api_key=API_KEY_из_профиля

Для получения краткой информации о стране по названию в формате json выполните следующий запрос:

https://htmlweb.ru/geo/api.php?country=Россия&json&info&short&charset=utf-8&api_key=API_KEY_из_профиля

Информация о регионе(штате,области) по коду

Для получения информации о стране по id в формате json выполните следующий запрос:

https://htmlweb.ru/geo/api.php?area=1&info&json&api_key=API_KEY_из_профиля

API получения списка городов (населенных пунктов) по части названия города

Структура API запроса для получения списка городов по части названия:

http://htmlweb.ru/geo/api.php?city_name=москва&json&api_key=API_KEY_из_профиля

Ответ:

{"limit":46,
"0":{"id":1,"name":"Москва","area":1,"telcod":"495,499","latitude":55.755787,"longitude":37.617634,"time_zone":4,"english":"Moscow","rajon":3597,"country":"RU","sound":"M210","level":1,"iso":"MOW","vid":1,"full_name":"Москва (Московская область, Домодедовский район)"},
"1":{"id":169703,"name":"Москва","area":48,"telcod":"","latitude":57.448612,"longitude":29.185556,"time_zone":"0","english":"Moscow","rajon":3589,"country":"RU","sound":"M210","level":"0","iso":"","vid":"0","full_name":"Москва (Псковская область, Порховский район)"},
"2":{"id":193458,"name":"Москва","area":61,"telcod":"","latitude":null,"longitude":null,"time_zone":"0","english":"Moscow","rajon":1535,"country":"RU","sound":"M210","level":"0","iso":"","vid":"0","full_name":"Москва (Тверская область, Пеновский район)"},
"3":{"id":217176,"name":"Москва","area":27,"telcod":"","latitude":null,"longitude":null,"time_zone":"0","english":"Moscow","rajon":3164,"country":"RU","sound":"M210","level":"0","iso":"","vid":"0","full_name":"Москва (Кировская область, Верхошижемский район)"},
"4":{"id":462041,"name":"Москва","area":7859,"telcod":"","latitude":null,"longitude":null,"time_zone":"0","english":"Moscow","rajon":"0","country":"KG","sound":"M210","level":"0","iso":"","vid":"0","full_name":"Москва (Киргизия, Баткенская област)"}
}

Вариант запроса для получения готового html кода для вставки на страницу в <Select></Select>

http://htmlweb.ru/geo/api.php?city_name=москва&api_key=API_KEY_из_профиля

Ответ:

<option value='1'>Москва (Московская область, Домодедовский район)</option>
<option value='169703'>Москва (Псковская область, Порховский район)</option>
<option value='193458'>Москва (Тверская область, Пеновский район)</option>
<option value='217176'>Москва (Кировская область, Верхошижемский район)</option>
<option value='462041'>Москва (Киргизия, Баткенская област)</option>
Web форма

API получения ближайших городов(населенных пунктов) от заданного

Структура API запроса для получения ближайших населенных пунктов:

http://htmlweb.ru/api/geo/city_coming/?city_coming=ID_CITY&json&api_key=API_KEY_из_профиля

Например, для Москвы:

http://htmlweb.ru/api/geo/city_coming/?city_coming=1&json&api_key=API_KEY_из_профиля

Ответ:

{"0":{"id":837,"name":"Ильпырский","area":24,"telcod":"","latitude":55.755772,"longitude":37.617760,"time_zone":null,"english":"Il'pyrskiy","rajon":1512,"country":"RU","sound":"I416","level":"0","iso":"","vid":"0","distance":"0.008051199154096073","full_name":"Ильпырский (Россия, Камчатская область, Карагинский район)"},
 "1":{"id":5882,"name":"Вилючинск-3","area":24,"telcod":41538,"latitude":55.755772,"longitude":37.617760,"time_zone":null,"english":"Vilyuchinsk-3","rajon":"0","country":"RU","sound":"V422","level":"0","iso":"","vid":"0","distance":"0.008051199154096073","full_name":"Вилючинск-3 (Россия, Камчатская область)"},
 "2":{"id":18812,"name":"Покровка","area":1,"telcod":3459,"latitude":55.759521,"longitude":37.646999,"time_zone":null,"english":"Pokrovka","rajon":2925,"country":"KG","sound":"P261","level":"0","iso":"","vid":"0","distance":"1.8842262410223318","full_name":"Покровка (Киргизия, Московская область, Клинский район)"},
  ....
 "19":{"id":5743,"name":"Вилла Гора","area":25,"telcod":8145623,"latitude":55.779900,"longitude":37.394295,"time_zone":null,"english":"Villa gora","rajon":1303,"country":"RU","sound":"V426","level":"0","iso":"","vid":"0","distance":"14.229374783729542","full_name":"Вилла Гора (Россия, Республика Карелия, Пряжинский район)"},
 "limit":"40"
}

Вариант запроса для получения готового html кода для вставки на страницу:

http://htmlweb.ru/api/geo/city_coming/?city_coming=1&api_key=API_KEY_из_профиля

Ответ:

<p>Ближайшие города (населенные пункты) для <span style='font-size:10px;' title='latitude, longitude'>(55,755787, 37,617634)</span>:</p>
<div class='box'>
    <a href="http://htmlweb.ru/geo/country/RU/city/837"><b>Ильпырский</b></a> - <b>0 км </b> <span style='font-size:10px;' title='latitude, longitude'>(55.755772, 37.617760)</span><br>
    <a href="http://htmlweb.ru/geo/country/RU/city/5882"><b>Вилючинск-3</b></a> - <b>0 км </b> <span style='font-size:10px;' title='latitude, longitude'>(55.755772, 37.617760)</span><br>
    <a href="http://htmlweb.ru/geo/country/KG/city/18812"><b>Покровка</b> (Pokrovka)</a> - <b>2 км </b> <span style='font-size:10px;' title='latitude, longitude'>(55.759521, 37.646999)</span><br>
    ....
    <a href="http://htmlweb.ru/geo/country/RU/city/5743"><b>Вилла Гора</b></a> - <b>14 км </b> <span style='font-size:10px;' title='latitude, longitude'>(55.779900, 37.394295)</span><br>
</div>

Дополнительные необязательные параметры:
country=RU - только в этой стране (код страны). Если указан, но пустой, то код страны из переданного города
country_other=RU - только в стране не совпадающей с этой (код страны). Если указан, но пустой, то код страны из переданного города
length=500 - расстояние в пределах которого осуществляется поиск, км
level=1 - только крупнейшие города
level=2 - большие и крупнейшие города
p=N - с какой страницы выдавать список городов
perpage=30 - сколько городов выводить в списке (за каждые 20 населенных пунктов списывается один запрос, подробнее...)

Web форма

API получения ближайших городов (населенных пунктов) от заданных координат

Структура API запроса для получения ближайших населенных пунктов:

https://htmlweb.ru/api/geo/city_coming/?latitude=XXX&longitude=YYY

Дополнительные необязательные параметры:
country=RU - только в этой стране (код страны)
length=500 - расстояние в пределах которого осуществляется поиск, км
level=1 - только крупнейшие города
level=2 - большие и крупнейшие города
p=N - с какой страницы выдавать список городов
perpage=50 - сколько городов выводить в списке (за каждые 20 населенных пунктов списывается один запрос, подробнее...)

Пример запроса:
https://htmlweb.ru/api/geo/city_coming/?latitude=54&longitude=27&country=by&level=2&length=500&json&api_key=API_KEY_из_профиля

API получения города по GPS - координатам

Данный запрос отличается от предыдущего параметром perpage=1, требующим вернуть только один ближайший населенный пункт. Структура запроса для получения ближайшего города по GPS-координатам:

http://htmlweb.ru/api/geo/city_coming/?perpage=1&latitude=XXX&longitude=YYY&api_key=API_KEY_из_профиля

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

Web форма

API расчета расстояния между городами

Структура API запроса для расчета расстояния в километрах между городами:

новый формат запроса:
https://htmlweb.ru/json/geo/distance?city1=1&city2=1711
старый формат запроса:
http://htmlweb.ru/geo/api.php?city1=ID_CITY1&city2=ID_CITY2&json&api_key=API_KEY_из_профиля

Например, для расчета расстояния между Москвой и Ростовом-на-Дону:

http://htmlweb.ru/geo/api.php?city1=1&city2=1711&json&api_key=API_KEY_из_профиля

Ответ для старого формата:

{"distance":958.881,
"city1":{"id":1,"name":"Москва","area":1,"telcod":"495,499","latitude":55.755787,"longitude":37.617634,"time_zone":4.00,"english":"Moscow","rajon":"0","country":"RU","sound":"M210","level":1,"iso":"","vid":"0","full_name":"Москва (Россия, Московская область)"},
"city2":{"id":1711,"name":"Ростов-на-Дону","area":49,"telcod":863,"latitude":47.233189,"longitude":39.715000,"time_zone":4.00,"english":"Rostov-na-donu","rajon":"0","country":"RU","sound":"R231","level":1,"iso":"","vid":1,"full_name":"Ростов-на-Дону (Россия, Ростовская область)"},
"limit":42}

Ответ для нового формата:

{"status":200,"distance":958.881,"limit":3896,"balans":1000}

Вариант запроса для получения готового html кода для вставки на страницу:

http://htmlweb.ru/geo/api.php?city1=1&city2=1711&api_key=API_KEY_из_профиля

Ответ:

<p>Ближайшие города (населенные пункты) для <span style='font-size:10px;' title='latitude, longitude'>(55,755787, 37,617634)</span>:</p>
<br />
<a href="/geo/country/RU/city/1"><b>Москва</b></a>: 37.617634, 55.755787<br />
<a href="/geo/country/RU/city/1711"><b>Ростов-на-Дону</b></a>: 39.715000, 47.233189<br />
Расстояние между <b>Москва</b> и <b>Ростов-на-Дону</b>: <b style='font-size:18px;'>958.881 км </b>

API расчета расстояния между точками на карте

Структура API запроса для расчета расстояния в километрах между точками на карте с координатами широта, долгота:

новый формат запроса:
https://htmlweb.ru/json/geo/distance?latitude1=55.755787&longitude1=37.617634&latitude2=47.233189&longitude2=39.715000

Ответ:

{"status":200,"distance":958.881,"limit":3896,"balans":1000}

Получить названия населенных пунктов, областей, регионов на разных языках, переименования и синонимы

Структура API запроса для получения всех альтернативных названий:

http://htmlweb.ru/json/geo/sinonim?sinonim=НАИМЕНОВАНИЕ&api_key=API_KEY_из_профиля

Входные параметры:

  • sinonim - для какого названия требуется список синонимов
  • lang2obj - заменить в выборке поле lang на объект, содержащий подробную информацию о языке. При передаче этого параметра дополнительно спишется ещё один запрос

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

https://htmlweb.ru/json/geo/sinonim/Москва?api_key=API_KEY_из_профиля
http://htmlweb.ru/json/geo/sinonim?sinonim=Москва&api_key=API_KEY_из_профиля

Ответ:

{"status":200,
"items":[
    {"id":601562,"name":"Москва","sinonim":"Moskau","tbl":"city","lang":481,"tbl_id":0},
    {"id":601563,"name":"Москва","sinonim":"Moscou","tbl":"city","lang":745,"tbl_id":0},
    {"id":601564,"name":"Москва","sinonim":"Moscú","tbl":"city","lang":230,"tbl_id":0},
    {"id":601565,"name":"Москва","sinonim":"Mosca","tbl":"city","lang":235,"tbl_id":0},
    {"id":601566,"name":"Москва","sinonim":"Moscovo","tbl":"city","lang":230,"tbl_id":0},
    {"id":601567,"name":"Москва","sinonim":"Moskwa","tbl":"city","lang":540,"tbl_id":0},
    ....
    {"id":601617,"name":"Москва","sinonim":"Мускав","tbl":"city","lang":86,"tbl_id":0}],
"limit":20,
"balans":450}

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

https://htmlweb.ru/json/geo/sinonim/Москва?lang2obj
http://htmlweb.ru/json/geo/sinonim?sinonim=Москва&lang2obj&api_key=API_KEY_из_профиля

Ответ:

{"status":200,"items":[
    {"id":601562,"name":"Москва","sinonim":"Moskau","tbl":"city","lang":{"id":481,"name":"Немецкий","english":"German","iso1":"de","iso2":"deu\/ger","iso3":"deu","gost":"нем"},"tbl_id":0},
    {"id":601563,"name":"Москва","sinonim":"Moscou","tbl":"city","lang":{"id":745,"name":"Французский","english":"French","iso1":"fr","iso2":"fra\/fre","iso3":"fra","gost":"фра"},"tbl_id":0},
    {"id":601564,"name":"Москва","sinonim":"Moscú","tbl":"city","lang":{"id":230,"name":"Испанский","english":"","iso1":"es","iso2":"esl\/spa","iso3":"spa","gost":"исп"},"tbl_id":0},
    {"id":601565,"name":"Москва","sinonim":"Mosca","tbl":"city","lang":{"id":235,"name":"Итальянский","english":"Italian","iso1":"it","iso2":"ita","iso3":"ita","gost":"ита"},"tbl_id":0},
    ....
    ],
"limit":19,
"balans":450}

Web форма

Структура API запроса для поиска:

http://htmlweb.ru/json/geo/search?search=Москва&api_key=API_KEY_из_профиля
https://htmlweb.ru/json/geo/search/Москва?api_key=API_KEY_из_профиля

Входные параметры:

  • search - Страна или ISO код страны или название столицы или город в стране

Необязательные:

  • tbl = country | area | rajon | city - искать только в странах, областях, районах, городах
  • country - искать только в указанной стране
  • capital2obj - заменить в выборке поле capital на объект, содержащий подробную информацию о столице, иначе возвращается только код столицы. Спишется +1 запрос
  • area2obj - заменить в выборке поле area на объект, содержащий подробную информацию о регионе, иначе возвращается только код региона.

Кроме стандартного набора форматов вывода (json, xml, api), поддерживает формат html - возвращает список ссылок в html-формате. Для этого добавьте в запрос параметр &html, например: https://htmlweb.ru/api/geo/search/Москва?html.

Возвращает:

  • country - список стран
  • area - список регионов
  • rajon - список районов
  • city - список населенных пунктов

Ограничение: возвращается не более 50 позиций в каждом элементе выборки

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

http://htmlweb.ru/json/geo/search?search=Москва&api_key=API_KEY_из_профиля

Ответ:

{"status":200,
    "city":{"1":{"id":1,"name":"Москва","area":1,"telcod":"495,496,498,499","latitude":55.7558,"longitude":37.6176,"time_zone":3,"tz":"","english":"Moscow","rajon":0,"sub_rajon":0,"country":"RU","sound":"M210","level":1,"iso":"MOW","vid":1,"post":101000,"geonameid":null,"wiki":"ru.wikipedia.org\/wiki\/%D0%9A%D0%BE%D1%80%D0%BE%D0%BB%D1%91%D0%B2_(%D0%B3%D0%BE%D1%80%D0%BE%D0%B4)"}},
    "area":[{"id":1,"name":"Московская область","okrug":"Центральный федеральный округ","autocod":"50,90,150,190,177,199","capital":1,"english":"Moscow oblast","iso":"MOS","country":"RU","vid":0}],
"limit":483,
"balans":450
}

Ограничение

При расчете лимита за один запрос принимается один запрос с выборкой не более 20 записей. Тарификация производится за каждый запрос!

Обратите внимание, по умолчанию выводится с 1-ой по 20-ую записи. Если Вы хотите вывести следующие 20 записей укажите дополнительный параметр:

&p=2

Если Вы хотите выводить не по 20, а другое кол-во укажите параметр:

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