Библиотека Places

Выберите платформу: Android iOS JavaScript Веб-сервисы

Примечание. Теперь действуют ограничения на ключи API.

Примечание: библиотеки на стороне сервера

Обзор

С помощью функций в библиотеке Places в Maps JavaScript API можно добавить в приложение возможность поиска мест (которыми в данном API считаются учреждения, географические местоположения и объекты инфраструктуры), расположенных в определенной области, например на участке карты или около фиксированной точки.

Places API включает функцию автозаполнения, которая отображает названия мест при вводе текста в поле поиска Google Карт. Она срабатывает, когда пользователь начинает вводить адрес. Подробную информацию можно найти в документации по функции автозаполнения.

Начало работы

Если вы не знакомы с Maps JavaScript API или JavaScript, рекомендуем сначала изучить JavaScript и получить ключ API.

Включите API

Прежде чем использовать библиотеку Places в Maps JavaScript API, убедитесь, что в Google Cloud Console включен Places API в том же проекте, который вы установили для Maps JavaScript API.

Чтобы посмотреть список включенных API:

Войдите в Google Cloud Console.
Нажмите кнопку Select a project (Выбрать проект), затем выберите тот же проект, который вы используете для Maps JavaScript API, и нажмите Open (Открыть).
В списке API на панели управления поищите Places API.
Если в списке есть Places API, то он уже включен. Если API в списке нет, включите его:
1. Вверху страницы выберите Enable APIS and Services (Включить API и сервисы), чтобы появилась вкладка Library (Библиотека). Вы также можете выбрать в меню слева пункт Library (Библиотека).
2. Введите поисковый запрос Places API, а затем выберите API из списка результатов.
3. Нажмите Enable (Включить). Когда процесс завершится, Places API появится в списке API на панели управления.

Загрузка библиотеки

Сервис Places – самодостаточная библиотека, используемая отдельно от основного кода Maps JavaScript API. Для работы с этой библиотекой необходимо сначала загрузить ее с помощью параметра libraries в URL начальной загрузки Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Подробные сведения приведены в статье Обзор библиотек.

Как добавить Places API в список ограничений API ключа

Применение ограничений API к ключам ограничивает использование ключа API одним или несколькими API или SDK. Запросы к API или SDK, связанные с ключом API, при этом будут обрабатываться, а запросы, не связанные с ключом, – нет. Чтобы ограничить использование ключа API только библиотекой Places в Maps JavaScript API, выполните следующие действия:

Войдите в Google Cloud Console.
Выберите в раскрывающемся меню проект, содержащий нужный ключ API.
Нажмите кнопку меню и выберите Google Maps Platform > Credentials (Платформа Google Карт > Учетные данные).
На странице Credentials (Учетные данные) нажмите на название нужного ключа API.
Задайте ограничения на странице Restrict and rename API key (Ограничение и переименование ключа API):
- Ограничения для API
Нажмите Save (Сохранить).

Правила и ограничения на использование

Квоты

Для библиотеки Places в JavaScript API используется квота совместно с Places API, как описано в документации по лимитам на использование Places API.

Правила

Использовать библиотеку из Maps JavaScript API необходимо в соответствии с правилами, описанными для Places API.

Поиск мест

С помощью сервиса Places можно выполнять четыре вида поиска:

Find Place from Query возвращает место, соответствующее текстовому запросу, например название или адрес места.
Find Place from Phone возвращает место, соответствующее указанному номеру телефона.
Nearby Search возвращает список близлежащих мест на основе местоположения пользователя.
Text Search возвращает список близлежащих мест на основе поисковой строки, например "Пицца".
Запросы Place Details возвращают подробную информацию, включая отзывы пользователей, о конкретном месте.

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

Запросы Find Place

С помощью запроса Find Place можно искать место по тексту или номеру телефона. Есть два типа таких запросов:

Find Place from Query
Find Place from Phone Number

Find Place from Query

Запрос Find Place from Query принимает текстовое значение и возвращает место. Ввести можно любые данные о месте, например название компании или адрес. Чтобы сделать запрос Find Place from Query, вызовите метод findPlaceFromQuery() сервиса PlacesService, который принимает следующие параметры:

query (обязательный параметр) – строка для текстового поиска, например, "ресторан" или "улица Центральная, 123". Нужно указать название места, его адрес или категорию учреждения. Если ввести данные другого типа, вы можете получить неправильные результаты или возникнет ошибка. На основе этой строки Places API возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.
fields (обязательный параметр) – одно или несколько полей, где указаны типы данных Place, которые нужно вернуть.
locationBias (необязательный параметр) – координаты, определяющие область поиска. Может принимать следующие значения:
- набор координат широты и долготы, указанный в виде LatLngLiteral или объекта LatLng;
- прямоугольные границы (две пары координат широты и долготы или объект LatLngBounds);
- окружность заданного радиуса (в метрах) с центром в координатах широты и долготы.

Кроме того, для обработки объекта результатов и ответа google.maps.places.PlacesServiceStatus нужно передать метод обратного вызова методу findPlaceFromQuery().

В примере ниже показан вызов метода findPlaceFromQuery() для поиска "Museum of Contemporary Art Australia" с указанием значений полей name и geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}

Посмотреть пример

Find Place from Phone Number

Find Place from Phone Number принимает номер телефона и возвращает место. Чтобы сделать запрос Find Place from Phone Number, вызовите метод findPlaceFromPhoneNumber() сервиса PlacesService, который принимает следующие параметры:

phoneNumber (обязательный параметр) – номер телефона в формате E.164.
fields (обязательный параметр) – одно или несколько полей, где указаны типы данных Place, которые нужно вернуть.
locationBias (необязательный параметр) – координаты, определяющие область поиска. Может принимать следующие значения:
- набор координат широты и долготы, указанный в виде LatLngLiteral или объекта LatLng;
- прямоугольные границы (четыре точки, определяемые широтой и долготой, или объект LatLngBounds);
- окружность заданного радиуса (в метрах) с центром в координатах широты и долготы.

Кроме того, для обработки объекта результатов и ответа findPlaceFromPhoneNumber() нужно передать метод обратного вызова методу google.maps.places.PlacesServiceStatus.

Поля (методы Find Place)

Чтобы указать типы данных о местах, которые нужно возвращать, используйте параметр fields. Пример: fields: ['formatted_address', 'opening_hours', 'geometry']. Если вы указываете составные значения, используйте точку. Пример: opening_hours.weekday_text.

Поля соответствуют результатам Place Search и разделены на три категории, которые оплачиваются по разным тарифам: Basic, Contact и Atmosphere. Поля Basic оплачиваются по базовой цене, и за них дополнительная плата не взимается. Поля Contact и Atmosphere оплачиваются по более высокой ставке. Ознакомьтесь с информацией о ценах. С каждым вызовом возвращаются сведения об авторстве (html_attributions) независимо от того, запрашивалось ли это поле.

Важное примечание. Запросы Place Search и Place Details возвращают разные поля. При запросах Place Search возвращается только часть полей, которые возвращаются при запросах Place Details. Если нужное поле не было возвращено Place Search, с помощью Place Search можно получить place_id, а затем использовать этот идентификатор места в запросе Place Details.

Basic

К категории Basic относятся следующие поля:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (поддержка прекращена), photos, place_id, plus_code, types

Contact

В категорию Contact входит следующее поле: opening_hours
Поддержка прекращена в библиотеке Places Library в Maps JavaScript API. Используйте запрос Place Details, чтобы получить результаты opening_hours.

Atmosphere

Категория Atmosphere содержит следующие поля: price_level, rating, user_ratings_total.

Методы findPlaceFromQuery() и findPlaceFromPhoneNumber() принимают и возвращают в ответах одинаковые наборы полей.

Как задать предпочтительное местоположение (методы Find Place)

Используйте параметр locationBias, чтобы в ответах на запросы Find Place предпочтение отдавалось результатам из определенной области. Вы можете задать locationBias следующим образом:

Настроить предпочтение результатов из определенной области:

locationBias: {lat: 37.402105, lng: -122.081974}

Ограничить поиск прямоугольной областью:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

Кроме того, можно использовать LatLngBounds.

Задать окружность определенного радиуса (в метрах) с центром в указанной точке.

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

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

С помощью Nearby Search можно находить места в указанной области по ключевому слову или по типу. В запросе Nearby Search нужно обязательно указать местоположение одним из следующих двух способов:

LatLngBounds;
с помощью комбинации свойства location, которое определяет центр окружности в виде объекта LatLng, и значения радиуса в метрах.

Для поиска Places Nearby необходимо вызвать метод nearbySearch() сервиса PlacesService, который вернет массив объектов PlaceResult. Обратите внимание, что начиная с версии 3.9 метод search() заменил устаревший метод nearbySearch().

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

Этот метод принимает запрос со следующими полями:

Одно из двух следующих полей:
- bounds, которое должно содержать объект google.maps.LatLngBounds, определяющий прямоугольную область поиска.
- location и radius. Первое поле принимает объект google.maps.LatLng, а второе – принимает простое целое число, представляющее радиус окружности в метрах. Максимальный допустимый радиус составляет 50 000 метров. Обратите внимание, что если для параметра rankBy задано значение DISTANCE, нужно обязательно указать location, но нельзя указать radius или bounds.
keyword (необязательный параметр) – ключевое слово, по которому ведется поиск во всех доступных полях, включая, помимо прочего, название, тип, адрес, а также отзывы клиентов и сторонний контент.
minPriceLevel и maxPriceLevel (необязательные параметры) – ограничивают результаты местами, которые соответствуют указанному диапазону. Значения могут находиться в диапазоне от 0 (наиболее доступные места) до 4 (наиболее дорогие места).
name – поддержка прекращена. Эквивалент keyword. Значения из этого поля объединяются со значениями поля keyword и передаются в составе той же строки поиска.
openNow (необязательный параметр) – логическое значение, указывающее, что сервис Places должен включить в результаты поиска только те места, которые открыты в момент отправки запроса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются. Установка для параметра openNow значения false ни на что не влияет.
rankBy (необязательный параметр) задает порядок вывода результатов. Возможные значения:
- google.maps.places.RankBy.PROMINENCE (по умолчанию). Результаты сортируются по известности. Приоритет в рейтинге отдается более известным местам, находящимся в заданной области, перед менее известными местами поблизости. На известность влияет рейтинг места в индексе Google, общая популярность и другие факторы. Если указано значение google.maps.places.RankBy.PROMINENCE, требуется также указать параметр radius.
- google.maps.places.RankBy.DISTANCE. Результаты сортируются в порядке близости к точке, заданной в параметре location (обязательный параметр). Обратите внимание, что нельзя задать значение bounds и/или radius, если вы указали RankBy.DISTANCE. Если вы укажете значение RankBy.DISTANCE, нужно также предоставить keyword, name и/или type.
type. В результаты поиска включаются только места указанного типа. Можно указать только один тип (если указано несколько, то все типы, кроме первого, игнорируются). Ознакомьтесь с поддерживаемыми типами.

Кроме того, для обработки объекта результатов и ответа nearbySearch() нужно передать метод обратного вызова методу google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

Посмотреть пример

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

Text Search в Google Places является веб-сервисом, который возвращает информацию о местах на основе введенной фразы, например "кафе в Москве" или "обувные магазины в Санкт-Петербурге". Ответ этого сервиса содержит список мест, соответствующих текстовой строке с учетом указанного предпочтительного местоположения. Ответ на поисковый запрос будет содержать список мест. Чтобы получить подробную информацию о любом из них, можно отправить запрос Place Details.

Для инициализации запросов Text Search используется метод textSearch() сервиса PlacesService.

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Этот метод принимает запрос со следующими полями:

query (обязательный параметр) – строка для текстового поиска, например "ресторан" или "улица Центральная, 123". Нужно указать название места, его адрес или категорию учреждения. Если ввести данные другого типа, вы можете получить неправильные результаты или возникнет ошибка. На основе этой строки сервис Places возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности. Этот параметр не обязателен, если в поисковом запросе также используется параметр type.
Необязательные поля:
- openNow – логическое значение, указывающее, что сервис Places должен включить в результаты поиска только те места, которые открыты в момент отправки запроса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются. Установка для параметра openNow значения false ни на что не влияет.
- minPriceLevel и maxPriceLevel ограничивают результаты местами, которые соответствуют указанному диапазону. Значения могут находится в диапазоне от 0 (наиболее доступные места) до 4 (наиболее дорогие места).
- Одно из двух следующих полей:
  - bounds – объект google.maps.LatLngBounds, определяющий прямоугольную область поиска.
  - location и radius – с помощью параметров location и radius можно настроить поиск так, чтобы предпочтение отдавалось результатам в пределах указанной окружности. Сервис Places будет показывать первыми в результатах места из указанной области, однако более отдаленные точки также могут быть включены в ответ. Поле location принимает объект google.maps.LatLng, а поле radius – обычное целое число, соответствующее радиусу окружности в метрах. Максимально допустимый радиус составляет 50 000 метров.
- type – в результаты поиска включаются только места указанного типа. Можно указать только один тип (если указано несколько, то все типы, кроме первого, игнорируются). Ознакомьтесь с поддерживаемыми типами.

Кроме того, для обработки объекта результатов и ответа textSearch() нужно передать метод обратного вызова методу google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

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

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

Объект ответа PlacesServiceStatus содержит информацию о статусе запроса и может включать в себя отладочную информацию для отслеживания сбоев при поиске. Возможные коды состояния:

INVALID_REQUEST: недопустимый запрос.
OK: ответ содержит действительный результат.
OVER_QUERY_LIMIT: превышена квота запросов к веб-странице.
REQUEST_DENIED: веб-странице запрещено использовать сервис PlacesService.
UNKNOWN_ERROR: запрос сервиса PlacesService не выполнен из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.
ZERO_RESULTS: не найдено результатов по данному запросу.

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

Функции findPlace(), nearbySearch() и textSearch() возвращают массив объектов PlaceResult.

Каждый объект PlaceResult может включать следующие свойства:

business_status указывает, работает ли место, если оно является компанией. Это свойство может принимать одно из следующих значений:
- OPERATIONAL
- CLOSED_TEMPORARILY
- CLOSED_PERMANENTLY
Если информация отсутствует, свойство business_status возвращено не будет.
formatted_address – строка, содержащая удобочитаемый адрес этого места. Свойство formatted_address возвращается только при запросе Text Search.
Часто это почтовый адрес. В некоторых странах, таких как Великобритания, не разрешено распространение настоящих почтовых адресов в связи с ограничениями лицензирования.

Отформатированный адрес состоит из одного или нескольких компонентов адреса. Например, адрес "111 8th Avenue, New York, NY" содержит отдельные компоненты "111" (номер дома), "8th Avenue" (улица), "New York" (город) и "NY" (штат США).

Не анализируйте отформатированный адрес программно. Вместо этого используйте отдельные компоненты адреса, которые ответ API включает в дополнение к полю отформатированного адреса.
geometry – геометрические характеристики места. Включает следующие свойства:
- location – широта и долгота места.
- viewport – предпочитаемая область просмотра на карте при просмотре данного места.
permanently_closed (поддержка прекращена) – логический флаг, указывающий на то, что место закрыто навсегда или временно (значение true). Не используйте permanently_closed. Вместо него используйте business_status, чтобы получать данные о статусе компаний.
plus_code (см. Open Location Code и коды Plus Code) – это закодированная ссылка на местоположение на основе координат широты и долготы, которая представляет область: 1/8000 градуса на 1/8000 градуса (приблизительно 14 x 14 метров на экваторе) или меньше. Коды Plus Code можно использовать в качестве замены почтовым адресам там, где эти адреса не существуют (здания не пронумерованы или улицам не присвоены названия).
Код Plus Code форматируется как глобальный и составной код:
- global_code содержит четыре знака кода зоны и не менее шести знаков местного кода (849VCWC8+R9).
- compound_code содержит не менее шести знаков местного кода с данными о местоположении (CWC8+R9 для Маунтин-Вью, Калифорния, США). Не анализируйте этот контент программно.
Как правило, возвращаются и глобальный, и составной код. Однако если результат находится в удаленном расположении, например в океане или пустыне, может быть возвращен только глобальный код.
html_attributions – массив указаний авторства, которые должны отображаться при выводе результатов поиска. Каждый элемент массива содержит текст HTML для одного указания. Примечание. Этот массив объединяет все указания авторства для всего поискового запроса, поэтому все объекты PlaceResult в ответе содержат идентичные списки указаний авторства.
icon возвращает URL для цветного значка в формате PNG размером 71 x 71 пиксель.
icon_mask_base_uri возвращает базовый URL для значка без цвета без указания расширения SVG или PNG.
icon_background_color возвращает шестнадцатеричный код цвета для категории места.
name – название места.
opening_hours может содержать следующую информацию:
- open_now – логическое значение, указывающее, работает или нет в текущий момент место (поддержка прекращена в библиотеке Places в Maps JavaScript API – используйте utc_offset_minutes).
place_id – уникальный текстовый идентификатор места. Чтобы извлечь информацию о месте, передайте этот идентификатор в запросе Place Details. Подробнее о том, как ссылаться на место с помощью идентификатора места…
rating – основанная на отзывах пользователей оценка места в диапазоне от 0,0 до 5,0.
types – массив типов для этого места (например, ["political", "locality"] или ["restaurant", "lodging"]). Этот массив может содержать несколько значений или может быть пустым. Новые значения могут быть добавлены без уведомления. Ознакомьтесь с поддерживаемыми типами.
vicinity – упрощенный адрес места, включая населенный пункт, улицу и номер дома, но без указания штата, провинции или области, почтового индекса и страны. Например, для офиса Google в Сиднее (Австралия), параметр vicinity имеет значение 5/48 Pirrama Road, Pyrmont.

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

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

hasNextPage – свойство, имеющее логическое значение и указывающее, доступны или нет дополнительные результаты. Имеет значение true, если существуют дополнительные результаты.
nextPage() – функция, возвращающая следующий набор результатов. Следующая страница становится доступной через две секунды после выполнения поиска.

Для просмотра следующего набора результатов следует вызвать функцию nextPage. Страницы результатов можно выводить только по очереди. Обратите внимание, что с точки зрения ограничений на использование каждый поиск учитывается как отдельный запрос.

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

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;index.js

Посмотреть пример

Примеры кода

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

Place Details

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

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

Для запроса Place Details используется метод getDetails() сервиса.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Этот метод принимает запрос, содержащий placeId нужного места и поля, указывающие, какие типы данных Places нужно вернуть. Подробнее о том, как ссылаться на место с помощью идентификатора места…

Кроме того, ему передается метод обратного вызова, который нужен для обработки кода статуса, передаваемого в ответе google.maps.places.PlacesServiceStatus, а также объект google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Посмотреть пример

Вы можете запросить place_id для места бесплатно. Для этого вызовите getDetails() и укажите только поле place_id.

Поля (информация о месте)

Параметр fields принимает массив строк (имен полей).

Чтобы указать типы данных о местах, которые нужно возвращать, используйте параметр fields. Пример: fields: ['address_components', 'opening_hours', 'geometry']. Если вы указываете составные значения, используйте точку. Например: opening_hours.weekday_text.

Поля соответствуют результатам Place Details и разделены на три категории, которые оплачиваются по разным тарифам: Basic, Contact и Atmosphere. Поля Basic оплачиваются по базовой цене, и за них дополнительная плата не взимается. Поля Contact и Atmosphere оплачиваются по более высокой ставке. Ознакомьтесь с информацией о ценах. С каждым вызовом возвращаются сведения об авторстве (html_attributions) независимо от того, запрашивалось ли это поле.

Basic

К категории Basic относятся следующие поля:
address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (deprecated), photo, place_id, plus_code, type, url, utc_offset (поддержка прекращена в библиотеке Places в Maps JavaScript API), utc_offset_minutes, vicinity.

Contact

В категорию Contact входят следующие поля:
formatted_phone_number, international_phone_number, opening_hours, website.

Atmosphere

Категория Atmosphere содержит следующие поля: price_level, rating, reviews, user_ratings_total.

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

Внимание! Если вы не укажете хотя бы одно поле с запросом или если не включите параметр fields в запросе, возвращены будут все возможные поля, и за это будет начислена плата. Это применяется только к запросам Place Details, в том числе к запросам Place Details, выполненным из виджета Place Autocomplete.

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

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

Объект ответа PlacesServiceStatus содержит данные статуса запроса и может включать сведения для отладки выполнении запроса Place Details. Возможные коды состояния:

INVALID_REQUEST: недопустимый запрос.
OK: ответ содержит действительный результат.
OVER_QUERY_LIMIT: превышена квота запросов к веб-странице.
NOT_FOUND: указанное место не найдено в базе данных Places.
REQUEST_DENIED: веб-странице запрещено использовать сервис PlacesService.
UNKNOWN_ERROR: запрос сервиса PlacesService не выполнен из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.
ZERO_RESULTS: не найдено результатов по данному запросу.

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

При успешном вызове getDetails() возвращается объект PlaceResult, имеющий следующие свойства:

address_components – массив, содержащий отдельные компоненты адреса.
Каждый из компонентов адреса обычно содержит следующие поля:
- types[] – массив, указывающий тип компонента адреса. Ознакомьтесь с поддерживаемыми типами.
- long_name – полное текстовое описание или название компонента адреса, возвращаемого геокодером.
- short_name – сокращенное текстовое название компонента адреса (если есть). Например, компонент адреса для штата Аляска может содержать long_name "Alaska" и short_name "AK" (двухбуквенное почтовое сокращение).
Обратите внимание на следующие особенности массива address_components[]:
- Массив компонентов адреса может содержать больше компонентов, чем formatted_address.
- Массив не обязательно будет включать все административные единицы, которые содержат адрес, за исключением тех, что включены в formatted_address. Чтобы получить все административные единицы, которые содержат определенный адрес, следует использовать обратное геокодирование и передать широту и долготу адреса в виде параметра запроса.
- Формат ответа может меняться от запроса к запросу. В частности, количество address_components зависит от запрашиваемого адреса и может изменяться со временем. Положение компонента в массиве может измениться. Может измениться и тип компонента. В последующем ответе определенный компонент может отсутствовать.
business_status указывает, работает ли место, если оно является компанией. Это свойство может принимать одно из следующих значений:
- OPERATIONAL
- CLOSED_TEMPORARILY
- CLOSED_PERMANENTLY
Если информация отсутствует, свойство business_status возвращено не будет.
formatted_address – удобочитаемый адрес места.
Часто это почтовый адрес. В некоторых странах, таких как Великобритания, не разрешено распространение настоящих почтовых адресов в связи с ограничениями лицензирования.

Отформатированный адрес состоит из одного или нескольких компонентов адреса. Например, адрес "111 8th Avenue, New York, NY" содержит отдельные компоненты "111" (номер дома), "8th Avenue" (улица), "New York" (город) и "NY" (штат США).

Не анализируйте отформатированный адрес программно. Вместо этого используйте отдельные компоненты адреса, которые ответ API включает в дополнение к полю отформатированного адреса.
formatted_phone_number – номер телефона для этого места в формате, соответствующем региональным правилам нумерации.
geometry – геометрические характеристики места. Включает следующие свойства:
- location – широта и долгота места.
- viewport – предпочитаемая область просмотра на карте при просмотре данного места.
permanently_closed (поддержка прекращена) – логический флаг, указывающий на то, что место закрыто навсегда или временно (значение true). Не используйте permanently_closed. Вместо него используйте business_status, чтобы получать данные о статусе компаний.
plus_code (см. Open Location Code и коды Plus Code) – это закодированная ссылка на местоположение на основе координат широты и долготы, которая представляет область: 1/8000 градуса на 1/8000 градуса (приблизительно 14 x 14 метров на экваторе) или меньше. Коды Plus Code можно использовать в качестве замены почтовым адресам там, где эти адреса не существуют (здания не пронумерованы или улицам не присвоены названия).
Код Plus Code форматируется как глобальный и составной код:
- global_code содержит четыре знака кода зоны и не менее шести знаков местного кода (849VCWC8+R9).
- compound_code содержит не менее шести знаков местного кода с данными о местоположении (CWC8+R9 для Маунтин-Вью, Калифорния, США). Не анализируйте этот контент программно.
Как правило, возвращаются и глобальный, и составной код. Однако если результат находится в отдаленном месте, например в океане или пустыне, может быть возвращен только глобальный код.
html_attributions – текст указания об авторстве, отображаемый для этого результата места.
icon – содержит URL-адрес ресурса изображения, которое можно использовать для обозначения этого типа места.
international_phone_number – содержит номер телефона в международном формате, в котором указывается код страны и префикс в виде знака "плюс" (+). Например, значение international_phone_number для офиса Google в Сиднее (Австралия): +61 2 9374 4000.
name – название места.
utc_offset – поддержка прекращена в библиотеке Places в Maps JavaScript API. Используйте utc_offset_minutes.
utc_offset_minutes – разница в минутах между текущим часовым поясом места и временем UTC. Например, в Сиднее (Австралия) после перехода на летнее время это значение равно 660 (+11 часов относительно UTC). Для Калифорнии после перехода на зимнее время это значение равно -480 (-8 часов относительно UTC).
opening_hours содержит следующие сведения:
- open_now (поддержка прекращена в библиотеке Places в Maps JavaScript API; используйте opening_hours.isOpen(); при необходимости посмотрите видео об использовании isOpen с Place Details) – логическое значение, указывающее, работает или нет в текущий момент это место.
- periods[] – хронологически упорядоченный массив часов работы, содержащий данные по семи дням недели, начиная с воскресенья. Каждый период содержит следующую информацию:
  - open содержит пару объектов дня недели и времени, описывающих время начала работы места:
    - day – номер дня недели в диапазоне от 0 до 6, начиная с воскресенья. Например, 2 обозначает вторник.
    - time – время в 24-часовом формате "ччмм" в диапазоне 0000–2359. Значение time указывается в часовом поясе этого места.
  - close содержит пару объектов дня недели и времени, описывающих время окончания работы места. Примечание: если место работает круглосуточно, в ответе не будет раздела close. Можно уверенно считать, что место работает круглосуточно, если период open содержит параметр day, имеющий значение 0, параметр time, имеющий значение 0000, и при этом отсутствует параметр close.
- weekday_text – массив с семью строками, обозначающими время работы по дням недели в соответствующем формате. Если при запросе Place Details был указан параметр language, сервис Places выведет время работы на указанном языке в соответствующем ему формате. Порядок элементов в этом массиве зависит от параметра language. В некоторых странах неделя начинается с понедельника, а в других началом недели считается воскресенье.
permanently_closed (поддержка прекращена) – логический флаг, указывающий на то, что место закрыто навсегда или временно (значение true). Не используйте permanently_closed. Вместо него используйте business_status, чтобы получать данные о статусе компаний.
photos[] – массив объектов PlacePhoto. Массив PlacePhoto можно использовать для получения фотографии с помощью метода getUrl(). Объекты также можно проверить по следующим значениям:
- height – максимальная высота изображения в пикселях.
- width – максимальная ширина изображения в пикселях.
- html_attributions – текст указания об авторстве, отображаемый с этой фотографией места.
place_id – уникальный текстовый идентификатор места, который можно использовать в запросах Place Details. Подробнее о том, как ссылаться на место с помощью идентификатора места…
rating – основанная на отзывах пользователей оценка места в диапазоне от 0,0 до 5,0.
reviews – массив, содержащий до пяти отзывов. Каждый отзыв состоит из нескольких компонентов:
- aspects[] содержит массив объектов PlaceAspectRating, каждый из которых определяет оценку организации по отдельным признакам. Первый объект в массиве считается основным критерием. Каждый объект PlaceAspectRating определяется следующим образом:
  - type – название оцениваемого критерия. Поддерживаются следующие типы: appeal, atmosphere, decor, facilities, food, overall, quality и service.
  - rating – пользовательская оценка по конкретному критерию в диапазоне от 0 до 3.
- author_name – имя пользователя, отправившего отзыв. К анонимным отзывам добавляется подпись "A Google user". Если указано значение для параметра языка, возвращается локализованная фраза "Пользователь Google".
- author_url – URL профиля Google+ пользователя (если указан).
- language – код IETF, указывающий язык, на котором написан отзыв. Это поле содержит только основной тег языка и не содержит дополнительный тег страны или региона. Например, все отзывы на английском языке имеют тег "en", но не "en-AU", "en-UK" и т. д.
- rating – общая оценка пользователя для данного места. Она представляет собой целое число от 1 до 5.
- text – отзыв пользователя. В сервисе Google Places поле текста отзыва не является обязательным и может быть пустым.
types – массив типов для этого места (например, ["political", "locality"] или ["restaurant", "lodging"]). Этот массив может содержать несколько значений или может быть пустым. Новые значения могут быть добавлены без уведомления. Ознакомьтесь с поддерживаемыми типами.
url – URL-адрес официальной страницы этого места в Google. Это страница Google, содержащая всю имеющуюся информацию об этом месте. Приложения должны показывать пользователю встроенную страницу места или ссылку на нее на любом экране с подробным описанием этого места.
vicinity – упрощенный адрес места, включая населенный пункт, улицу и номер дома, но без указания штата, провинции или области, почтового индекса и страны. Например, для офиса Google в Сиднее (Австралия), параметр vicinity имеет значение 5/48 Pirrama Road, Pyrmont. Свойство vicinity возвращается только при запросе Nearby Search.
website – перечень официальных сайтов, связанных с этим местом, например адрес домашней страницы компании.

Примечание. Не для всех мест могут быть даны оценки по каждому из критериев. При недостаточном количестве отзывов запрос описания возвращает предыдущую оценку в диапазоне от 0,0 до 5,0 (если она доступна) или вовсе не возвращает оценку.

Ссылка на место с использованием идентификатора

Идентификатор места – это уникальная ссылка не место на карте Google. Идентификаторы мест имеются для большинства местоположений, в том числе для компаний, ориентиров, парков и перекрестков.

Чтобы воспользоваться идентификатором места в приложении, вам необходимо предварительно найти нужный идентификатор, который содержится в объекте PlaceResult запроса Place Search или Details. Затем этот идентификатор можно использовать для запроса Place Details.

На идентификаторы мест не распространяются ограничения по кэшированию, указанные в пункте 3.2.3(a) Условий использования платформы Google Карт. Поэтому их можно хранить для последующего использования. Рекомендации по хранению идентификаторов мест приведены в статье Общие сведения об идентификаторах мест.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Фотографии места

Функция Place Photo – удобный источник высококачественных снимков для вашего сайта. Она открывает доступ к миллионам фотографий, которые хранятся в базах данных Places и Google+ Local. Идентификаторы фотографий возвращаются автоматически при запросе данных о конкретном месте. В ответ на запросы Nearby Search b Text Search для каждого места также возвращается один идентификатор фотографии (при наличии). Затем вы можете показать фотографию с этим идентификатором пользователю в оптимальном для вашего приложения размере.

Массив объектов PlacePhoto возвращается в виде части объекта PlaceResult для любого запроса getDetails(), textSearch() и nearbySearch(), направленного в сервис PlacesService.

Примечание. Количество возвращаемых фотографий зависит от типа запроса.

В ответах на запросы Nearby Search и Text Search возвращается не более одного объекта PlacePhoto.
В ответах на запрос Details возвращается до десяти объектов PlacePhoto.

С помощью метода PlacePhoto.getUrl() и передачи действующего объекта PhotoOptions можно запросить URL связанного изображения. Объект PhotoOptions позволяет указать максимальную высоту и ширину изображения. Если указать значение для параметров maxHeight и maxWidth, сервис Photo изменит размер изображения с учетом меньшего значения, сохранив при этом соотношение сторон.

Приведенный ниже фрагмент кода принимает объект места и добавляет метку к карте при наличии фотографии. Изображение метки по умолчанию сменяется миниатюрной фотографией.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

Сервис Photo передает изображения из множества источников, в том числе фотографии, предоставленные владельцами компаний и пользователями. Как правило, такие фотографии можно использовать без упоминания авторства, или оно будет указано непосредственно на снимке. Однако, если возвращенный элемент photo содержит значение в поле html_attributions, в приложении вместе с изображением необходимо дополнительно указывать авторство.