Муниципальное бюджетное образовательное учреждение;pdf

API Яндекс.Карт
Поиск по Народной карте
2.10.2014
API Яндекс.Карт. Поиск по Народной карте. Версия 1.0
Дата сборки документа: 2.10.2014.
Этот документ является составной частью технической документации Яндекса.
Сайт справки к сервисам Яндекса: http://help.yandex.ru
© 2008—2014 ООО «ЯНДЕКС». Все права защищены.
Предупреждение об исключительных правах
Яндексу (а также указанному им правообладателю) принадлежат исключительные права на все результаты интеллектуальной деятельности и приравненные к ним
средства индивидуализации, используемые при разработке, поддержке и эксплуатации сервиса API Яндекс.Карт. К таким результатам могут относиться, но не
ограничиваясь указанными, программы для ЭВМ, базы данных, изображения, тексты, другие произведения, а также изобретения, полезные модели, товарные знаки,
знаки обслуживания, коммерческие обозначения и фирменные наименования. Эти права охраняются в соответствии с Гражданским кодексом РФ и международным
правом.
Вы можете использовать сервис API Яндекс.Карт или его составные части только в рамках полномочий, предоставленных вам Пользовательским соглашением
сервиса API Яндекс.Карт или специального соглашения.
Нарушение требований по защите исключительных прав правообладателя влечет за собой дисциплинарную, гражданско-правовую, административную
или уголовную ответственность в соответствии с российским законодательством.
Контактная информация
ООО «ЯНДЕКС»
http://www.yandex.ru
Тел.: +7 495 739 7000
Email: [email protected]
Главный офис: 119021, Россия, г. Москва, ул. Льва Толстого, д. 16
Содержание
Поиск по Народной карте ................................................................................................................................................................. 4
Параметры HTTP-запроса ................................................................................................................................................................. 4
Ответ. Результаты поиска ................................................................................................................................................................. 5
Примеры .............................................................................................................................................................................................. 8
API Яндекс.Карт
Поиск по Народной карте
Поиск по Народной карте
Поиск по Народной карте
API Яндекс.Карт предоставляет возможность поиска по Народной карте, нарисованной пользователями
Яндекса. Пользователи наносят на карту границы объектов, указывают их тип, снабжают названием
и описанием, помечают ключевыми словами (присваивают метки). API позволяет производить поиск
по этим объектам.
Поиск объектов на Народной карте можно производить средствами JavaScript API или с помощью HTTPзапросов. При обращении к геокодеру по HTTP-протоколу ответ может быть сформирован либо в виде XML-документа на языке YMapsML, либо в формате JSON.
Внимание!
При осуществлении поискового HTTP-запроса в параметрах запроса необходимо указать API-ключ.
Ключ можно получить, заполнив соответствующую форму.
В данном документе описаны параметры поискового HTTP-запроса к Народной карте, ответ,
содержащий результаты поиска, а также приведены примеры использования.
Параметры HTTP-запроса
Поисковый запрос к Народной карте представляет собой обращение по HTTP-протоколу к URL http://
psearch-maps.yandex.ru/1.x/. Обязательными параметрами запроса являются:
•
text — текст поискового запроса.
•
key — API-ключ Яндекс.Карт.
Например, для того, чтобы найти на Народной карте самый известный памятник Петру I в Санкт-Петербурге, можно выполнить следующий запрос:
http://psearch-maps.yandex.ru/1.x/?text=Медный всадник&key=API-ключ
Ответ будет содержать координаты размещённых на Народной карте объектов, соответствующих запросу (если таковые нашлись) и дополнительную информацию о найденных объектах.
В таблице приведен полный список параметров HTTP-запроса.
Параметр
Значение
Пример
Обязательные параметры
text
Текст поискового запроса. Напри- text=остров Балчуг
мер, название объекта.
key
Ключ API Яндекс.Карт.
key=API-ключ
Формат ответа геокодера:
format=json
Необязательные параметры
format
•
xml — результат возвращается
в виде YMapsML-документа;
•
json — результат возвращается
в формате JSON.
Значение по умолчанию: xml.
callback
API Яндекс.Карт
Имя JavaScript-функции, в которую callback=my_response_handl
передается ответ геокодера (в соот- er
ветствии с соглашениями JSONP).
Поиск по Народной карте
4
Поиск по Народной карте
Параметр
Значение
Пример
Параметр учитывается только в том
случае, если ответ возвращается
в формате JSON.
ll,spn
Область, в районе которой предполо- ll=37.618920,55.756994&spn
жительно находятся искомые объек- =0.552069,0.400552
ты.
Параметр
ll{longitude,latitude} задаёт долготу и широту центра области (в градусах), а spn {span} —
её протяженность (в градусах).
Протяженность области задается
двумя числами, первое из которых
есть разница между максимальной
и минимальной долготой, а второе —
между максимальной и минимальной широтой данной области.
rspn
results
Позволяет ограничить поиск объек- rspn=1
тов областью, заданной с помощью
параметров ll и spn. Возможные
значения:
•
0 — не ограничивать поиск
(по умолчанию),
•
1 — ограничить.
Максимальное количество выводи- results=5
мых результатов.
Значение по умолчанию: 10.
skip
Количество результатов (начиная
с первого), которое необходимо
пропустить.
skip=10
Ответ. Результаты поиска
Результаты поискового запроса к Народной карте могут быть возвращены в следующих форматах:
•
XML;
•
JSON (может быть возвращен в качестве аргумента функции — JSONP).
Оба формата имеют одинаковую структуру, а возвращаемые результаты абсолютно одинаковы. В случае XML-выдачи результаты представлены в виде XML-элементов. При использовании JSON используются пары «ключ»:«значение», заключенные в фигурные скобки, и группировка с помощью массивов — квадратные скобки. Название XML-элемента совпадает с соответствующем ключом в JSON-выдаче.
Ответ в формате XML
Рассмотрим XML-ответ сервиса на запрос «мехмат МГУ»:
http://psearch-maps.yandex.ru/1.x/?format=xml&text=мехмат МГУ&key=API-ключ
Для получения выдачи в формате XML параметр format можно не использовать.
http://psearch-maps.yandex.ru/1.x/?text=мехмат МГУ&key=API-ключ
Ответ:
API Яндекс.Карт
Поиск по Народной карте
5
Поиск по Народной карте
<?xml version="1.0" encoding="utf-8"?>
<ymaps xmlns="http://maps.yandex.ru/ymaps/1.x">
<GeoObjectCollection>
<metaDataProperty xmlns="http://www.opengis.net/gml">
<PSearchMetaData xmlns="http://maps.yandex.ru/psearch/1.x">
<PSearchRequest>
<request> мехмат МГУ</request>
<results>10</results>
<boundedBy xmlns="http://www.opengis.net/gml">
<Envelope>
<lowerCorner>38.869626 47.161456</lowerCorner>
<upperCorner>38.969627 47.261451</upperCorner>
</Envelope>
</boundedBy>
</PSearchRequest>
<PSearchResponse>
<found>1</found>
</PSearchResponse>
</PSearchMetaData>
</metaDataProperty>
<featureMember xmlns="http://www.opengis.net/gml">
<GeoObject xmlns="http://maps.yandex.ru/ymaps/1.x">
<metaDataProperty xmlns="http://www.opengis.net/gml">
<PSearchObjectMetaData xmlns="http://maps.yandex.ru/psearch/1.x">
<id>56</id>
<name>Главное здание МГУ</name>
<kind>house</kind>
<Tags>
<tag>мгу</tag>
<tag>мехмат</tag>
<tag>геофак</tag>
</Tags>
<Address>
<locality>Москва</locality>
<thoroughfare>Ленинские горы</thoroughfare>
<premiseNumber>1</premiseNumber>
</Address>
</PSearchObjectMetaData>
</metaDataProperty>
<name xmlns="http://www.opengis.net/gml">Главное здание МГУ</name>
<boundedBy xmlns="http://www.opengis.net/gml">
<Envelope>
<lowerCorner>37.527193 55.700877</lowerCorner>
<upperCorner>37.534415 55.705026</upperCorner>
</Envelope>
</boundedBy>
<Point xmlns="http://www.opengis.net/gml">
<pos>37.530804 55.702952</pos>
</Point>
</GeoObject>
</featureMember>
</GeoObjectCollection>
</ymaps>
XML-ответ представляет собой документ в формате YMapsML, удовлетворяющий XML-схеме http://
maps.yandex.ru/psearch/1.x.
Элемент PSearchRequest содержит информацию о тексте и прочих параметрах запроса, а элемент
PSearchResponse — количество найденных объектов.
Информация о найденных объектах содержится в элементах GeoObject: описание объекта размещается в элементе PSearchObjectMetaData, географическая информация — в элементах Point
и boundedBy.
API Яндекс.Карт
Поиск по Народной карте
6
Поиск по Народной карте
Элемент PSearchObjectMetaData содержит следующую информацию об объекте:
•
уникальный идентификатор объекта, размещённого на Народной карте — элемент id;
•
название объекта — элемент name;
•
символьный идентификатор типа объекта (здание, населенный пункт, лес, водоем и пр., если указан) — элемент kind;
•
метки, присвоенные пользователями (если присвоены) — элемент Tags;
•
адрес объекта (если удалось определить) — элемент Address.
Координаты центра объекта содержатся в элементе Point, а в элементе boundedBy – координаты
вершин минимального прямоугольника, в который может быть вписан объект.
Ответ в формате JSON
Чтобы получить ответ в формате JSON, необходимо присвоить параметру format значение json:
http://psearch-maps.yandex.ru/1.x/?format=json&text=мехмат МГУ&key=API-ключ
Ответ:
{
"response": {
"GeoObjectCollection": {
"metaDataProperty": {
"PSearchMetaData": {
"PSearchRequest": {
"request": " мехмат МГУ",
"results": "10"
},
"PSearchResponse": {
"found": "1"
}
}
},
"featureMember": [
{
"GeoObject": {
"metaDataProperty": {
"PSearchObjectMetaData": {
"id": "56",
"name": "Главное здание МГУ",
"kind": "house",
"Tags": {
"tag": "мгу",
"tag": "мехмат",
"tag": "геофак"
},
"Address": {
"locality": "Москва",
"thoroughfare": "Ленинские горы",
"premiseNumber": "1"
}
}
},
"name": "Главное здание МГУ",
"boundedBy": {
"Envelope": {
"lowerCorner": "37.527202 55.700872",
"upperCorner": "37.534334 55.705031"
}
API Яндекс.Карт
Поиск по Народной карте
7
Поиск по Народной карте
},
"Point": {
"pos": "37.530768 55.702952"
}
}
}
]
}
}
}
JSONP
Политика безопасности современных браузеров не позволяет веб-страницам загружать данные со сторонних серверов. Под сторонним подразумевается сервер, доменное имя которого отличается от доменного имени сервера, на котором находится страница. Если необходимо сформировать страницу, запрашивающую результаты поиска по Народной карте, следует воспользоваться технологией JSONP.
При использовании JSONP серверу, возвращающему данные, передается имя функции, и результат возвращается в виде объекта JSON, но в качестве параметра функции с указанным именем.
Чтобы получить результаты поиска в виде JSONP, необходимо присвоить параметру callback
имя функции, которая будет обрабатывать возвращенные в формате JSON результаты.
Так, по запросу
http://psearch-maps.yandex.ru/1.x/?format=json&callback=my_function&text=мехмат
МГУ&key=API-ключ
будет возвращен JSON-объект из предыдущего примера, но в виде аргумента функции my_function:
my_function({
"response": {
"GeoObjectCollection": {
"metaDataProperty": {
"PSearchMetaData": {
"PSearchRequest": {
"request": " мехмат МГУ",
"results": "10"
...
});
Примеры
Простой поиск по названию
Запрос «Царь-колокол»: http://psearch-maps.yandex.ru/1.x/?text=Царь-колокол&key=API-ключ.
Этот же запрос, но для выдачи результатов в формате JSON: http://psearch-maps.yandex.ru/1.x/?
format=json&text=Царь-колокол&key=API-ключ.
Поиск объектов в заданной области
Если в запросе указать область поиска (параметр spn), то первыми будут выведены объекты, наиболее
близкие к этой области. Например, чтобы найти улицу Ленина, находящуюся в г. Таганрог, можно выполнить
следующий
запрос:
http://psearch-maps.yandex.ru/1.x/?text=улица
Ленина&ll=38.919626,47.211477&spn=1.0,1.0&key=API-ключ.
Первый результат выдачи соответствует улице Ленина г. Таганрог, остальные отсортированы по расстоянию от центра области поиска и степени соответствия тексту запроса.
API Яндекс.Карт
Поиск по Народной карте
8
Поиск по Народной карте
Если необходимо найти только те объекты, которые находятся в заданной области, следует использовать
параметр
rspn:
http://psearch-maps.yandex.ru/1.x/?text=Красная
площадь&ll=38.919626,47.211477&spn=0.1,0.1&rspn=1&key=API-ключ.
Выбор результатов поиска
Некоторым запросам может соответствовать большое количество найденных объектов. HTTP-запрос
позволяет сформировать выборку результатов поиска. Для этого предназначены следующие параметры:
•
results — максимальное количество выводимых результатов;
•
skip — количество результатов (начиная с первого), которое необходимо пропустить.
Запрос
«техникум»,
первые
text=техникум&results=5&key=API-ключ.
5
результатов:
Запрос «институт», 7 результатов, начиная
text=институт&results=7&skip=23&key=API-ключ.
API Яндекс.Карт
с
23-го:
http://psearch-maps.yandex.ru/1.x/?
http://psearch-maps.yandex.ru/1.x/?
Поиск по Народной карте
9
API Яндекс.Карт
Поиск по Народной карте
2.10.2014