Знакомство с API 2ГИС

Автор: | 18.09.2011

Вам наверно известно о существовании электронного справочника по 134 городам России и 2 городам Украины (Одесса и Ильичёвск) 2ГИС (ДубльГИС).

Сообщаю интересную новость для разработчиков — теперь любой из Вас может использовать данные 2ГИС совершенно бесплатно через справочное API 2ГИС.

Данные представляют собой подробную информацию по каждой организации в каждом городе — начиная от названия и контактов, заканчивая временем работы и способами оплаты услуг. Важный момент, что данные не просто собираются – их постоянно обновляют и дополняют сотни специалистов колл-центра 2ГИС по всей стране.

В этой заметке я расскажу как начать работать с API и покажу несколько примеров использования.

В самом начале необходимо получить уникальный идентификационный ключ (key). По этому ключу осуществляется доступ к API, а также регистрация действий пользователя. Для получения ключа необходимо заполнить анкету на подключение API.

После этого через некоторое время вы получите свой ключ.

Текущая версия справочного API — 1.3.

Для поиска и получения информации о фирмах в API поддерживаются 4 метода:

Метод Описание
http://catalog.api.2gis.ru/search? Поиск фирм по запросам «Что?», «Где?», который выдает сокращенные карточки фирм с названием фирмы, рубриками и идентификатором фирмы.
http://catalog.api.2gis.ru/searchinrubric? Поиск фирм, относящихся к конкретной рубрике. Метод идентичен методу search. Гео-фильтрация не осуществляется.
http://catalog.api.2gis.ru/profile? Получение полного профиля фирмы с контактами, временем работы, и прочими параметрами.
http://catalog.api.2gis.ru/firmsByFilialId? Получение списка фирм, связанных одним юридическим лицом. К примеру, все офисы МТС.

Параметры можно передать GET или POST запросом.

Названия переменных в запросе регистрозависимые, то есть what и WHAT — это разные параметры.

В API названия параметров всегда должны передаваться в нижнем регистре.

Результаты выдаются в XML или JSON форматах. По умолчанию используется JSON.

Ожидаемые и поддерживаемые нагрузки: от 100 до 200 запросов в секунду.

Время ответа сервера до 200 мс.

Давайте рассмотрим первый пример поиска организации, выполнения запроса и обработки ответа.

Для поиска может использоваться стандартная форма с двумя текстовыми полями: поле Что (параметр what) — в котором указывается название фирмы или область деятельности фирмы и поле Где (параметр where) — обязательно должно содержать название населенного пункта (Новосибирск, Омск), название населенного пункта + район (Новосибирск Центральный) или название населенного пункта + улица (Новосибирск Советская). Если не указать название населенного пункта, то поиск выполнен не будет.

Пример запроса (кафе Советский район Нижнего Новгорода):

http://catalog.api.2gis.ru/search?what=кафе&where=Нижний%20Новгород%20Советский%20район&page=1&pagesize=30&key=rudaxa6557&version=1.3&sort=relevance&output=xml

Код ответа в формате XML: ссылка

Или то же самое но в формате JSON: ссылка

Подробнее о параметрах запросов можно прочитать в документации.

Я рассмотрю реализацию нескольких примеров использования на практике.

Начинаем с реализации первого примера, вывод фирм по рубрикам.

В начале в столбец выводятся все названия корневых (главных) рубрик.

По щелчку по ссылке с наименованием рубрики, появляется столбец со списком подрубрик.

Затем, по клику на одной из подрубрик — показывется список первых 30 наименований фирм с адресами, отсортерованными по наилучшему соответствию запросу (релевантности).

Посмотреть пример в действии

Код примера rubriki.html

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml"> 
  <head> 
<title>API 2GIS - Пример вывод рубрик</title> 
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 
 
<style type="text/css"> 
  html, body {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
  font-size: 12px;
}
</style>
 
<script type="text/javascript">
 
$(document).ready(function(){
var url="http://catalog.api.2gis.ru/rubricator?where=Нижний Новгород&output=jsonp&key=rudaxa6557&version=1.3&callback=?";
$.getJSON(url,function(json){
	$("#content").html('');
	$.each(json.result,function(i,result){
 
	$("#content").append(
		'<div class="post">'+
			'<a href="#" onClick="podcat('+"'"+result.id+"'"+')">'+result.name+'</a>'+
		'</div>'
	);
	});
});
});
 
function podcat(id){
 
var url2="http://catalog.api.2gis.ru/rubricator?where=Нижний Новгород&parent_id="+id+"&output=jsonp&key=rudaxa6557&version=1.3&callback=?";
$.getJSON(url2,function(json){
$("#content2").html('');
$.each(json.result,function(i,result){
$("#content2").append(
		'<div class="post">'+
			'<a href="#" onClick="spfirms('+"'"+result.name+"'"+')">'+result.name+'</a>'+
		'</div>'
	);
});
$("#content2").append('<br /><br />');
});
}
 
function spfirms(rubname){
 
var url3="http://catalog.api.2gis.ru/searchinrubric?what="+rubname+"&where=Нижний Новгород&page=1&pagesize=30&output=jsonp&key=rudaxa6557&version=1.3&sort=relevance&callback=?";
$.getJSON(url3,function(json){
$("#content3").html('');
$.each(json.result,function(i,result){
$("#content3").append(
		'<div class="post">'+
			'<strong>'+result.name+'</strong>'+
			'<p>Адрес: '+result.address+'</p>'+
		'</div>'
	);
});
$("#content3").append('<br /><br />');
});
}
 
 
</script>
 
</head> 
<body> 
<table>
<tr><td style="vertical-align: top;"><div id="content"></div></td><td style="vertical-align: top;"><div id="content2"></div></td><td style="vertical-align: top;"><div id="content3"></div></td></tr>
</table>
 
</body> 
</html>

В самом начале мы подключаем JavaScript-библиотеку jQuery из хранилища библиотек Google.

Ее мы будем использовать для создания AJAX-запросов и обработки ответов сервера.

Затем в строке

var url="http://catalog.api.2gis.ru/rubricator?where=Нижний Новгород&output=jsonp&key=rudaxa6557&version=1.3&callback=?";

Формируем URL для запроса корневых рубрик справочника для Нижнего Новгорода.

Т.к. запрос является кросс-домнным, мы отправляем запрос на домен catalog.api.2gis.ru, то в параметрах указываем формат вывода output=jsonp и название callback функции для jsonp запроса, можно написать просто callback=?.

Затем осуществляем сам запрос $.getJSON и обрабатываем полученные данные ответа.

Подробнее о параметрах запроса на вывод рубрик и примеры ответов в формате JSON и XML можно прочитать в документации.

Далее по выбору одной из рубрик, мы вызываем функцию podcat вывода списка подрубрик, передаем в нее значение result.id.

Это значение мы подставляем в запрос в качестве параметра parent_id, т.е фомируем URL-запроса вида:

var url2="http://catalog.api.2gis.ru/rubricator?where=Нижний Новгород&parent_id="+id+"&output=jsonp&key=rudaxa6557&version=1.3&callback=?";

Осуществляем запрос и обрабатываем результат ответа.

При выборе одной из подрубрик вызывается функция spfirms в которую передается наименование подрубрики.

Мы снова формируем URL-запроса в виде:

var url3="http://catalog.api.2gis.ru/searchinrubric?what="+rubname+"&where=Нижний Новгород&page=1&pagesize=30&output=jsonp&key=rudaxa6557&version=1.3&sort=relevance&callback=?";

Осуществляем запрос методом GET и выводим ответ в виде списка наименований фирм с их адресами.

Второй пример, поиск фирм.

Для этого в начале создаем форму с двумя полями: Что ищем и Где ищем.

В первое поле мы будем вводить для поиска название фирмы или область деятельности, а во второе — где ищем, название населенного пункта с добавлением при необходимости названия района или улицы для поиска.
Например, мы хотим найти все фирмы в Нижнем Новгороде, которые занимаются продажей и установкой окон, тогда в поле «Что ищем» мы указываем «окна», а в поле «Где» — «Нижний Новгород».

И выводим список первых 20 найденных фирм.

Посмотреть пример в действии.

Для отображения результатов поиска на карте, я использовал API Яндекс.Карт, т..к текущая версия API 2ГИС (на момент написания 1.3.6) не поддерживает вывод данных на карту 2ГИС.

Код примера: search.html

<html>
<head> 
<title>API 2GIS - пример поиска фирмы</title> 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 
 
<script src="http://api-maps.yandex.ru/1.1/index.xml?key=ACuF2EkBAAAAzahYCgIASLsFm9n8EPvNjaTc8nAWiETKgYcAAAAAAAAAAAC-q61vWtIK3Kzt2yQ9qFaGJGKzXw==" type="text/javascript"></script>  
 
<style type="text/css"> 
  html, body {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
  font-size: 12px;
}
</style>
 
<script type="text/javascript">
 
var map;
 
YMaps.jQuery(document).ready(function(){		
 
map = new YMaps.Map(YMaps.jQuery("#YMapsID")[0]);
 
// Установка для карты ее центра и масштаба
map.setCenter(new YMaps.GeoPoint(43.998779,56.316537), 13);
 
// Создание группы
var gCollection = new YMaps.GeoObjectCollection("default#greenPoint");
var bounds = new YMaps.GeoCollectionBounds();
 
map.addControl(new YMaps.ToolBar());					
map.addControl(new YMaps.Zoom());
map.addControl(new YMaps.TypeControl());
 
YMaps.jQuery('#search-form').submit(function() {
var whatName = YMaps.jQuery('#what').attr('value');
var whereName = YMaps.jQuery('#where').attr('value');			
		var url='http://catalog.api.2gis.ru/search?method=search&what='+whatName+'&page=1&pagesize=20&sort=relevance&where='+whereName+'&key=rudaxa6557&version=1.3&output=jsonp&sort=relevance&callback=?';
YMaps.jQuery.getJSON(url,function(json){
 
if(json.response_code == 200)
{
YMaps.jQuery("#rezultat").html('');
gCollection = new YMaps.GeoObjectCollection("default#greenPoint");
bounds = new YMaps.GeoCollectionBounds();
map.removeAllOverlays();
YMaps.jQuery.each(json.result,function(i,result){
 
// Создает метку в центре
var placemark = new YMaps.Placemark(new YMaps.GeoPoint(result.lon,result.lat));
bounds.add(new YMaps.GeoPoint(result.lon,result.lat));
// Устанавливает содержимое балуна
placemark.name = result.name;
placemark.description = result.address;
 
// Добавляет метку на карту
gCollection.add(placemark); 
 
YMaps.jQuery("#rezultat").append(
		'<div class="post">'+
			'<a href="#" onClick="fullfirm('+"'"+result.id+"'"+','+"'"+result.hash+"'"+')">'+result.name+'</a>'+
			'<p>Адрес: '+result.address+'</p>'+			
		'</div>'
	);	
 
	});	
map.setBounds(bounds);
map.addOverlay(gCollection);
}
else
{
alert('Отсутствуют результаты поиска');
}
 
});
});	
});	
 
function fullfirm(firm_id, firm_hash)
{
var url2="http://catalog.api.2gis.ru/profile?id="+firm_id+"&hash="+firm_hash+"&output=jsonp&key=rudaxa6557&version=1.3&callback=?";
YMaps.jQuery.getJSON(url2,function(json){
YMaps.jQuery("#rezultat").html('');
map.removeAllOverlays();
YMaps.jQuery("#rezultat").append(
		'<div class="post">'+
			'<strong>'+json.name+'</strong>'+
			'<p>Адрес: '+json.address+'</p>'+
			'<p>Рубрика: '+json.rubrics+'</p>'+			
		'</div>'
	);
 
if(json.lon!="" && json.lat!= "")
			{			
			map.setCenter(new YMaps.GeoPoint(json.lon,json.lat),16);
			var placemark=new YMaps.Placemark(new YMaps.GeoPoint(json.lon,json.lat));
			placemark.name='<div style="color:#ff0303;font-weight:bold;">'+json.name+'</div>';
			placemark.description = '<strong>Адрес:</strong> '+json.address+'</div></div>';
			map.addOverlay(placemark);
			placemark.openBalloon();
			}
 
});
 
}
</script>
 
</head>
<body> 
 
 <div id="YMapsID" style="float:left; width:600px; height:400px; margin-right: 10 px;"></div>
 
            <form id="search-form" action="javascript:alert("success!");">
                <table cellpadding="0" cellspacing="0">
                    <tbody><tr>
                        <td>
                            <div class="title">Что ищем?</div>
                            <input type="text"  id="what" value="" placeholder="Например мебель...">
                        </td>
                        <td>
                            <div class="title">Где ищем?</div>
                            <input type="text"  id="where" value="Нижний Новгород" placeholder="Где ищем?">
                        </td>
                        <td valign="bottom">
                            <input type="submit" id="submit" value="Найти!">
                        </td>
                    </tr>
                </tbody></table>
            </form>
 
	<div id="rezultat"></div>
</body> 
</html>

Рассмотрим код примера подробнее.

Т. к. мы будем использовать API Яндекс.Карт, то в начале подключаем API с ключом для Вашего домена.

API Яндекс.Карт уже включет в себя JavaScript-библиотеку jQuery версии 1.3.2, поэтому нет необходимости в ее дополнительном подключении.

По клику по кнопке «Найти!», введенные данные из формы передаются в JavaScript в котором формируется запрос для поиска в виде URL:

var url='http://catalog.api.2gis.ru/search?method=search&what='+whatName+'&page=1&pagesize=20&sort=relevance&where='+whereName+'&key=rudaxa6557&version=1.3&output=jsonp&sort=relevance&callback=?';

Здесь параметр whatName — значение поля Что ищем формы, а параметр whereName — значение поля Где ищем.

Еще параметры: page — номер запрашиваемой страницы, 1 — первая; pagesize — количество результатов поиска, выводимых на одной странице (значение по умолчанию: 20), ограничение: от 5 до 50; sort — relevance (по умолчанию) — наилучшее соответствие запросу, в поиске участвует название фирмы и рубрики в которые фирма входит.

Запрос посылается методом GET на сервер, полученный ответ обрабатывается и выводится в виде списка фирм и меток на карте.

Перед формированием запроса, мы определяем начальные параметры для карты и необходимые элементы управления.

Создаем группу gCollection, в которую будут помещаться метки результатов поиска и область показа для группы bounds.

В результатах ответа предаются параметры «lon» и «lat» со значениями координат на карте, где «lon» — географические координаты широты и «lat» — координаты долготы в в системе координат WGS84.

О параметрах запроса для поиска и примеры ответов в формате JSON и XML можно прочитать в документации

При выборе одной из фирм в списке, выводиться подробная информация о ней и указывается местоположение на карте.

При этом вызывается функция fullfirm, в которую передаются два параметра: идентификатор фирмы — firm_id и уникальный хэш результатов + хэш филиала — firm_hash.

После этого формируется URL-запроса:

var url2="http://catalog.api.2gis.ru/profile?id="+firm_id+"&hash="+firm_hash+"&output=jsonp&key=rudaxa6557&version=1.3&callback=?";

Запрос посылается методом GET на сервер, полученный ответ обрабатывается и выводится в виде строк наименования и адреса фирмы, а также местоположения на карте.

В примерах я везде использовал обработку результатов представленных в формате JSON, который используется в API по умолчанию.

Вы можете использовать и формат XML, отличие будет заключаться в том, что ответ будет загружаться php-скриптом и в нем же обрабатываться, используя, например, расширение SimpleXML или обработку производить в JavaScript.

Вы понимаете, что нельзя подробно в одной заметке рассказать о всех возможностях API 2ГИС, документацию и примеры использования Вы найдете по адресу http://api.2gis.ru/doc/main/ .

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

Знакомство с API 2ГИС: 9 комментариев

  1. Федор

    Проще делать через запросы через CURL, получать ответы в JSON. И получить массив через json_decode.

    1. admin Автор записи

      В заметке я показал один из вариантов решения, можно с API 2ГИС работать другим удобным для вас способом.

  2. Николай

    Спасибо Вам за статью! Ваш сайт очень полезный и информативный, успешного продвижения!

  3. Геннадий

    Весьма познавательно. НО нет последнего шага — получения профиля организации. Если уважаемому автору не сложно, может научите, как показывать пользователю часы работы выбранной фирмы? У меня чего-то не выходит…

  4. александр

    согласен с последним каментом. Как сделать чтоб уже по клику по организации открывался вариант с описанием и картой?

  5. Валерий

    да я тоже согласен,пробовал изменять запросы составлять ответы
    ни чего не выходит выдает только название и адрес остальные данные почему то не выводит.Ни номера телефонов ни часы работы и.т.д.Подскажите кто может…

  6. Алекс

    Не могли бы написать как выводить полный профиль фирмы, пожалуйста?

Добавить комментарий для Валерий Отменить ответ

Ваш адрес email не будет опубликован. Обязательные поля помечены *