Все готово!

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

Активация Google Places API Web Service

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Places API Web Service
  3. Создание соответствующих ключей

Поиск мест

Google Places API Web Service позволяет запрашивать информацию об организациях, достопримечательностях, географических объектах и многих других местах на карте. Вы можете искать места в заданном радиусе или по прямому текстовому запросу. При этом возвращается список мест и общая информация о каждом из них. Дополнительные данные можно получить с помощью запроса данных о месте.

Поиск мест поблизости

В предыдущих версиях Places API поиск мест поблизости назывался просто "поиском мест".

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

Запрос поиска мест поблизости – это URL-адрес в формате HTTP, который выглядит следующим образом:

https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters

где output может принимать одно из следующих значений:

  • json (рекомендуется) – задает вывод в формате JavaScript Object Notation (JSON);
  • xml – задает вывод в формате XML.

Чтобы инициировать запрос поиска мест поблизости, необходимо указать определенные параметры. Все параметры разделяются амперсандами (&) в соответствии со стандартом URL-адресов.

Обязательные параметры

  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. Поэтому места, добавленные из вашего приложения, сразу же будут доступны в нем. Дополнительную информацию см. в документе Получение ключа.
  • location – широта и долгота точки, вокруг которой выполняется поиск мест. Должны быть указаны ее координаты в формате: широта,долгота.
  • radius – расстояние в метрах, в пределах которого должны находиться найденные результаты. Максимальный допустимый радиус составляет 50 000 метров. Обратите внимание, что параметр radius не следует использовать, если указано значение rankby=distance (см. раздел Дополнительные параметры ниже).
  • Если указано значение rankby=distance (см. описание в разделе Дополнительные параметры ниже), необходимо использовать параметры keyword, name или type.

Дополнительные параметры

  • keyword – слово, по которому ведется поиск во всем содержимом, проиндексированном Google для данного места, включая название, тип, адрес, отзывы пользователей и сторонний контент.
  • language – код языка, на котором следует по возможности возвращать результаты. Результаты поиска зависят от выбранного языка. Результатам на определенном языке может присваиваться более высокий рейтинг. См. список поддерживаемых языков и их коды. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.
  • minprice и maxprice (необязательно) – ценовой диапазон, ограничивающий результаты поиска. Допускаются значения от 0 (бесплатные) до 4 (самые дорогие) включительно. Точная сумма для каждого из этих значений зависит от региона.
  • name – термин, который следует сопоставить со всем контентом, индексированным Google для этого местоположения. Эквивалентно keyword. В поле name теперь можно вводить не только названия мест. Значения из этого поля объединяются со значениями поля keyword и передаются в составе той же строки поиска. Мы рекомендуем использовать в поисковых запросах только параметр keyword.
  • opennow – ограничивает результаты поиска только теми организациями (заведениями), которые открыты в момент отправки запроса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются.
  • rankby – порядок вывода результатов. Параметр rankby не следует указывать, если задан параметр radius (описывается в разделе Обязательные параметры выше). Возможны следующие значения:
    • prominence (по умолчанию) – результаты сортируются по известности. Приоритет в рейтинге отдается более известным местам, находящимся в заданной области. На известность влияет рейтинг места в индексе Google, общая популярность и другие факторы.
    • distance – результаты сортируются в порядке близости к точке, заданной в параметре location. Если указан параметр distance, необходимо также указать один или несколько параметров keyword, name или type.
  • type – ограничивает результаты поиска только теми местами, тип которых соответствует хотя бы одному из указанных. Можно указать только один тип (если указано несколько типов, все типы, кроме первого, игнорируются). См. список поддерживаемых типов.
  • types (объявлен устаревшим) – ограничивает результаты поиска только теми местами, тип которых соответствует хотя бы одному из указанных. Отдельные типы с символом трубы, например:
    type1|type2|etc.
  • pagetoken – возвращает следующие 20 результатов для последнего поискового запроса. Если указать параметр pagetoken, поиск будет выполнен с предыдущими параметрами – все параметры, кроме pagetoken, будут игнорироваться.
  • zagatselected (объявлен устаревшим) – ограничивает результаты поиска только теми местами, которые рекомендует Zagat. Необходимо просто включить параметр в запрос, не задавая никакого значения. Этот параметр не должен содержать значения true или false. Параметр zagatselected используется в порядке эксперимента и доступен только пользователям Google Places API с лицензией на Premium Plan.

Примечание для пользователей Google Maps APIs Premium Plan. В запросах необходимо указывать ключ API. В запросы нельзя включать параметры client или signature.

Пример поиска в окружении

Вот как будет выглядеть запрос на поиск мест, где можно перекусить (тип "restaurant") в радиусе 500 метров от заданной точки в г. Сиднее, Австралия, в названии которых есть слово "cruise":

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

Примечание. Для обработки приведенного в этом примере запроса в вашем приложении необходимо заменить значение key вашим собственным ключом API.

Текстовый поиск

Служба текстового поиска Google Places API Text Search – это веб-служба, которая возвращает информацию о местах на основе введенной фразы, например "пиццерия Химки", "магазины обуви рядом с Иваново" или "улица Ленина, 123". Служба возвращает список мест, соответствующий текстовой строке запроса и установленному предпочтительному местоположению.

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

Ответ на поисковый запрос будет содержать список мест. Чтобы получить подробную информацию о любом из них, можно отправить запрос данных о месте.

Поиск мест поблизости и текстовый поиск в Google Places учитываются в общей квоте ограничений на использование. При этом для запросов текстового поиска применяется коэффициент 10. Это значит, что при оценке расходования квоты каждый запрос текстового поиска учитывается как 10 обычных запросов. Если Google Places API был приобретен в рамках договора на Google Maps APIs Premium Plan, может применяться другой коэффициент. Подробную информацию см. в документации по Google Maps APIs Premium Plan.

Запрос к службе текстового поиска мест – это URL-адрес в формате HTTP, который выглядит следующим образом:

https://maps.googleapis.com/maps/api/place/textsearch/output?parameters

где output может принимать одно из следующих значений:

  • json (рекомендуется) – задает вывод в формате JavaScript Object Notation (JSON);
  • xml – задает вывод в формате XML.

Чтобы инициировать поисковый запрос, необходимо указать определенные параметры. Все параметры разделяются амперсандами (&) в соответствии со стандартом URL-адресов.

Обязательные параметры

  • query – фраза, по которой выполняется поиск, например "ресторан" или "улица Ленина, 123". Служба Google Places возвращает подходящие варианты на основе этой строки. Результаты будут отсортированы по релевантности. Этот параметр не обязателен, если в поисковом запросе также используется параметр type.
  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. Поэтому места, добавленные из вашего приложения, сразу же будут доступны в нем. Дополнительную информацию по созданию проекта API и получению ключа см. в документе Получение ключа для Google Places API Web Service.

Дополнительные параметры

  • location – широта и долгота точки, вокруг которой выполняется поиск мест. Должны быть указаны ее координаты в формате: широта,долгота. Вместе с параметром location обязательно следует использовать параметр radius.
  • radius – расстояние в метрах, в пределах которого должны находиться полученные результаты. Максимальный допустимый радиус составляет 50 000 метров. Места в пределах радиуса будут отображаться выше в результатах поиска, чем более отдаленные, однако на окончательную позицию в рейтинге также может влиять известность.
  • language – код языка, на котором следует по возможности возвращать результаты. Результаты поиска зависят от выбранного языка. Результатам на определенном языке может присваиваться более высокий рейтинг. См. список поддерживаемых языков и их коды. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.
  • minprice и maxprice (необязательно) – ценовой диапазон, ограничивающий результаты поиска. Допускаются значения от 0 (бесплатные) до 4 (самые дорогие) включительно. Точная сумма для каждого из этих значений зависит от региона.
  • opennow – ограничивает результаты поиска только теми организациями (заведениями), которые открыты в момент отправки запроса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются.
  • pagetoken – возвращает следующие 20 результатов для последнего поискового запроса. Если указать параметр pagetoken, поиск будет выполнен с предыдущими параметрами – все параметры, кроме pagetoken, будут игнорироваться.
  • type – ограничивает результаты поиска только теми местами, тип которых соответствует хотя бы одному из указанных. Можно указать только один тип (если указано несколько типов, все типы, кроме первого, игнорируются). См. список поддерживаемых типов.
  • types (объявлен устаревшим) – ограничивает результаты поиска только теми местами, тип которых соответствует хотя бы одному из указанных. Отдельные типы, разделенные вертикальной чертой (type1|type2|etc).
  • zagatselected (объявлен устаревшим) – ограничивает результаты поиска только теми местами, которые рекомендует Zagat. Необходимо просто включить параметр в запрос, не задавая никакого значения. Этот параметр не должен содержать значения true или false. Параметр zagatselected используется в порядке эксперимента и доступен только пользователям Google Places API с лицензией на Premium Plan.

Если задать параметры location и radius, первыми в результатах будут отображаться места из указанной области, однако более отдаленные точки также могут быть включены в ответ.

Примечание для пользователей Google Maps APIs Premium Plan. В запросах необходимо указывать ключ API. В запросы нельзя включать параметры client или signature.

Примеры текстового поиска

Примечание. Для выполнения приведенных в этих примерах запросов в вашем приложении необходимо заменить значение key вашим собственным ключом API.

Пример 1. В следующем примере показан поиск ресторанов рядом с Сиднеем.

https://maps.googleapis.com/maps/api/place/textsearch/xml?query=restaurants+in+Sydney&key=YOUR_API_KEY

Пример 2. В следующем примере показан поиск по неполному адресу. В данном случае это адрес, в котором не указаны город, область и страна.

https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&key=YOUR_API_KEY

Пример 3. В следующем примере показан поиск по тому же неполному адресу, что и в примере 2, с параметрами location и radius для смещения результатов в интересующую область. Сравните результаты примера 2 и примера 3.

https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&location=42.3675294,-71.186966&radius=10000&key=YOUR_API_KEY

Массовый поиск

Служба массового поиска в Google Places API позволяет искать одновременно до 200 мест, но с меньшей детализацией, чем при текстовом поиске или поиске мест поблизости. Эта функция будет полезна для приложений, которые помогают найти скопление интересующих пользователя мест в пределах заданной области.

В ответ на поисковый запрос будет включено до 200 мест со следующими данными по каждому из них.

  • Поле geometry с координатами места.
  • Идентификатор place_id, который можно использовать в запросе данных о месте для получения дополнительной информации. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
  • Поле reference (использовать не рекомендуется). См. уведомление о прекращении использования на этой странице.

Запрос массового поиска мест – это URL-адрес в формате HTTP, который выглядит следующим образом:

https://maps.googleapis.com/maps/api/place/radarsearch/output?parameters

где output может принимать одно из следующих значений:

  • json (рекомендуется) – задает вывод в формате JavaScript Object Notation (JSON);
  • xml – задает вывод в формате XML.

Чтобы инициировать поисковый запрос, необходимо указать определенные параметры. Все параметры разделяются амперсандами (&) в соответствии со стандартом URL-адресов.

Обязательные параметры

  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. Поэтому места, добавленные из вашего приложения, сразу же будут доступны в нем. Дополнительную информацию по созданию проекта API и получению ключа см. в документе Получение ключа для Google Places API Web Service.
  • location – широта и долгота точки, вокруг которой выполняется поиск мест. Должны быть указаны ее координаты в формате: широта,долгота.
  • radius – расстояние в метрах, в пределах которого должны находиться найденные результаты. Максимальный допустимый радиус составляет 50 000 метров.
  • Запрос массового поиска должен включать в себя хотя бы один из параметров: keyword, name или type.

Дополнительные параметры

  • keyword – слово, по которому ведется поиск во всем содержимом, проиндексированном Google для данного места, включая название, тип, адрес, отзывы пользователей и сторонний контент.
  • language – код языка, на котором следует по возможности возвращать результаты. Результаты поиска зависят от выбранного языка. Результатам на определенном языке может присваиваться более высокий рейтинг. См. список поддерживаемых языков и их коды. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.
  • minprice и maxprice (необязательно) – ценовой диапазон, ограничивающий результаты поиска. Допускаются значения от 0 (бесплатные) до 4 (самые дорогие) включительно. Точная сумма для каждого из этих значений зависит от региона.
  • name – термин, который следует сопоставить со всем контентом, индексированным Google для этого местоположения. Эквивалентно keyword. В поле name теперь можно вводить не только названия мест. Значения из этого поля объединяются со значениями поля keyword и передаются в составе той же строки поиска. Мы рекомендуем использовать в поисковых запросах только параметр keyword.
  • opennow – ограничивает результаты поиска только теми организациями (заведениями), которые открыты в момент отправки запроса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются.
  • type – ограничивает результаты поиска только теми местами, тип которых соответствует хотя бы одному из указанных. Можно указать только один тип (если указано несколько типов, все типы, кроме первого, игнорируются). См. список поддерживаемых типов.
  • types (объявлен устаревшим) – ограничивает результаты поиска только теми местами, тип которых соответствует хотя бы одному из указанных. Отдельные типы, разделенные вертикальной чертой (type1|type2|etc).
  • zagatselected (объявлен устаревшим) – ограничивает результаты поиска только теми местами, которые рекомендует Zagat. Необходимо просто включить параметр в запрос, не задавая никакого значения. Этот параметр не должен содержать значения true или false. Параметр zagatselected используется в порядке эксперимента и доступен только пользователям Google Places API с лицензией на Premium Plan.

Примечание для пользователей Google Maps APIs Premium Plan. В запросах необходимо указывать ключ API. В запросы нельзя включать параметры client или signature.

Примеры массового поиска

Примечание. Для выполнения приведенных в этих примерах запросов в вашем приложении необходимо заменить значение key вашим собственным ключом API.

Пример 1. Так будет выглядеть запрос на поиск музеев поблизости от Лондона.

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=51.503186,-0.126446&radius=5000&type=museum&key=YOUR_API_KEY

Пример 2. Запросы можно формулировать точнее, используя сочетание параметров keyword, name и types. Так будет выглядеть запрос на поиск всех кафе в Париже, которые, судя по отзывам пользователей, предлагают вегетарианские блюда.

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=48.859294,2.347589&radius=5000&type=cafe&keyword=vegetarian&key=YOUR_API_KEY

Ответы на поисковые запросы

Ответы на поисковые запросы возвращаются в формате, указанном с помощью флага output в URL-адресе запроса.

В примере ниже показан ответ на запрос поиска мест поблизости. Ответы на текстовые запросы похожи на него, но в них возвращается значение параметра formatted_address, а не свойство vicinity, как при поиске мест поблизости. Ответы на запросы массового поиска содержат ограниченное число полей (см. выше).

JSON
{
   "html_attributions" : [],
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870775,
               "lng" : 151.199025
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "21a0b251c9b8392186142c798263e289fe45b4aa",
         "name" : "Rhythmboat Cruises",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 270,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAF-LjFR1ZV93eawe1cU_3QNMCNmaGkowY7CnOf-kcNmPhNnPEG9W979jOuJJ1sGr75rhD5hqKzjD8vbMbSsRnq_Ni3ZIGfY6hKWmsOf3qHKJInkm4h55lzvLAXJVc-Rr4kI9O1tmIblblUpg2oqoq8RIQRMQJhFsTr5s9haxQ07EQHxoUO0ICubVFGYfJiMUPor1GnIWb5i8",
               "width" : 519
            }
         ],
         "place_id" : "ChIJyWEHuEmuEmsRm9hTkapTCrk",
         "scope" : "GOOGLE",
         "alt_ids" : [
            {
               "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
               "scope" : "APP"
            }
         ],
         "reference" : "CoQBdQAAAFSiijw5-cAV68xdf2O18pKIZ0seJh03u9h9wk_lEdG-cP1dWvp_QGS4SNCBMk_fB06YRsfMrNkINtPez22p5lRIlj5ty_HmcNwcl6GZXbD2RdXsVfLYlQwnZQcnu7ihkjZp_2gk1-fWXql3GQ8-1BEGwgCxG-eaSnIJIBPuIpihEhAY1WYdxPvOWsPnb2-nGb6QGhTipN0lgaLpQTnkcMeAIEvCsSa0Ww",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "Pyrmont Bay Wharf Darling Dr, Sydney"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866891,
               "lng" : 151.200814
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "45a27fd8d56c56dc62afc9b49e1d850440d5c403",
         "name" : "Private Charter Sydney Habour Cruise",
         "photos" : [
            {
               "height" : 426,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAL3n0Zu3U6fseyPl8URGKD49aGB2Wka7CKDZfamoGX2ZTLMBYgTUshjr-MXc0_O2BbvlUAZWtQTBHUVZ-5Sxb1-P-VX2Fx0sZF87q-9vUt19VDwQQmAX_mjQe7UWmU5lJGCOXSgxp2fu1b5VR_PF31RIQTKZLfqm8TA1eynnN4M1XShoU8adzJCcOWK0er14h8SqOIDZctvU",
               "width" : 640
            }
         ],
         "place_id" : "ChIJqwS6fjiuEmsRJAMiOY9MSms",
         "scope" : "GOOGLE",
         "reference" : "CpQBhgAAAFN27qR_t5oSDKPUzjQIeQa3lrRpFTm5alW3ZYbMFm8k10ETbISfK9S1nwcJVfrP-bjra7NSPuhaRulxoonSPQklDyB-xGvcJncq6qDXIUQ3hlI-bx4AxYckAOX74LkupHq7bcaREgrSBE-U6GbA1C3U7I-HnweO4IPtztSEcgW09y03v1hgHzL8xSDElmkQtRIQzLbyBfj3e0FhJzABXjM2QBoUE2EnL-DzWrzpgmMEulUBLGrtu2Y",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "Australia"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870943,
               "lng" : 151.190311
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "30bee58f819b6c47bd24151802f25ecf11df8943",
         "name" : "Bucks Party Cruise",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAA48AX5MsHIMiuipON_Lgh97hPiYDFkxx_vnaZQMOcvcQwYN92o33t5RwjRpOue5R47AjfMltntoz71hto40zqo7vFyxhDuuqhAChKGRQ5mdO5jv5CKWlzi182PICiOb37PiBtiFt7lSLe1SedoyrD-xIQD8xqSOaejWejYHCN4Ye2XBoUT3q2IXJQpMkmffJiBNftv8QSwF4",
               "width" : 800
            }
         ],
         "place_id" : "ChIJLfySpTOuEmsRsc_JfJtljdc",
         "scope" : "GOOGLE",
         "reference" : "CoQBdQAAANQSThnTekt-UokiTiX3oUFT6YDfdQJIG0ljlQnkLfWefcKmjxax0xmUpWjmpWdOsScl9zSyBNImmrTO9AE9DnWTdQ2hY7n-OOU4UgCfX7U0TE1Vf7jyODRISbK-u86TBJij0b2i7oUWq2bGr0cQSj8CV97U5q8SJR3AFDYi3ogqEhCMXjNLR1k8fiXTkG2BxGJmGhTqwE8C4grdjvJ0w5UsAVoOH7v8HQ",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "37 Bank St, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867591,
               "lng" : 151.201196
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "a97f9fb468bcd26b68a23072a55af82d4b325e0d",
         "name" : "Australian Cruise Group",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 242,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAABjeoPQ7NUU3pDitV4Vs0BgP1FLhf_iCgStUZUr4ZuNqQnc5k43jbvjKC2hTGM8SrmdJYyOyxRO3D2yutoJwVC4Vp_dzckkjG35L6LfMm5sjrOr6uyOtr2PNCp1xQylx6vhdcpW8yZjBZCvVsjNajLBIQ-z4ttAMIc8EjEZV7LsoFgRoU6OrqxvKCnkJGb9F16W57iIV4LuM",
               "width" : 200
            }
         ],
         "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
         "scope" : "GOOGLE",
         "reference" : "CoQBeQAAAFvf12y8veSQMdIMmAXQmus1zqkgKQ-O2KEX0Kr47rIRTy6HNsyosVl0CjvEBulIu_cujrSOgICdcxNioFDHtAxXBhqeR-8xXtm52Bp0lVwnO3LzLFY3jeo8WrsyIwNE1kQlGuWA4xklpOknHJuRXSQJVheRlYijOHSgsBQ35mOcEhC5IpbpqCMe82yR136087wZGhSziPEbooYkHLn9e5njOTuBprcfVw",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "32 The Promenade, King Street Wharf 5, Sydney"
      }
   ],
   "status" : "OK"
}

Ответ в формате JSON содержит до четырех корневых элементов:

  • "status" – содержит метаданные по запросу. См. раздел Коды состояния ниже.
  • results – содержит массив мест с информацией о каждом из них. Дополнительную информацию о результатах см. в разделе Результаты поиска. Places API возвращает до 20 результатов типа establishment на каждый запрос. Кроме того, могут быть возвращены результаты типа political, которые служат для определения области запроса.
  • html_attributions – содержит обязательную информацию об источнике данных о месте.
  • next_page_token – содержит токен, с помощью которого можно запросить 20 следующих результатов поиска. Значение next_page_token не возвращается, если изначально получено не более 20 результатов. Всего можно получить не более 60 результатов. Токен next_page_token начинает действовать не сразу, а спустя некоторое непродолжительное время с момента выдачи.

Подробную информацию о синтаксическом анализе ответов в формате JSON см. в разделе Обработка JSON с помощью JavaScript.

XML
<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Rhythmboat Cruises</name>
  <vicinity>Pyrmont Bay Wharf Darling Dr, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8707750</lat>
    <lng>151.1990250</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJyWEHuEmuEmsRm9hTkapTCrk</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CoQBdAAAAChhtoQX_467esHavS0Sj9DrY306W3_uDXKmB2us8Eh7_dX7rDuln18i_uqocF_LmzRptuFr6WZs7aeBSLFq8VFmckxFjsXDaqMdd3gvxi_5dIwPTEugQQYG9oJA-YnYfPBvjGtuoMfNnjyU2GuxGRmJjCO77pEAbsTLq44eBG5jEhAvkKHCGqIzqgC9tdOb1dSqGhRA1hhG4pvILD5OEAq6W8L8sXbkug</reference>
  <id>21a0b251c9b8392186142c798263e289fe45b4aa</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAiRA8ls6lx5LTfLuHJtLYvz73LXIMa5EVsHz2OUjh70LBPBnIEULZ57w076gOuyCeJqP041_v-ek3I5C4IkqW7YgA0EBybwywfIcUXsj5W_qiJR2yaXHXI-FmDM6j1zaS0sJQnNJhe4Bl9W42Jx16phIQRmNOWKGIemKLgzNEPcCnmBoUGgr0gWQBwWd8HAseR-5ie3JYuIM</photo_reference>
   <width>519</width>
   <height>270</height>
  </photo>
 </result>
 <result>
  <name>Private Charter Sydney Habour Cruise</name>
  <vicinity>Australia</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8668910</lat>
    <lng>151.2008140</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJqwS6fjiuEmsRJAMiOY9MSms</place_id>
  <scope>GOOGLE</scope>
  <reference>CpQBhQAAAKGKrbbnAW3_eAypKW9bhAzAuSmaqAogs7MTFxsntDqCzt-gKD9nz-zqNsk0uJsl0yCUYpNYjHz_yzmh3J_4TTxpxIqdaq2uDvfoTYtvm8FkxMAkK3cS7k9t3Ze2aHRWnxlN9hczK2xlc5taDE7xAGOHF5Xe5IlVV1wV66sOrWrlHtGh47lqT9Id86eG2OmlVhIQo4djLtRkceg-zaYjULYEjRoUToVEyOUVCFfZMUs_E7ZLSzjFmcg</reference>
  <id>45a27fd8d56c56dc62afc9b49e1d850440d5c403</id>
  <photo>
   <photo_reference>CnRnAAAAUW97jpK2_C2Lh4jLPVKZlhyS84mqZxvVmWFdc6jdl3XxjzKbYdbJpz0PGW5eFRw6kTKYNZM9QvRf-csFegHILZxLCLJ-6ZnbdEXbVM4kBzOb-rhchJx1KC6LHs_vVWP8bK96569lFYRf7Hn8ylQrlhIQb69_dcZVwqQhREsHW6azWhoU0XMWqZMBBzx-hgpduAaeErOFg8E</photo_reference>
   <width>640</width>
   <height>426</height>
  </photo>
 </result>
 <result>
  <name>Bucks Party Cruise</name>
  <vicinity>37 Bank St, Pyrmont</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8709430</lat>
    <lng>151.1903110</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJLfySpTOuEmsRsc_JfJtljdc</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBdAAAAOMUoYamsekTDxBDVyKZ-E54VQ6HjirVzAZBBwz5gcn5KTfmemmwmOAtLcvRScp1NLQmj-fBYzEO2Gq_cO4Dc12PG0_twzDv9zq3KIyNQVuO-r0n1eQVj8Dlng-n4c1F2hMxufCNVp4-QfjMj81qXJm0invQMUc1xNgZRyiOpLe9EhDLn0KiVWEFKOURYsWrHRouGhR7YMJxYmFs-OXjKyzQKGdQXLrzPw</reference>
  <id>30bee58f819b6c47bd24151802f25ecf11df8943</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAjboYP9Ujxe5SmZFN5AJc42AWtpYFX9wYdqjcTXavXJlfoXdHPC2hErdbHcaeYJBNPV6CzoDc2RLw_w9HofGOhCWHtoAl9b3g8TZZjnZobnAHxoljUdgV8PXyd-pCO-QHKOtiKfIdUmF4HRj2QHj6OhIQhLNpoKNKP8MNjk90M4KGrhoUW2NyBgsWjRpUEoWlt0fD48BhEcQ</photo_reference>
   <width>800</width>
   <height>600</height>
  </photo>
 </result>
 <result>
  <name>Australian Cruise Group</name>
  <vicinity>32 The Promenade, King Street Wharf 5, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675910</lat>
    <lng>151.2011960</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJrTLr-GyuEmsRBfy61i59si0</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBeAAAAJZA0WY2pKnZ6nNnxNd_pSDA2NilDLfGDf7pTt7VssxB5tMYE7400w3HZHRav2unpKRhEp7lrh0yKcVdSfKYIz85k1SExoLGmYD8NIf1dPr8KlkRWOYZUTLGp623r5hAzEGk94mPleF4s50pWqLrhAzwvJb1tGj2ak-2PXQORkeTEhAfTj6tMFo_tRWZYOnYCxiVGhQA3n-KV7AW5MvJlGaIDHuLyyEBBA</reference>
  <id>a97f9fb468bcd26b68a23072a55af82d4b325e0d</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAhTkpwozMoZx_NXMkIrKdcEGe46BmPy3GPCfS-gkCK5PlR8rFDY9DtD_7wFYAIdhVoZz3I9QguRNbil5y37jTU-03GJ_LqVw_avSxFkT0g2kU0K5z2VYnAsgNsrbsK_EVglhg5PrDybC1tAVKCXSGsRIQOcdlAVnC1Qc46YLWjlqdyxoUL5JGZgczfo1jxLxhDeGs8OvBQCk</photo_reference>
   <width>200</width>
   <height>242</height>
  </photo>
 </result>
</PlaceSearchResponse>

Ответ в формате XML содержит один элемент <PlaceSearchResponse> и до четырех элементов верхнего уровня:

  • <status> – содержит метаданные по запросу. См. раздел Коды состояния ниже.
  • <result> – содержит информацию об одной организации. Таких элементов в ответе может быть несколько или может не быть вовсе. Дополнительную информацию о результатах см. в разделе Результаты поиска мест поблизости. Places API возвращает до 20 результатов типа establishment на каждый запрос. Кроме того, могут быть возвращены результаты типа (<type>) political или улицы, которые служат для определения области запроса.
  • next_page_token – содержит токен, с помощью которого можно запросить 20 следующих результатов поиска. Значение next_page_token не возвращается, если изначально получено не более 20 результатов. Всего можно получить не более 60 результатов. Токен next_page_token активируется через 2 секунды после выдачи.
  • html_attributions – содержит обязательную информацию об источнике данных о месте.

Коды состояния

Поле status в объекте ответа на запрос содержит данные о состоянии запроса и может содержать отладочную информацию, позволяющую выяснить причину сбоя. В поле status могут быть указаны следующие значения.

  • OK – ошибок нет, место обнаружено, и получен хотя бы один результат.
  • ZERO_RESULTS – поиск выполнен, результатов не найдено. Такое может произойти, если для поиска установлены координаты latlng отдаленного места.
  • OVER_QUERY_LIMIT – превышена квота.
  • REQUEST_DENIED – означает, что запрос отклонен, как правило, из-за отсутствия или неверного значения параметра key.
  • INVALID_REQUEST – как правило, отсутствует обязательный параметр запроса (location или radius).

Сообщения об ошибках

Если служба адресов Google возвращает код состояния, отличный от OK, в данных ответа может быть дополнительное поле error_message. Это поле содержит более подробную информацию о причинах указанного кода состояния.

Результаты поиска

Результаты в формате JSON, полученные при выполнении поиска, помещаются в массив results. Даже если служба не находит результатов (например, если в параметре location указано отдаленное место), все равно возвращается пустой массив results. XML-ответы могут содержать любое, в том числе нулевое, число элементов <result>.

Каждый элемент массива results содержит один результат для указанной области (location и radius). Результаты отсортированы по известности.

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

"html_attributions" : [
      "Listings by \u003ca href=\"http://www.example.com/\"\u003eExample Company\u003c/a\u003e"
],
Пример информации об источнике данных в формате XML:
<html_attribution>Listings by <a href="http://www.example.com/">Example Company</a></html_attribution>

Каждый результат в массиве results может содержать следующие поля:

  • icon – содержит URL-адрес рекомендуемого значка, которым можно обозначить этот результат на карте.
  • id – содержит уникальный постоянный идентификатор места. Этот идентификатор не позволяет получить информацию о месте, но гарантированно будет действителен для всех сеансов. С его помощью можно объединять данные о месте и идентифицировать его в разных поисковых запросах. Примечание. Вместо параметра id рекомендуется использовать place_id. См. уведомление о прекращении использования на этой странице.
  • geometry – содержит геометрические данные о результате, которые обычно состоят из location (геокода места) и дополнительного элемента viewport, определяющего размер области на экране.
  • name – содержит удобочитаемое название результата. Для результатов в категории establishment обычно используется название компании.
  • opening_hours может содержать следующую информацию:
    • open_now – логическое значение, указывающее, работает ли организация в настоящий момент.
  • photos[] – массив объектов photo, каждый из которых содержит ссылку на изображение. В результатах поиска мест возвращается не больше одного объекта photo. Отправив запрос данных о месте, можно получить до 10 фотоснимков. Подробную информацию о фотографиях места и о том, как их использовать в своем приложении, см. в документе Фотографии мест. Объекты photo обладают следующими свойствами.
    • photo_reference – строка с идентификатором фотографии, которая возвращается в ответ на запрос изображения.
    • height – максимальная высота изображения.
    • width – максимальная ширина изображения.
    • html_attributions[] – информация об авторстве. Хотя это поле может быть пустым, оно всегда включается в ответ.
  • place_id – уникальный текстовый идентификатор места. Чтобы извлечь информацию о месте, передайте этот идентификатор в поле placeId запроса Places API. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
  • scope – указывает область действия идентификатора place_id. Возможные значения:
    • APP – идентификатор места распознается только вашим приложением. Это связано с тем, что место было добавлено вашим приложением и еще не прошло проверку.
    • GOOGLE – идентификатор места доступен в других приложениях и Google Maps.
    Примечание. Поле scope включается только в результаты запросов поиска мест поблизости и результаты запросов данных о месте. Для получения мест, доступных в рамках приложения, необходимо использовать запросы поиска мест поблизости и запросы данных о месте. Если в ответе нет поля scope, можно с уверенностью предположить, что областью действия является GOOGLE.
  • alt_ids – массив альтернативных идентификаторов места. С каждым альтернативным идентификатором связана область действия. Примечание. Этот массив может отсутствовать или быть пустым. Если массив присутствует, он содержит следующие поля.
    • place_id – наиболее вероятная причина наличия альтернативного идентификатора состоит в том, что ваше приложение добавило место и получило его идентификатор в рамках приложения, а после прохождения проверки место получило идентификатор в рамках Google.
    • scope – область действия альтернативного идентификатора места всегда имеет значение APP, указывая на то, что альтернативный идентификатор места распознается только вашим приложением.
    Например, пусть ваше приложение добавило место и получило идентификатор place_id нового места, содержащий значение AAA. Затем место прошло проверку и получило идентификатор place_id в рамках Google, имеющий значение BBB. С этого момента информация о данном месте содержит следующие поля.
        "results" : [
          {
            "place_id" : "BBB",
            "scope" : "GOOGLE",
            "alt_ids" : [
              {
                "place_id" : "AAA",
                "scope" : "APP",
              }
            ],
          }
        ]
        
  • price_level – уровень цен для этого места, от 0 до 4. Точная величина для каждого из этих значений зависит от региона. Уровни цен ранжируются следующим образом:
    • 0 – бесплатные;
    • 1 – недорогие;
    • 2 – средние по цене;
    • 3 – дорогие;
    • 4 – очень дорогие.
  • rating – содержит рейтинг места на основе сводных отзывов пользователей (от 1,0 до 5,0).
  • reference – содержит уникальный токен, который можно использовать для получения дополнительной информации в запросе данных о месте. Хотя токен однозначно определяет место, обратное утверждение неверно. Место может иметь несколько токенов с действительными ссылками. Мы не гарантируем, что в результате выполнения различных поисковых запросов для одного и того же места всегда будет возвращен один и тот же токен. Примечание. Вместо параметра reference рекомендуется использовать place_id. См. уведомление о прекращении использования на этой странице.
  • types[] – массив типов свойств, описывающих данный результат. См. список поддерживаемых типов. XML-ответы содержат несколько элементов <type>, если результату присвоено несколько типов.
  • vicinity – содержит название близлежащего объекта. Как правило, это улица или район, указанные в полученных результатах. Свойство vicinity возвращается только при поиске мест поблизости.
  • formatted_address – строка, содержащая удобочитаемый адрес этого места. Часто это почтовый адрес. Свойство formatted_address возвращается только при текстовом поиске.
  • permanently_closed – логический флаг, указывающий на то, что организация закрыта всегда (значение true). Если же организация закрыта не всегда, в полученном ответе этот флаг отсутствует.

Премиум-данные

В дополнение к указанным выше полям пользователи Google Places API с лицензией на Premium Plan могут получать следующие данные. Они будут возвращаться в виде дочерних полей верхнего уровня по отношению к полю result.

  • aspects – содержит один объект AspectRating с основной оценкой места. Объекты AspectRating обладают следующими свойствами:
    • type – оцениваемый критерий. Поддерживаются следующие типы: привлекательность, атмосфера, интерьер, удобства, кухня, общее впечатление, качество и сервис.
    • rating – сводная оценка по определенному критерию, от 0 до 30. Обратите внимание, что сводная оценка составляет от 0 до 30 баллов, тогда как оценки в отзывах выставляются в диапазоне от 0 до 3.
  • zagat_selected – указывает, что это место находится в каталоге службы Zagat. Этим знаком Zagat отмечает только те места, которые известны своим неизменно высоким качеством обслуживания, уникальной атмосферой или специализацией.
Дополнительную информацию см. в документе Премиум-данные.

Отображение дополнительных результатов

По умолчанию на поисковый запрос мест поблизости или текстовый запросы возвращается до 20 результатов типа establishment. Всего их количество может доходить до 60, и в таком случае они разбиваются на три страницы. Если поисковый запрос возвращает более 20 результатов, в ответе содержится дополнительное значение – next_page_token. Передайте значение next_page_token в параметр pagetoken, чтобы отобразить следующую страницу результатов в новом запросе. Если значение свойства next_page_token равно нулю или отсутствует, значит, все результаты уже показаны. Токен next_page_token начинает действовать не сразу, а спустя некоторое непродолжительное время с момента выдачи. Если запросить следующую страницу раньше, будет возвращен ответ INVALID_REQUEST. В этом случае для перехода на следующую страницу результатов достаточно повторить запрос с тем же значением next_page_token.

Ниже показан пример запроса на поиск ресторанов, расположенных рядом с Дарлинг-харбор в г. Сидней, Австралия. Результаты сортируются по расстоянию. Ответ содержит свойство next_page_token.

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&rankby=distance&types=food&key=YOUR_API_KEY
{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867217,
               "lng" : 151.195939
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png",
         "id" : "7eaf747a3f6dc078868cd65efc8d3bc62fff77d7",
         "name" : "Biaggio Cafe - Pyrmont",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAmWmj0BqA0Jorm1_vjAvx1n6c7ZNBxyY-U9x99-oNyOxvMjDlo2npJzyIq7c3EK1YyoNXdMFDcRPzwLJtBzXAwCUFDGo_RtLRGBPJTA2CoerPdC5yvT2SjfDwH4bFf5MrznB0_YWa4Y2Qo7ABtAxgeBIQv46sGBwVNJQDI36Wd3PFYBoUTlVXa0wn-zRITjGp0zLEBh8oIBE",
               "width" : 900
            }
         ],
         "place_id" : "ChIJIfBAsjeuEmsRdgu9Pl1Ps48",
         "scope" : "GOOGLE",
         "price_level" : 1,
         "rating" : 3.4,
         "reference" : "CoQBeAAAAGu0wNJjuZ40DMrRe3mpn7fhlfIK1mf_ce5hgkhfM79u-lqy0G2mnmcueTq2JGWu9wsgS1ctZDHTY_pcqFFJyQNV2P-kdhoRIeYRHeDfbWtIwr3RgFf2zzFBXHgNjSq-PSzX_OU6OT2_3dzdhhpV-bPezomtrarW4DsGl9uh773yEhDJT6R3V8Fyvl_xeE761DTCGhT1jJ3floFI5_c-bHgGLVwH1g-cbQ",
         "types" : [ "cafe", "bar", "restaurant", "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866786,
               "lng" : 151.195633
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
         "id" : "3ef986cd56bb3408bc1cf394f3dad9657c1d30f6",
         "name" : "Doltone House",
         "photos" : [
            {
               "height" : 1260,
               "html_attributions" : [ "From a Google User" ],
               "photo_reference" : "CnRwAAAAeM-aLqAm573T44qnNe8bGMkr_BOh1MOVQaA9CCggqtTwuGD1rjsviMyueX_G4-mabgH41Vpr8L27sh-VfZZ8TNCI4FyBiGk0P4fPxjb5Z1LrBZScYzM1glRxR-YjeHd2PWVEqB9cKZB349QqQveJLRIQYKq2PNlOM0toJocR5b_oYRoUYIipdBjMfdUyJN4MZUmhCsTMQwg",
               "width" : 1890
            }
         ],
         "place_id" : "ChIJ5xQ7szeuEmsRs6Kj7YFZE9k",
         "scope" : "GOOGLE",
         "reference" : "CnRvAAAA22k1PAGyDxAgHZk6ErHh_h_mLUK_8XNFLvixPJHXRbCzg-gw1ZxdqUwA_8EseDuEZKolBs82orIQH4m6-afDZV9VcpggokHD9x7HdMi9TnJDmGb9Bdh8f-Od4DK0fASNBL7Me3CsAWkUMWhlNQNYExIQ05W7VbxDTQe2Kh9TiL840hoUZfiO0q2HgDHSUyRdvTQx5Rs2SBU",
         "types" : [ "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "aspects" : [
            {
               "rating" : 23,
               "type" : "overall"
            }
         ],
      ...
   ],
   "status" : "OK"
}

Чтобы увидеть следующий список результатов, можно создать новый запрос, передав значение next_page_token в параметр pagetoken. Например:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY

Если указать pagetoken, другие параметры игнорируются. Поиск выполняется с теми же параметрами, что и раньше, просто выводится следующая страница результатов. Подобный запрос можно отправлять только дважды после исходного запроса. Страницы результатов можно выводить только по очереди. В ответ на запрос нельзя выводить больше одной страницы результатов. Обратите внимание, что каждая загрузка новой страницы результатов учитывается в квоте ограничений на использование как отдельный запрос.

Параметр sensor

Ранее запросы Google Places API обязательно должны были содержать параметр sensor, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.

Оставить отзыв о...

Текущей странице
location_on
Google Places API Web Service