Обзор
Функции библиотеки мест и 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:
- Перейдите в облачную консоль Google .
- Нажмите кнопку «Выбрать проект» , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите « Открыть» .
- В списке API на информационной панели найдите Places API .
- Если вы видите API Places в списке, значит, он уже включен. Если API нет в списке, включите его:
- В верхней части страницы выберите ВКЛЮЧИТЬ API И СЕРВИСЫ , чтобы отобразить вкладку «Библиотека» . Либо в меню слева выберите «Библиотека» .
- Найдите Places API , затем выберите его из списка результатов.
- Выберите ВКЛЮЧИТЬ . По завершении процесса 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:- Перейдите в облачную консоль Google .
- Щелкните раскрывающийся список проекта и выберите проект, содержащий ключ API, который вы хотите защитить.
- Нажмите кнопку меню
и выберите Платформа Google Maps > Учетные данные .
- На странице «Учетные данные» щелкните имя ключа API, который вы хотите защитить.
- На странице «Ограничить и переименовать ключ API» установите ограничения:
- Ограничения API
- Выберите Ограничить ключ .
- Нажмите «Выбрать API» и выберите Maps JavaScript API и Places API .
(Если какой-либо из API-интерфейсов отсутствует в списке, его необходимо включить .)
- Нажмите СОХРАНИТЬ .
Ограничения и политики использования
Квоты
Библиотека Places разделяет квоту использования с Places API, как описано в документации по ограничениям использования для Places API.
Политика
Использование библиотеки Places и Maps JavaScript API должно соответствовать политикам, описанным для Places API .
Поиск мест
С помощью службы «Метки» вы можете выполнять следующие виды поиска:
- Функция «Найти место из запроса» возвращает место на основе текстового запроса (например, названия или адреса места).
- Функция «Найти место по номеру телефона» возвращает место по номеру телефона.
- Поиск поблизости возвращает список мест поблизости на основе местоположения пользователя.
- Текстовый поиск возвращает список близлежащих мест на основе строки поиска, например. "Пицца".
- Запросы Place Details возвращают более подробную информацию о конкретном месте, включая отзывы пользователей.
Возвращенная информация может включать заведения, такие как рестораны, магазины и офисы, а также результаты «геокодирования», которые указывают адреса, политические районы, такие как города и другие достопримечательности.
Найти запросы мест
Запрос «Найти место» позволяет искать место по текстовому запросу или номеру телефона. Существует два типа запроса «Найти место»:
Найти место по запросу
Функция «Найти место из запроса» принимает текстовый ввод и возвращает место. Входными данными могут быть любые данные о месте, например название компании или адрес. Чтобы выполнить запрос «Найти место из запроса», вызовите метод 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
, определяющим прямоугольную область поиска. Максимальное поддерживаемое диагональное расстояние для зоны границ составляет примерно 100 000 метров. -
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
, определяющим прямоугольную область поиска. Максимальное поддерживаемое диагональное расстояние для зоны границ составляет примерно 100 000 метров. -
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.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;
Попробуйте образец
Детали места
Помимо предоставления списка мест в пределах области, служба «Места» также может возвращать подробную информацию о конкретном месте. После того как место возвращается в ответ на поиск места, его идентификатор места можно использовать для запроса дополнительных сведений об этом месте, таких как полный адрес, номер телефона, рейтинг пользователей, отзывы и т. д.
Разместить запросы на получение подробной информации
Сведения о месте запрашиваются с помощью вызова метода 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
: текстовый идентификатор, который уникально идентифицирует место и может использоваться для извлечения информации о месте с помощью запроса о деталях места . Узнайте больше о том, как ссылаться на место с идентификатором места . -
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 компонента обзора места, показанного на основе поля размера, введенного пользователем.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-overview-sizes.png?authuser=6&hl=ru)
Ссылка на место с идентификатором места
Идентификатор места - это уникальная ссылка на место на карте 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+. Когда вы получите информацию о размещении, используя запрос на информацию о местах, ссылки на фотографии будут возвращены для соответствующего фотографического контента. Бесзамянутые запросы на поиск и текстовый поиск также возвращают одну ссылку на фотографию на место, когда это уместно. Используя фото службу, вы можете получить доступ к указанным фотографиям и изменить размер изображения до оптимального размера для вашего приложения.
Массив объектов 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
, вы должны включить дополнительную атрибуцию в ваше приложение, где бы вы ни отображали изображение.