Все готово!

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

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

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

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

Данные о месте

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

Запросы данных о месте

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

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

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

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

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

  • key (обязательный параметр) – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. Поэтому места, добавленные из вашего приложения, сразу же будут доступны в нем. Дополнительную информацию см. в документе Получение ключа.
  • Введите placeid или reference, (необходимо указать один из этих параметров, но не оба сразу):
Дополнительные параметры
  • extensions (необязательный параметр) – указывает, должен ли ответ на запрос данных о месте включать дополнительные поля. В дополнительных полях можно запрашивать премиум-данные, на которые нужна дополнительная лицензия, либо значения, которые запрашиваются редко. Расширенные данные (Extensions) предоставляются пока в экспериментальном режиме. Для параметра Extensions поддерживаются следующие значения:
    • review_summary – краткая и исчерпывающая рецензия, подготовленная под руководством редакторов Google.
  • language (необязательный параметр) – код языка, на котором следует, по возможности, возвращать результаты. Некоторые поля доступны не на всех языках. См. список поддерживаемых языков и их коды. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.

В следующем примере запрашиваются сведения о месте по параметру placeid:

https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4&key=YOUR_API_KEY

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

В следующем примере используется устаревший параметр reference:

https://maps.googleapis.com/maps/api/place/details/json?reference=CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g&key=YOUR_API_KEY

Ответы на запросы данных о месте

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


JSON
{
   "html_attributions" : [],
   "result" : {
      "address_components" : [
         {
            "long_name" : "48",
            "short_name" : "48",
            "types" : [ "street_number" ]
         },
         {
            "long_name" : "Pirrama Road",
            "short_name" : "Pirrama Road",
            "types" : [ "route" ]
         },
         {
            "long_name" : "Pyrmont",
            "short_name" : "Pyrmont",
            "types" : [ "locality", "political" ]
         },
         {
            "long_name" : "NSW",
            "short_name" : "NSW",
            "types" : [ "administrative_area_level_1", "political" ]
         },
         {
            "long_name" : "AU",
            "short_name" : "AU",
            "types" : [ "country", "political" ]
         },
         {
            "long_name" : "2009",
            "short_name" : "2009",
            "types" : [ "postal_code" ]
         }
      ],
      "formatted_address" : "48 Pirrama Road, Pyrmont NSW, Australia",
      "formatted_phone_number" : "(02) 9374 4000",
      "geometry" : {
         "location" : {
           "lat" : -33.8669710,
           "lng" : 151.1958750
         },
         "viewport" : {
            "northeast" : {
               "lat" : -33.8665053,
               "lng" : 151.1960371
            },
            "southwest" : {
               "lat" : -33.8669293,
               "lng" : 151.1952183
            }
         }
      },
      "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "id" : "4f89212bf76dde31f092cfc14d7506555d85b5c7",
      "international_phone_number" : "+61 2 9374 4000",
      "name" : "Google Sydney",
      "place_id" : "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "scope" : "GOOGLE",
      "alt_ids" : [
         {
            "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
            "scope" : "APP"
         }
      ],
      "rating" : 4.70,
      "reference" : "CnRsAAAA98C4wD-VFvzGq-KHVEFhlHuy1TD1W6UYZw7KjuvfVsKMRZkbCVBVDxXFOOCM108n9PuJMJxeAxix3WB6B16c1p2bY1ZQyOrcu1d9247xQhUmPgYjN37JMo5QBsWipTsnoIZA9yAzA-0pnxFM6yAcDhIQbU0z05f3xD3m9NQnhEDjvBoUw-BdcocVpXzKFcnMXUpf-nkyF1w",
      "reviews" : [
         {
            "aspects" : [
               {
                  "rating" : 3,
                  "type" : "quality"
               }
            ],
            "author_name" : "Simon Bengtsson",
            "author_url" : "https://plus.google.com/104675092887960962573",
            "language" : "en",
            "rating" : 5,
            "text" : "Just went inside to have a look at Google. Amazing.",
            "time" : 1338440552869
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Felix Rauch Valenti",
            "author_url" : "https://plus.google.com/103291556674373289857",
            "language" : "en",
            "rating" : 5,
            "text" : "Best place to work :-)",
            "time" : 1338411244325
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Chris",
            "language" : "en",
            "rating" : 5,
            "text" : "Great place to work, always lots of free food!",
            "time" : 1330467089039
         }
      ],
      "types" : [ "establishment" ],
      "url" : "http://maps.google.com/maps/place?cid=10281119596374313554",
      "vicinity" : "48 Pirrama Road, Pyrmont",
      "website" : "http://www.google.com.au/"
   },
   "status" : "OK"
}
      
XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceDetailsResponse>
 <status>OK</status>
 <result>
  <name>Google Sydney</name>
  <vicinity>48 Pirrama Road, Pyrmont</vicinity>
  <type>establishment</type>
  <formatted_phone_number>(02) 9374 4000</formatted_phone_number>
  <formatted_address>48 Pirrama Road, Pyrmont NSW, Australia</formatted_address>
  <address_component>
   <long_name>48</long_name>
   <short_name>48</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Pirrama Road</long_name>
   <short_name>Pirrama Road</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Pyrmont</long_name>
   <short_name>Pyrmont</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>NSW</long_name>
   <short_name>NSW</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>AU</long_name>
   <short_name>AU</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>2009</long_name>
   <short_name>2009</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
     <lat>-33.8669710</lat>
     <lng>151.1958750</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8669293</lat>
     <lng>151.1952183</lng>
    </southwest>
    <northeast>
     <lat>-33.8665053</lat>
     <lng>151.1960371</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.7</rating>
  <url>http://maps.google.com/maps/place?cid=10281119596374313554</url>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png</icon>
  <place_id>ChIJN1t_tDeuEmsRUsoyG83frY4</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CnRsAAAAoGXc0eAcQOoO1A7sU58repRnghwM5q7UtsZFhVtjYtfKN_LFAPhdhBfUAU8m0EzeSyP0cDBi7kazZwNjlIMUqktqIanMiymuRDS8c539M6KCJNUMkjw22WXxtl3QoR25fIf-7YJnpza6bMIuFZ1CKBIQuBsbXu8xkbUNofECCkdvmxoU5k3Lpbr8XNCbofIKtsZxj8GloGA</reference>
  <id>4f89212bf76dde31f092cfc14d7506555d85b5c7</id>
  <international_phone_number>+61 2 9374 4000</international_phone_number>
  <website>http://www.google.com.au/</website>
  <review>
   <time>1338440552869</time>
   <text>Just went inside to have a look at Google. Amazing.</text>
   <author_name>Simon Bengtsson</author_name>
   <author_url>https://plus.google.com/104675092887960962573</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1338411244325</time>
   <text>Best place to work :-)</text>
   <author_name>Felix Rauch Valenti</author_name>
   <author_url>https://plus.google.com/103291556674373289857</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1330467089039</time>
   <text>Great place to work, always lots of free food!</text>
   <author_name>Chris</author_name>
   <author_url>https://maps.google.com/maps/user?uid=211457841236072500285</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
 </result>
</PlaceDetailsResponse>

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

  • "status" – содержит метаданные по запросу. См. раздел Коды состояния ниже.
  • "result" – содержит подробную информацию о запрашиваемом месте. Информацию об этих результатах см. в разделе Результаты запросов данных о месте.
  • "html_attributions" – содержит обязательную информацию об источнике данных о месте.

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

Ответ в формате XML состоит из отдельного элемента <PlaceDetailsResponse> и трех следующих элементов верхнего уровня.

  • <status> – содержит метаданные по запросу. См. раздел Коды состояния.
  • Один элемент <result> содержит подробные данные об отдельной организации. Информацию об этих результатах см. в разделе Результаты запросов данных о месте.
  • <html_attributions> – содержит обязательную информацию об источнике данных о месте.

Рекомендуемые шаблоны для обработки вывода приведены в разделе Синтаксический анализ XML с помощью XPath.

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

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

  • OK – ошибок нет, место обнаружено, и получен хотя бы один результат.
  • UNKNOWN_ERROR – ошибка на стороне сервера. Повторная попытка может быть успешной.
  • ZERO_RESULTS – ссылка более не указывает на корректный результат. Такое может произойти, если организация прекратила свое существование.
  • OVER_QUERY_LIMIT – превышена квота.
  • REQUEST_DENIED – означает, что запрос отклонен, как правило, из-за отсутствия или неверного значения параметра key.
  • INVALID_REQUEST – обычно означает отсутствие запроса (reference).
  • NOT_FOUND – указанное место отсутствует в базе данных Google Places.

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

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

Результаты запросов данных о месте

Результаты, получаемые при запросе подробных данных из Google Places, помещаются в единый массив result. Каждый результат может содержать следующие поля.

  • address_components[] – массив составляющих адреса. Например, "Россия, Москва, Балчуг, 7" содержит отдельные компоненты адреса: "7" (номер дома), "Балчуг" (улица), "Москва" (город) и "Россия" (страна). Каждый address_component, как правило, содержит следующие атрибуты.
    • types[] – массив, указывающий тип компонента адреса.
    • long_name – полное текстовое описание или название компонента адреса.
    • short_name – сокращенное текстовое название компонента адреса (если есть). Например, компонент адреса для штата Аляска может содержать значение параметра long_name "Alaska" и short_name "AK" (двухбуквенная почтовая аббревиатура).
  • formatted_address – строка, содержащая удобочитаемый адрес этого места. Часто это почтовый адрес, который может выглядеть по-разному в зависимости от страны. Адрес обычно состоит из одного или нескольких полей address_component.
  • formatted_phone_number – содержит номер телефона в местном формате. Например, formatted_phone_number для офиса Google в Москве выглядит так: 8 495 644-14-00.
  • geometry – содержит следующую информацию:
    • location – геокодированные значения широты и долготы места.
    • viewport – содержит предпочитаемую область просмотра при отображении этого места на карте в виде параметра LatLngBounds, если он известен.
  • icon – содержит URL-адрес рекомендуемого значка, которым можно обозначить этот результат на карте.
  • id – содержит уникальный постоянный идентификатор места. Этот идентификатор не позволяет получить информацию о месте, но с его помощью можно объединять данные об этом месте и распознавать его в разных поисковых запросах. Поскольку идентификаторы могут со временем изменяться, рекомендуется сравнивать сохраненный идентификатор места с идентификатором, возвращенным в последующих ответах на запросы данных о том же объекте, и при необходимости обновлять его. Примечание. Вместо параметра id рекомендуется использовать place_id. См. уведомление о прекращении использования на этой странице.
  • international_phone_number – содержит номер телефона места в международном формате. В международном формате указывается код страны и знак плюс (+) перед номером. Например, свойство international_phone_number для офиса Google в Москве выглядит так: +7 495 644 1400.
  • name – содержит удобочитаемое название результата. Обычно для результатов в категории establishment выводится название компании.
  • opening_hours – содержит следующую информацию:
    • open_now – логическое значение, указывающее, работает ли организация в настоящий момент.
    • periods[] – массив с графиком работы на неделю в хронологическом порядке, начиная с воскресенья. Каждый период содержит следующую информацию.
      • Параметр open – включает пару объектов day и time, обозначающих время открытия.
        • day – число от 0 до 6, соответствующее дням недели, начиная с воскресенья. Например, 2 обозначает вторник.
        • time – время в 24-часовом формате (ччмм) со значениями в диапазоне 0000–2359. Значение time указывается по местному часовому поясу.
      • Параметр close – включает пару объектов day и time, обозначающих время закрытия. Примечание. Если место открыто постоянно, в ответе отсутствует раздел close. Можно уверенно считать, что место открыто постоянно, если период open содержит параметр day, имеющий значение 0, параметр time, имеющий значение 0000, и при этом отсутствует параметр close.
    • weekday_text – массив с семью строками, обозначающими время работы по дням недели в соответствующем формате. Если при запросе данных о месте был указан параметр language, время работы будет выведено на указанном языке в соответствующем ему формате. Порядок элементов в этом массиве зависит именно от параметра language. В некоторых странах неделя начинается с понедельника, а в других началом недели считается воскресенье.
  • permanently_closed – логический флаг, указывающий на то, что организация закрыта всегда (значение true). Если же организация закрыта не всегда, в полученном ответе этот флаг отсутствует.
  • photos[] – массив объектов photo, каждый из которых содержит ссылку на изображение. Отправив запрос данных о месте, можно получить до 10 фотоснимков. Подробную информацию о фотографиях места и о том, как их использовать в своем приложении, см. в документе Фотографии мест. Объекты photo обладают следующими свойствами.
    • photo_reference – строка с идентификатором фотографии, которая возвращается в ответ на запрос изображения.
    • height – максимальная высота изображения.
    • width – максимальная ширина изображения.
    • html_attributions[] – информация об авторстве. Хотя это поле может быть пустым, оно всегда включается в ответ.
  • place_id – уникальный текстовый идентификатор места. Чтобы извлечь информацию о месте, передайте этот идентификатор в поле placeId запроса Places API. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
  • scope – указывает область действия идентификатора place_id. Возможные значения:
    • APP – идентификатор места распознается только вашим приложением. Это связано с тем, что место было добавлено вашим приложением и еще не прошло проверку.
    • GOOGLE – идентификатор места доступен в других приложениях и Google Maps.
  • 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, используемого в запросе данных. Сохраненные ссылки на места рекомендуется регулярно обновлять. Хотя токен однозначно определяет место, обратное утверждение неверно. Место может иметь несколько токенов с действительными ссылками. Примечание. Вместо параметра reference рекомендуется использовать place_id. См. уведомление о прекращении использования на этой странице.
  • reviews[] – массив в формате JSON, содержащий до пяти отзывов. Если при запросе данных о месте был указан параметр language, в первую очередь будут показаны места с отзывами на указанном языке. Каждый отзыв состоит из нескольких компонентов:
    • aspects содержит коллекцию объектов AspectRating с оценками организации по определенным критериям. Первый объект в коллекции считается основным критерием. Объекты AspectRating обладают следующими свойствами:
      • type – оцениваемый критерий. Поддерживаются следующие типы: привлекательность, атмосфера, интерьер, удобства, кухня, общее впечатление, качество и сервис.
      • rating – пользовательская оценка по этому критерию, от 0 до 3.
    • author_name – имя пользователя, написавшего отзыв. Для анонимных рецензий в качестве автора будет указан "A Google user".
    • author_url – URL-адрес профиля пользователя в Google+ (если есть).
    • language – код IETF, указывающий язык, на котором написан отзыв. Это поле содержит только основной тег языка и не содержит дополнительный тег страны или региона. Например, все отзывы на английском языке имеют тег "en", но не "en-AU", "en-UK" и т. д.
    • rating – общая пользовательская оценка этого места. Она представляет собой целое число от 1 до 5.
    • text – текст отзыва пользователя. При рецензировании местоположения с помощью Google Places текстовые отзывы не являются обязательными, поэтому это поле может быть пустым. Обратите внимание, что это поле может содержать простую разметку HTML. Например, отзыв о предприятии может содержать символ амперсанда &amp;.
    • time – время размещения отзыва, измеренное в секундах с полуночи 1 января 1970 г. по UTC.
  • types[] – массив типов свойств, описывающих данный результат. См. список поддерживаемых типов. XML-ответы содержат несколько элементов <type>, если результату присвоено несколько типов.
  • url – содержит URL-адрес официальной страницы этого места в Google. Это страница Google, содержащая всю имеющуюся информацию об этом месте. Приложения должны показывать пользователю встроенную страницу места или ссылку на нее на любом экране с подробным описанием этого места.
  • utc_offset – разница между временем текущего часового пояса и UTC (в минутах). Например, для объектов в г. Сидней (Австралия) при переходе на летнее время оно составит 660 (+11 часов от UTC), а для мест в Калифорнии без перехода на летнее время будет равным -480 (-8 часов от UTC).
  • vicinity – содержит упрощенный адрес места, включая район, улицу и номер дома, но без указания области, почтового индекса или страны. Например, для офиса Google в Москве значением параметра vicinity будет Балчуг 7, ЦАО.
  • website – содержит перечень официальных сайтов, связанных с этим местом, таких как адрес домашней страницы компании.

Не для всех мест могут быть даны оценки по каждому из критериев. Если отзывов слишком мало, в ответе на запрос данных будет возвращена старая оценка по шкале от 1,0 до 5,0. Если оценок нет, параметр будет отсутствовать.

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

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

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

В следующем примере показано отображение полей aspects и review_summary в теле ответа:

"aspects" : [
   {
      "rating" : 24,
      "type" : "food"
   },
   {
      "rating" : 21,
      "type" : "decor"
   },
   {
      "rating" : 24,
      "type" : "service"
   }
],

...

"review_summary" : "For a meal that's a \"leisurely celebration\",
Mountain View \"foodies\" head to this \"lovely\" old Victorian house, where
\"artful\", \"high-end\" New French tasting dinners that \"look great and taste
even better\" are enhanced by sommelier-selected wines and service that
\"anticipates your every need\"; a garden out back supplies some ingredients,
while four dining areas provide \"lovely decor and ambiance\"; P.S. an
abbreviated tasting menu is also available."

Параметр sensor

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

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

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