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

Автор: | 18.09.2011
9 комментариев

Вам наверно известно о существовании электронного справочника по 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 комментариев

  2. Федор

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

    Ответить ↓
    1. admin Автор записи

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

      Ответить ↓
  3. Николай

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

    Ответить ↓
  4. Геннадий

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

    Ответить ↓
  5. александр

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

    Ответить ↓
  6. Валерий

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

    Ответить ↓
  7. Алекс

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

    Ответить ↓

Добавить комментарий

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