Библиотека Places

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

Обзор

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

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

Начиная

Если вы не знакомы с API JavaScript Карт или с 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. Если вы видите API Places в списке, значит, он уже включен. Если API нет в списке, включите его:
    1. В верхней части страницы выберите ВКЛЮЧИТЬ API И СЕРВИСЫ , чтобы отобразить вкладку «Библиотека» . Либо в меню слева выберите «Библиотека» .
    2. Найдите Places API , затем выберите его из списка результатов.
    3. Выберите ВКЛЮЧИТЬ . По завершении процесса Places API появится в списке API на информационной панели .

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

Служба Places — это автономная библиотека, отдельная от основного кода API JavaScript Карт. Чтобы использовать функциональные возможности, содержащиеся в этой библиотеке, необходимо сначала загрузить ее с помощью параметра libraries в URL-адресе начальной загрузки API Карт:

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

Дополнительную информацию см. в обзоре библиотек .

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

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

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

Квоты

Библиотека Places разделяет квоту использования с Places API, как описано в документации по ограничениям использования для Places API.

Политика

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

Поиск мест

С помощью службы «Метки» вы можете выполнять следующие виды поиска:

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

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

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

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

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

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

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

В следующем примере показан вызов findPlaceFromQuery() , поиск по запросу «Музей современного искусства Австралии» и включение полей 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);
    }
  });
}
Посмотреть пример

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

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

  • phoneNumber (обязательно) Номер телефона в формате E.164 .
  • fields (обязательные) Одно или несколько полей , определяющих типы возвращаемых данных о месте.
  • 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
( устарело в библиотеке мест, Maps JavaScript API. Используйте запрос сведений о месте, чтобы получить результаты 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 ) и радиуса, измеренного в метрах.

Поиск мест поблизости инициируется вызовом метода nearbySearch() службы PlacesService , который возвращает массив объектов 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 Адресов, не будут возвращены, если вы включите этот параметр в свой запрос. Установка 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 Адресов — это веб-служба, которая возвращает информацию о наборе мест на основе строки, например «пицца в Нью-Йорке» или «обувные магазины недалеко от Оттавы». Служба отвечает списком мест, соответствующих текстовой строке, и любым установленным смещениям местоположения. Ответ на поиск будет включать список мест. Вы можете отправить запрос Place Details для получения дополнительной информации о любом из мест в ответе.

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

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

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

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

Машинопись

// 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. () {
    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. () {
    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
Посмотреть пример

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

Детали места

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

Разместить запросы на получение подробной информации

Сведения о месте запрашиваются с помощью вызова метода 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_components', 'opening_hours', 'geometry'] . Используйте точку при указании составных значений. Например: opening_hours.weekday_text .

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

Базовый

Категория «Базовый» включает в себя следующие поля:
address_components , 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 ( устарело в библиотеке адресов, Maps JavaScript API), utc_offset_minutes , vicinity

Контакт

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

Атмосфера

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

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

Детали места Ответы

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

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

  • INVALID_REQUEST : этот запрос недействителен.
  • OK : ответ содержит действительный результат.
  • OVER_QUERY_LIMIT : веб-страница превысила квоту запросов.
  • NOT_FOUND Указанное местоположение не найдено в базе данных мест.
  • 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 ( устарело ) — это логический флаг, указывающий, закрыто ли место навсегда или временно (значение true ). Не используйте permanently_closed . Вместо этого используйте business_status , чтобы получить операционный статус предприятий.
  • plus_code (см. Открытый код местоположения и плюсовые коды ) — это закодированная ссылка на местоположение, полученная из координат широты и долготы, которая представляет собой площадь: 1/8000 градуса на 1/8000 градуса (около 14 х 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, API JavaScript Карт, вместо этого используйте utc_offset_minutes .
  • utc_offset_minutes содержит количество минут, на которое текущий часовой пояс этого места смещен от UTC. Например, для мест в Сиднее, Австралия, во время летнего времени это будет 660 (+11 часов от UTC), а для мест в Калифорнии вне летнего времени это будет -480 (-8 часов от UTC).
  • opening_hours содержит следующую информацию:
    • open_now ( устарело в библиотеке мест, Maps JavaScript API; вместо этого используйте open_hours.isOpen() . Посмотрите это видео , чтобы узнать, как использовать isOpen со сведениями о месте.) — логическое значение, указывающее, открыто ли место в текущий момент.
    • periods[] — это массив периодов открытия, охватывающий семь дней, начиная с воскресенья, в хронологическом порядке. Каждый период содержит:
      • open содержит пару объектов дня и времени, описывающих, когда открывается место:
        • day число от 0 до 6, соответствующее дням недели, начиная с воскресенья. Например, 2 означает вторник.
        • time может содержать время суток в 24-часовом формате ччмм (значения находятся в диапазоне 0000–2359). time будет указано в часовом поясе места.
      • close может содержать пару объектов дня и времени, описывающих, когда заведение закрывается. Примечание. Если место всегда открыто , раздел close в ответе будет отсутствовать. Приложения могут полагаться на то, что всегда открытый период будет представлен как open период, содержащий day со значением 0 и time со значением 0000, а также отсутствие close .
    • weekday_text — это массив из семи строк, представляющих отформатированные часы работы для каждого дня недели. Если в запросе сведений о месте был указан language параметр, служба адресов отформатирует и локализует часы работы соответствующим образом для этого языка. Порядок элементов в этом массиве зависит от параметра 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 Имя пользователя, который отправил обзор. Анонимные отзывы приписываются «пользователю Google». Если был установлен язык языка, то фраза «Пользователь Google» вернет локализованную строку.
    • author_url URL -адрес для пользователей Google+ профиля, если доступно.
    • language ИЭТ -языковой код, указывающий язык, используемый в обзоре пользователя. Это поле содержит только основной тег языка, а не вторичный тег, указывающий на страну или регион. Например, все английские обзоры помечены как «en», а не «en-au» или «en-uk» и так далее.
    • rating общего рейтинга пользователя для этого места. Это целое число, в диапазоне от 1 до 5.
    • text обзор пользователя. При просмотре местоположения с Google Place обзоры считаются необязательными; Следовательно, это поле может пусто.
  • types множества типов для этого места (например, ["political", "locality"] или ["restaurant", "lodging"] ). Этот массив может содержать несколько значений или может быть пустым. Новые значения могут быть введены без предварительного уведомления. Смотрите список поддерживаемых типов .
  • url : URL официальной страницы Google для этого места. Это страница, принадлежащая Google, которая содержит лучшую доступную информацию о месте. Приложения должны ссылаться на эту страницу или встроить эту страницу на любой экране, на котором показаны подробные результаты о месте для пользователя.
  • vicinity : упрощенный адрес для этого места, включая название улицы, номер улицы и местность, но не провинция/штат, почтовый кодекс или страна. Например, Google в Сиднее, Австралийский офис имеет vicinity ценность 5/48 Pirrama Road, Pyrmont . Собственность vicinity возвращается только для близлежащего поиска .
  • website перечисляет авторитетный веб -сайт для этого места, например, на домашней странице бизнеса.

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

Используйте компонент обзора места

Примечание. В этом примере используется библиотека с открытым исходным кодом. См. Readme для поддержки и обратной связи, связанных с библиотекой.

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

Изображение показывает вариации X-Small, Small, Medium, Hard и X-Large Size компонента обзора места, показанного на основе поля размера, введенного пользователем.
Рисунок 1: Разместите информацию о деталях с пятью различными вариациями размера

Ссылка на место с идентификатором места

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

Чтобы использовать идентификатор места в вашем приложении, вы должны сначала найти идентификатор, который доступен в PlaceResult of the Place Search или запроса деталей. Затем вы можете использовать это идентификатор места, чтобы посмотреть детали места .

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

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 позволяет добавлять высококачественный фотографический контент на ваш сайт. Фото -служба дает вам доступ к миллионам фотографий, хранящихся в местах и ​​локальной базе данных Google+. Когда вы получаете информацию о месте с помощью запроса Place Details, ссылки на фотографии будут возвращены для соответствующего фотографического контента. Бесзамянутые запросы на поиск и текстовый поиск также возвращают одну ссылку на фотографию на место, когда это уместно. Используя службу фотографий, вы можете получить доступ к указанным фотографиям и изменить размер изображения до оптимального размера для вашего приложения.

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

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

  • Ближайший поиск или текстовый поиск вернется не более одного объекта PlacePhoto .
  • Запрос деталей вернется до десяти объектов PlacePhoto .

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

Следующий фрагмент кода принимает объект Place и добавляет маркер к карте, если фотография существует. Изображение маркера по умолчанию заменяется небольшой версией фотографии.

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 включает значение в поле html_attributions , вы должны включить дополнительную атрибуцию в ваше приложение, где бы вы ни отображали изображение.