Библиотека мест

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Выберите платформу: Android iOS JavaScript Web Service

Обзор

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

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

Начиная

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

Включить API

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

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

  1. Перейдите в облачную консоль Google .
  2. Нажмите кнопку « Выбрать проект» , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите « Открыть » .
  3. В списке API на панели инструментов найдите Places API .
  4. Если вы видите в списке Places API, он уже включен. Если API нет в списке, включите его:
    1. В верхней части страницы выберите ВКЛЮЧИТЬ API И СЛУЖБЫ , чтобы отобразить вкладку « Библиотека ». Кроме того, в левом боковом меню выберите « Библиотека ».
    2. Найдите Places API и выберите его в списке результатов.
    3. Выберите ВКЛЮЧИТЬ . Когда процесс завершится, 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 одним или несколькими API или SDK. Запросы к API или SDK, связанные с ключом API, будут обрабатываться. Запросы к API или SDK, не связанным с ключом API, завершатся ошибкой. Чтобы ограничить использование ключа API с библиотекой Places, Maps JavaScript API:
  1. Перейдите в облачную консоль Google .
  2. Щелкните раскрывающийся список проекта и выберите проект, содержащий ключ API, который вы хотите защитить.
  3. Нажмите кнопку меню и выберите Платформа Google Карт > Учетные данные .
  4. На странице учетных данных щелкните имя ключа API, который вы хотите защитить.
  5. На странице Ограничить и переименовать ключ API задайте ограничения:
    • Ограничения API
      • Выберите Ограничить ключ .
      • Нажмите «Выбрать API» и выберите API JavaScript для Карт и API Places .
        (Если какой-либо из API отсутствует в списке, его необходимо включить .)
  6. Нажмите СОХРАНИТЬ .

Ограничения и политики использования

квоты

Библиотека Places, API JavaScript имеет общую квоту использования с API Places, как описано в документации по ограничениям использования для API Places. Ограничение частоты запросов в секунду применяется к сеансу пользователя, независимо от того, сколько пользователей совместно используют один и тот же проект.*

Примечание . При первой загрузке API вам выделяется начальная квота запросов. После того, как вы используете эту квоту, API применяет ограничения скорости для дополнительных запросов на посекундной основе. Если за определенный период времени сделано слишком много запросов, API возвращает код ответа OVER_QUERY_LIMIT. Ограничение скорости на сеанс предотвращает использование клиентских служб для пакетных запросов. Для пакетных запросов используйте API наших веб-сервисов.

Политики

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

Место поиска

Служба Places позволяет выполнять следующие виды поиска:

  • Функция « Найти место из запроса » возвращает место на основе текстового запроса (например, название или адрес места).
  • Функция « Найти место по номеру телефона » возвращает место по номеру телефона.
  • Поиск поблизости возвращает список ближайших мест на основе местоположения пользователя.
  • Текстовый поиск возвращает список близлежащих мест на основе строки поиска, например. "Пицца".
  • Запросы сведений о месте возвращают более подробную информацию о конкретном месте, включая отзывы пользователей.

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

Запросы на поиск мест

Запрос «Найти место» позволяет искать место либо по текстовому запросу, либо по номеру телефона. Существует два типа запроса «Найти место»:

Найти место из запроса

Find Place from Query принимает ввод текста и возвращает место. Входными данными могут быть любые данные о месте, например название компании или адрес. Чтобы сделать запрос «Найти место из запроса», вызовите PlaceService findPlaceFromQuery() , который принимает следующие параметры:

  • query (обязательно) Текстовая строка для поиска, например: "ресторан" или "123 Мейн-стрит". Это должно быть название места, адрес или категория заведений. Любые другие типы ввода могут генерировать ошибки и не гарантируют возврат правильных результатов. Places API будет возвращать возможные совпадения на основе этой строки и упорядочивать результаты в зависимости от их предполагаемой релевантности.
  • fields (обязательно) Одно или несколько полей , определяющих типы возвращаемых данных Place.
  • locationBias (необязательно) Координаты, определяющие область поиска. Это может быть одно из следующих:
    • Набор координат широты/долготы, указанный как объект LatLngLiteral или LatLng .
    • Прямоугольные границы (две пары широта/долгота или объект LatLngBounds )
    • Радиус (в метрах) с центром в широте/долготе

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

В следующем примере показан вызов 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);
    }
  });
}
Посмотреть пример

Найти место по номеру телефона

Функция «Найти место по номеру телефона» берет номер телефона и возвращает место. Чтобы сделать запрос «Найти место по номеру телефона», вызовите PlaceService findPlaceFromPhoneNumber() , который принимает следующие параметры:

  • phoneNumber (обязательно) Номер телефона в формате E.164 .
  • fields (обязательно) Одно или несколько полей , определяющих типы возвращаемых данных Place.
  • locationBias (необязательно) Координаты, определяющие область поиска. Это может быть одно из следующих:
    • Набор координат широты/долготы, указанный как объект LatLngLiteral или LatLng .
    • Прямоугольные границы (четыре точки широты/долготы или объект LatLngBounds )
    • Радиус (в метрах) с центром в широте/долготе

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

Поля (методы «Найти место»)

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

Поля соответствуют результатам поиска мест и разделены на три категории оплаты: «Базовый», «Контакты» и «Атмосфера». Плата за основные поля взимается по базовому тарифу и не требует дополнительной оплаты. Поля «Контакт» и «Атмосфера» оплачиваются по более высокой ставке. См. прайс-лист для получения дополнительной информации. Атрибуции ( html_attributions ) всегда возвращаются при каждом вызове, независимо от того, было ли запрошено поле.

Базовый

Категория «Основные» включает в себя следующие поля:
business_status , formatted_address , geometry , icon , icon_mask_base_uri , icon_background_color , name , permanently_closed ( устарело ), photos , place_id , plus_code , types

Контакт

Категория «Контакт» включает в себя следующее поле: opening_hours
( устарело в Places Library, Maps JavaScript API. Используйте запрос Place Details, чтобы получить результаты opening_hours ).

Атмосфера

Категория Атмосфера включает в себя следующие поля: price_level , rating , user_ratings_total

Каждый findPlaceFromQuery() и findPlaceFromPhoneNumber() принимает один и тот же набор полей и может возвращать одни и те же поля в соответствующих ответах.

Установить смещение местоположения (методы «Найти место»)

Используйте параметр locationBias , чтобы сделать поиск места предпочтительным в определенной области. Вы можете установить 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}}

Ближайшие поисковые запросы

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

  • LatLngBounds .
  • круговая область, определяемая как комбинация свойства location — указание центра круга как объекта LatLng — и радиуса, измеряемого в метрах.

Поиск Places Nearby инициируется вызовом метода PlacesService nearbySearch() , который возвращает массив объектов PlaceResult . Обратите внимание, что метод nearbySearch() заменяет метод search() начиная с версии 3.9.

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]);
    }
  }
}

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

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

Служба текстового поиска Google Places — это веб-служба, которая возвращает информацию о наборе мест на основе строки, например «пицца в Нью-Йорке» или «обувные магазины недалеко от Оттавы». Служба отвечает списком мест, соответствующих текстовой строке, и любым установленным смещением местоположения. Ответ поиска будет включать список мест. Вы можете отправить запрос сведений о месте, чтобы получить дополнительную информацию о любом из мест в ответе.

Текстовый поиск инициируется вызовом PlacesService textSearch() .

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

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

  • query ( обязательный ) Текстовая строка для поиска, например: "ресторан" или "123 Main Street". Это должно быть название места, адрес или категория заведений. Любые другие типы ввода могут генерировать ошибки и не гарантируют возврат правильных результатов. Служба Places будет возвращать возможные совпадения на основе этой строки и упорядочивать результаты в зависимости от их предполагаемой релевантности. Этот параметр становится необязательным, если в запросе поиска также используется параметр type .
  • Необязательно:
    • openNow — логическое значение, указывающее, что служба Places должна возвращать только те места, которые открыты для бизнеса на момент отправки запроса. Места, для которых не указаны часы работы в базе данных Google Places, не будут возвращены, если вы включите этот параметр в свой запрос. Установка для openNow false не имеет никакого эффекта.
    • minPriceLevel и maxPriceLevel — ограничивает результаты только теми местами в пределах указанного уровня цен. Допустимые значения находятся в диапазоне от 0 (самый доступный) до 4 (самый дорогой) включительно.
    • Любой из:
      • bounds — объект google.maps.LatLngBounds , определяющий прямоугольник для поиска; или же
      • location и radius — вы можете сместить результаты к указанному кругу, передав параметр location и radius . Это даст указание службе Places отдавать предпочтение показу результатов внутри этого круга. Результаты за пределами определенной области все еще могут отображаться. Местоположение принимает объект google.maps.LatLng , а радиус принимает простое целое число, представляющее радиус окружности в метрах. Максимально допустимый радиус составляет 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 возвращается только для текстового поиска .

    Часто этот адрес эквивалентен почтовому адресу. Обратите внимание, что в некоторых странах, например в Великобритании, распространение настоящих почтовых адресов запрещено из-за лицензионных ограничений.

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

    Не анализируйте отформатированный адрес программно. Вместо этого следует использовать отдельные компоненты адреса, которые включаются в ответ API в дополнение к форматированному полю адреса.

  • geometry : информация, связанная с геометрией места. Это включает:
    • location обеспечивает широту и долготу места.
    • viewport определяет предпочтительную область просмотра на карте при просмотре этого места.
  • permanently_closed ( deprecated ) — это логический флаг, указывающий, закрыто ли место навсегда или временно (значение true ). Не используйте permanently_closed . Вместо этого используйте business_status , чтобы получить операционный статус предприятий.
  • plus_code (см. Открытый код местоположения и плюсовые коды ) — это закодированная ссылка на местоположение, полученная из координат широты и долготы, которая представляет площадь: 1/8000 градуса на 1/8000 градуса (около 14 м x 14 м на экваторе) или меньше. Плюс-коды можно использовать в качестве замены уличных адресов в местах, где их нет (где здания не пронумерованы или улицы не названы).

    Плюс-код форматируется как глобальный код и составной код:

    • global_code — это 4-символьный код города и 6-символьный или более локальный код (849VCWC8+R9).
    • compound_code — это локальный код из 6 или более символов с явным указанием местоположения (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 — это текстовый идентификатор, однозначно идентифицирующий место. Чтобы получить информацию о месте, передайте этот идентификатор в запросе сведений о месте. Узнайте больше о том, как сослаться на место с помощью идентификатора места .
  • rating содержит рейтинг места от 0,0 до 5,0 на основе сводных отзывов пользователей.
  • types Массив типов для этого места (например, ["political", "locality"] или ["restaurant", "lodging"] ). Этот массив может содержать несколько значений или может быть пустым. Новые значения могут быть введены без предварительного уведомления. См. список поддерживаемых типов .
  • vicinity : упрощенный адрес места, включая название улицы, номер улицы и населенный пункт, но не провинцию/штат, почтовый индекс или страну. Например, офис Google в Сиднее, Австралия, находится по адресу 5/48 vicinity 5/48 Pirrama Road, Pyrmont .

Доступ к дополнительным результатам

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

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

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

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

Машинопись

// 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;

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;
Посмотреть пример

Попробуйте образец

Сведения о месте

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

Запрос сведений о месте

Сведения о месте запрашиваются при вызове метода службы 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);
  }
}

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

Поля (детали места)

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

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

Поля соответствуют результатам сведений о месте и разделены на три категории выставления счетов: «Базовый», «Контакт» и «Атмосфера». Плата за основные поля взимается по базовому тарифу и не требует дополнительной оплаты. Поля «Контакт» и «Атмосфера» оплачиваются по более высокой ставке. См. прайс-лист для получения дополнительной информации. Атрибуции ( html_attributions ) всегда возвращаются при каждом вызове, независимо от того, был ли он запрошен.

Базовый

Категория «Основные» включает в себя следующие поля:
address_component , adr_address , business_status , formatted_address , geometry , icon , icon_mask_base_uri , icon_background_color , name , permanently_closed ( устарело ), photo , place_id , plus_code , type , url , utc_offset ( устарело в Places Library, Maps JavaScript API), utc_offset_minutes , vicinity

Контакт

Категория «Контакты» включает следующие поля:
formatted_phone_number , international_phone_number , opening_hours , веб- website

Атмосфера

Категория Атмосфера включает в себя следующие поля: price_level , rating , review , user_ratings_total

Подробнее о полях мест . Дополнительную информацию о том, как оплачиваются запросы данных Place, см. в разделе Использование и выставление счетов .

Место Подробности Ответы

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

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

  • 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 «Аляска» и short_name «АК» с использованием двухбуквенной почтовой аббревиатуры.

    Обратите внимание на следующие факты о массиве 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 ( deprecated ) — это логический флаг, указывающий, закрыто ли место навсегда или временно (значение true ). Не используйте permanently_closed . Вместо этого используйте business_status , чтобы получить операционный статус предприятий.
  • plus_code (см. Открытый код местоположения и плюсовые коды ) — это закодированная ссылка на местоположение, полученная из координат широты и долготы, которая представляет площадь: 1/8000 градуса на 1/8000 градуса (около 14 м x 14 м на экваторе) или меньше. Плюс-коды можно использовать в качестве замены уличных адресов в местах, где их нет (где здания не пронумерованы или улицы не названы).

    Плюс-код форматируется как глобальный код и составной код:

    • global_code — это 4-символьный код города и 6-символьный или более локальный код (849VCWC8+R9).
    • compound_code — это локальный код из 6 или более символов с явным указанием местоположения (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 ( Deprecated in the Places Library, Maps JavaScript API; use opening_hours.isOpen() instead. See this video for how to use isOpen with Place Details.) is a boolean value indicating whether the place is open at the current time.
    • periods[] is an array of opening periods covering seven days, starting from Sunday, in chronological order. Each period contains:
      • open contains a pair of day and time objects describing when the place opens:
        • day a number from 0–6, corresponding to the days of the week, starting on Sunday. For example, 2 means Tuesday.
        • time may contain a time of day in 24-hour hhmm format (values are in the range 0000–2359). The time will be reported in the place's timezone.
      • close may contain a pair of day and time objects describing when the place closes. Note: If a place is always open , the close section will be missing from the response. Applications can rely on always-open being represented as an open period containing day with value 0 and time with value 0000, and no close .
    • weekday_text is an array of seven strings representing the formatted opening hours for each day of the week. If a language parameter was specified in the Place Details request, the Places Service will format and localize the opening hours appropriately for that language. The ordering of the elements in this array depends on the language parameter. Some languages start the week on Monday while others start on Sunday.
  • permanently_closed ( deprecated ) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true ). Do not use permanently_closed . Instead, use business_status to get the operational status of businesses.
  • photos[] : an array of PlacePhoto objects. A PlacePhoto can be used to obtain a photo with the getUrl() method, or you can inspect the object for the following values:
    • height : the maximum height of the image, in pixels.
    • width : the maximum width of the image, in pixels.
    • html_attributions : Attribution text to be displayed with this place photo.
  • place_id : A textual identifier that uniquely identifies a place and can be used to retrieve information about the place via a Place Details request . Learn more about how to reference a place with a place ID .
  • rating : The place's rating, from 0.0 to 5.0, based on aggregated user reviews.
  • reviews an array of up to five reviews. Each review consists of several components:
    • aspects[] contains an array of PlaceAspectRating objects, each of which provides a rating of a single attribute of the establishment. The first object in the array is considered the primary aspect. Each PlaceAspectRating is defined as:
      • type the name of the aspect that is being rated. The following types are supported: appeal , atmosphere , decor , facilities , food , overall , quality and service .
      • rating the user's rating for this particular aspect, from 0 to 3.
    • author_name the name of the user who submitted the review. Anonymous reviews are attributed to "A Google user". If a language parameter was set, then the phrase "A Google user" will return a localized string.
    • author_url the URL to the users Google+ profile, if available.
    • language an IETF language code indicating the language used in the user's review. This field contains the main language tag only, and not the secondary tag indicating country or region. For example, all the English reviews are tagged as 'en', and not 'en-AU' or 'en-UK' and so on.
    • rating the user's overall rating for this place. This is a whole number, ranging from 1 to 5.
    • text the user's review. When reviewing a location with Google Places, text reviews are considered optional; therefore, this field may by empty.
  • types An array of types for this place (eg, ["political", "locality"] or ["restaurant", "lodging"] ). This array may contain multiple values, or may be empty. New values may be introduced without prior notice. See the list of supported types .
  • url : URL of the official Google page for this place. This is the Google-owned page that contains the best available information about the place. Applications must link to or embed this page on any screen that shows detailed results about the place to the user.
  • vicinity : A simplified address for the place, including the street name, street number, and locality, but not the province/state, postal code, or country. For example, Google's Sydney, Australia office has a vicinity value of 5/48 Pirrama Road, Pyrmont . The vicinity property is only returned for a Nearby Search .
  • website lists the authoritative website for this place, such as a business' homepage.

Note: Multidimensional ratings may not be available for all locations. If there are too few reviews then the details response will either include a legacy rating on a 0.0 to 5.0 scale (if available) or no rating at all.

Referencing a Place with a Place ID

A place ID is a unique reference to a place on a Google Map. Place IDs are available for most locations, including businesses, landmarks, parks, and intersections.

To use a place ID in your app you must first look up the ID, which is available in PlaceResult of a Place Search or Details request. You can then use this place ID to look up Place Details .

Place IDs are exempt from the caching restrictions stated in Section 3.2.3(a) of the Google Maps Platform Terms of Service. You can therefore store place ID values for later use. For best practises when storing place IDs, see the place ID overview .

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);

Место Фото

The Place Photo feature allows you to add high quality photographic content to your site. The Photo service gives you access to the millions of photos stored in the Places and Google+ Local database. When you get place information using a Place Details request, photo references will be returned for relevant photographic content. The Nearby Search and Text Search requests also return a single photo reference per place, when relevant. Using the Photo service you can then access the referenced photos and resize the image to the optimal size for your application.

An array of PlacePhoto objects will be returned as part of the PlaceResult object for any getDetails() , textSearch() or nearbySearch() request made against a PlacesService .

Note: The number of photos returned varies by request.

  • A Nearby Search or a Text Search will return at most one PlacePhoto object.
  • A Details request will return up to ten PlacePhoto objects.

You can request the URL for the associated image by calling the PlacePhoto.getUrl() method, and passing a valid PhotoOptions object. The PhotoOptions object allows you to specify the maximum desired height and width of the image. If you specify a value for both maxHeight and a maxWidth , the photo service will resize the image to the smaller of the two sizes, while maintaining the original aspect ratio.

The following code snippet accepts a place object, and adds a marker to the map if a photo exists. The default marker image is replaced by a small version of the 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})
  });
}

Photos returned by the Photo service are sourced from a variety of locations, including business owners and user contributed photos. In most cases, these photos can be used without attribution, or will have the required attribution included as a part of the image. However, if the returned photo element includes a value in the html_attributions field, you must include the additional attribution in your application wherever you display the image.