Places Service

PlacesService

google.maps.places.PlacesService

包含与搜索地点和检索地点详细信息相关的方法。

通过调用 const {PlacesService} = await google.maps.importLibrary("places") 进行访问。请参阅 Maps JavaScript API 中的库

PlacesService
PlacesService(attrContainer)
参数: 
创建 PlacesService 的新实例,以在指定容器中呈现提供方说明。
findPlaceFromPhoneNumber
findPlaceFromPhoneNumber(request, callback)
参数: 
返回值:None
根据电话号码检索地点列表。在大多数情况下,结果列表中应该只有一个项目,但如果请求不明确,则可能会返回多个结果。传递给回调的 PlaceResult 是完整 PlaceResult 的子集。您的应用可以通过调用 PlacesService.getDetails 并传递所需地点的 PlaceResult.place_id 来获取每个地点的更详细的 PlaceResult
findPlaceFromQuery
findPlaceFromQuery(request, callback)
参数: 
返回值:None
根据查询字符串检索地点列表。在大多数情况下,结果列表中应该只有一个项目,但如果请求不明确,则可能会返回多个结果。传递给回调的 PlaceResult 是完整 PlaceResult 的子集。您的应用可以通过调用 PlacesService.getDetails 并传递所需地点的 PlaceResult.place_id 来获取每个地点的更详细的 PlaceResult
getDetails
getDetails(request, callback)
参数: 
返回值:None
检索由给定 placeId 标识的地点的详细信息。
nearbySearch
nearbySearch(request, callback)
参数: 
返回值:None
根据关键字或类型检索特定地点附近的地点列表。必须始终指定位置,可以通过传递 LatLngBoundslocationradius 参数来指定。传递给回调的 PlaceResult 是完整 PlaceResult 的子集。您的应用可以发送“地点详情”请求,传递所需地点的 PlaceResult.place_id,以获取每个地点的更详细 PlaceResultPlaceSearchPagination 对象可用于提取更多结果页面(如果这是结果的最后一页或只有一页结果,则为 null)。
textSearch
textSearch(request, callback)
参数: 
返回值:None
根据查询字符串(例如“北京烤鸭”或“南京附近的鞋店”)检索地点列表。位置参数是可选参数;指定位置后,系统仅会偏向于显示附近的结果,而不会仅限于该区域内的地点。当您想使用任意字符串搜索地点,以及不想将搜索结果限制为特定位置时,请使用 textSearchPlaceSearchPagination 对象可用于提取更多结果页面(如果这是结果的最后一页或只有一页结果,则为 null)。

PlaceDetailsRequest 接口

google.maps.places.PlaceDetailsRequest 接口

要发送到 PlacesService 的地点详情查询。

placeId
类型:  string
要请求详细信息的地点的地点 ID。
fields optional
类型:  Array<string> optional
要包含在详细信息响应中的字段(将计入费用)。如果未指定任何字段或传入的是 ['ALL'],系统会返回所有可用字段并据此计费(不建议用于生产环境中的部署)。如需查看字段列表,请参阅 PlaceResult。嵌套字段可以使用点路径指定(例如 "geometry.location")。
language optional
类型:  string optional
应返回详细信息的语言的语言标识符。请参阅支持的语言列表
region optional
类型:  string optional
用户所在地区的地区代码。这可能会影响系统可能会返回哪些照片,以及可能影响其他方面。地区代码接受 ccTLD(“顶级域名”)双字符值。多数 ccTLD 代码都与 ISO 3166-1 代码相同,但也有一些需要注意的例外情况。例如,英国的 ccTLD 为“uk”(.co.uk),但其 ISO 3166-1 代码为“gb”(从技术层面来说,适用于“大不列颠及北爱尔兰联合王国”实体)。
sessionToken optional
类型:  AutocompleteSessionToken optional
用于将详情请求与自动补全会话捆绑在一起的唯一引用。

FindPlaceFromPhoneNumberRequest 接口

google.maps.places.FindPlaceFromPhoneNumberRequest 接口

要发送给 PlacesService.findPlaceFromPhoneNumber 的“通过文本搜索查找地点”请求。

fields
类型:  Array<string>
要包含在响应中的字段(系统会按这些字段进行结算)。如果传入的是 ['ALL'],系统会返回所有可用字段并据此计费(不建议用于生产环境中的部署)。如需查看字段列表,请参阅 PlaceResult。嵌套字段可以使用点路径指定(例如 "geometry.location")。
phoneNumber
类型:  string
要查询的地点的电话号码。格式必须为 E.164
language optional
类型:  string optional
应返回名称和地址的语言(如果可能)的语言标识符。请参阅支持的语言列表
locationBias optional
类型:  LocationBias optional
搜索地点时使用的偏向。结果会偏向于(但不限于)给定的 LocationBias

FindPlaceFromQueryRequest 接口

google.maps.places.FindPlaceFromQueryRequest 接口

要发送给 PlacesService.findPlaceFromQuery 的“通过文本搜索查找地点”请求。

fields
类型:  Array<string>
要包含在响应中的字段(系统会按这些字段进行结算)。如果传入的是 ['ALL'],系统会返回所有可用字段并据此计费(不建议用于生产环境中的部署)。如需查看字段列表,请参阅 PlaceResult。嵌套字段可以使用点路径指定(例如 "geometry.location")。
query
类型:  string
请求的查询。例如,地点的名称或地址。
language optional
类型:  string optional
应返回名称和地址的语言(如果可能)的语言标识符。请参阅支持的语言列表
locationBias optional
类型:  LocationBias optional
搜索地点时使用的偏向。结果会偏向于(但不限于)给定的 LocationBias

PlaceSearchRequest 接口

google.maps.places.PlaceSearchRequest 接口

要发送到 PlacesService 的地点搜索查询。

bounds optional
类型:  LatLngBounds|LatLngBoundsLiteral optional
要在其中搜索地点的边界。如果设置了 bounds,系统会忽略 locationradius
keyword optional
类型:  string optional
要与所有可用字段进行匹配的字词,包括但不限于名称、类型和地址,以及客户评价和其他第三方内容。
language optional
类型:  string optional
应返回名称和地址的语言(如果可能)的语言标识符。请参阅支持的语言列表
location optional
类型:  LatLng|LatLngLiteral optional
要在其周边搜索地点的位置。
maxPriceLevel optional
类型:  number optional
将结果限制为仅包含指定价位或更低价位的地点。有效值范围介于 0(最实惠)和 4(最昂贵)之间,包括 0 和 4。必须大于或等于 minPrice (如果指定)。
minPriceLevel optional
类型:  number optional
将结果限制为仅包含指定价位或更高价位的地点。有效值范围介于 0(最实惠)和 4(最昂贵)之间,包括 0 和 4。必须小于或等于 maxPrice(如果指定)。
name optional
类型:  string optional
等同于 keyword。此字段中的值会与 keyword 字段中的值合并,作为同一搜索字符串的一部分进行传递。
openNow optional
类型:  boolean optional
将结果限制为仅包含当前营业的地点。
radius optional
类型:  number optional
与要在其周边搜索地点的给定地点之间的距离(以米为单位)。允许的最大值为 50,000。
rankBy optional
类型:  RankBy optional
默认值RankBy.PROMINENCE
指定返回结果时要使用的排名方法。请注意,将 rankBy 设置为 DISTANCE 时,您必须指定 location,但不能指定 radiusbounds
type optional
类型:  string optional
搜索指定类型的地点。此类型会翻译为请求目标位置的本地语言,并用作查询字符串。如果还提供了查询,系统会将其附加到本地化类型字符串。系统会从响应中舍弃其他类型的结果。使用此字段可执行不依赖于语言和地区的分类搜索。有效类型详见此处

TextSearchRequest 接口

google.maps.places.TextSearchRequest 接口

要发送给 PlacesService 的文本搜索请求。

bounds optional
类型:  LatLngBounds|LatLngBoundsLiteral optional
用于在搜索地点时偏向结果的边界(可选)。如果设置了 bounds,系统会忽略 locationradius。结果不会仅限于这些边界内,但这些边界内的结果排名会更高。
language optional
类型:  string optional
应返回名称和地址的语言(如果可能)的语言标识符。请参阅支持的语言列表
location optional
类型:  LatLng|LatLngLiteral optional
用于在搜索地点时偏向结果的区域中心。
query optional
类型:  string optional
请求的查询字词。例如,地点名称(“埃菲尔铁塔”)、类别后跟地点名称(“纽约的披萨店”),或地点名称后跟地点歧义消除符(“悉尼的星巴克”)。
radius optional
类型:  number optional
用于在搜索地点时自定义调整结果的区域的半径,以米为单位。
region optional
类型:  string optional
用于使结果偏向于某个区域的区域代码。地区代码接受 ccTLD(“顶级域名”)双字符值。多数 ccTLD 代码都与 ISO 3166-1 代码相同,但也有一些需要注意的例外情况。例如,英国的 ccTLD 为“uk”(.co.uk),但其 ISO 3166-1 代码为“gb”(从技术层面来说,适用于“大不列颠及北爱尔兰联合王国”实体)。
type optional
类型:  string optional
搜索指定类型的地点。此类型会翻译为请求目标位置的本地语言,并用作查询字符串。如果还提供了查询,系统会将其附加到本地化类型字符串。系统会从响应中舍弃其他类型的结果。使用此字段可执行不依赖于语言和地区的分类搜索。有效类型详见此处

RankBy 常量

google.maps.places.RankBy 常量

PlaceSearchRequest 的排名选项。

通过调用 const {RankBy} = await google.maps.importLibrary("places") 进行访问。请参阅 Maps JavaScript API 中的库

DISTANCE 根据与地点的距离对地点搜索结果进行排名。
PROMINENCE 按地点知名度对地点结果进行排名。

LocationBias 类型定义

google.maps.places.LocationBias typedef

LocationBias 表示在搜索地点时使用的软边界或提示。结果可能来自指定区域之外。如需使用当前用户的 IP 地址作为偏差,可以指定字符串 "IP_BIAS"。注意:如果使用 Circle,则必须定义中心和半径。

LatLng|LatLngLiteral|LatLngBounds|LatLngBoundsLiteral|Circle|CircleLiteral|string

LocationRestriction 类型定义

google.maps.places.LocationRestriction typedef

LocationRestriction 表示在搜索地点时使用的严格边界。

LatLngBounds|LatLngBoundsLiteral

PlacesServiceStatus 常量

google.maps.places.PlacesServiceStatus 常量

PlacesService 在完成搜索后返回的状态。您可以按值指定这些参数,也可以使用常量的名称指定这些参数。例如 'OK'google.maps.places.PlacesServiceStatus.OK

通过调用 const {PlacesServiceStatus} = await google.maps.importLibrary("places") 进行访问。请参阅 Maps JavaScript API 中的库

INVALID_REQUEST 请求无效。
NOT_FOUND 找不到引用的地点。
OK 该响应包含有效的结果。
OVER_QUERY_LIMIT 应用已超出请求配额。
REQUEST_DENIED 应用无权使用 PlacesService
UNKNOWN_ERROR 由于服务器错误,系统无法处理 PlacesService 请求。如果您再试一次,该请求可能会成功。
ZERO_RESULTS 该请求查询不到任何结果。

PlaceSearchPagination 接口

google.maps.places.PlaceSearchPagination 接口

用于提取更多地点结果页面的对象。

hasNextPage
类型:  boolean
指示是否还有其他结果。如果存在额外的结果页面,属性值为 true
nextPage
nextPage()
参数:无
返回值:  void
提取下一页结果。使用提供给第一个搜索请求的相同回调函数。

PlaceResult 接口

google.maps.places.PlaceResult 接口

定义地点的相关信息。

address_components optional
类型:  Array<GeocoderAddressComponent> optional
此地点位置的地址组成部分集合。仅适用于 PlacesService.getDetails
adr_address optional
类型:  string optional
地点地址的 adr 微格式表示法。仅适用于 PlacesService.getDetails
aspects optional
类型:  Array<PlaceAspectRating> optional
此地点的各个方面获得的评分,基于 Google 和 Zagat 用户评价。评分范围为 0 到 30。
business_status optional
类型:  BusinessStatus optional
一个标志,表示地点的营业状态(如果该地点为商家,则表示地点是正常营业、暂停营业还是永久停业)。如果没有可用数据,搜索响应或详情响应中不会显示该标志。
formatted_address optional
类型:  string optional
地点的完整地址。
formatted_phone_number optional
类型:  string optional
地点的电话号码,其格式遵循 号码的地区惯例。仅适用于 PlacesService.getDetails
geometry optional
类型:  PlaceGeometry optional
地点的几何图形相关信息。
html_attributions optional
类型:  Array<string> optional
要针对此地点结果显示的提供方说明文本。无论请求了哪些 fields,系统始终都会返回可用的 html_attributions,并且必须显示这些 html_attributions
icon optional
类型:  string optional
指向可用于代表此地点类别的图片资源的网址。
icon_background_color optional
类型:  string optional
与地点图标搭配使用的背景颜色。另请参阅 PlaceResult.icon_mask_base_uri
icon_mask_base_uri optional
类型:  string optional
图标掩码的截断网址。通过在末尾附加文件扩展名(即 .svg.png)来访问不同的图标类型。
international_phone_number optional
类型:  string optional
地点的电话号码(采用国际电话号码格式)。国际格式包含国家/地区代码,并以加号符号 (+) 作为前缀。仅适用于 PlacesService.getDetails
name optional
类型:  string optional
地点的名称。注意:对于用户输入的地点,此字段是用户输入的原始文本。使用此类数据时请务必小心,因为恶意用户可能会尝试将其用作代码注入攻击的载体(请参阅 http://en.wikipedia.org/wiki/Code_injection)。
opening_hours optional
类型:  PlaceOpeningHours optional
定义地点的开业或打烊时间。
permanently_closed optional
类型:  boolean optional
一个标志,指明地点是永久停业还是暂时停业。如果相应地点处于运营状态,或者没有可用数据,则响应中不会包含该标志。
photos optional
类型:  Array<PlacePhoto> optional
此地点的照片。该集合最多包含 10 个 PlacePhoto 对象。
place_id optional
类型:  string optional
相应地点的唯一标识符。
plus_code optional
类型:  PlacePlusCode optional
为地点定义开放式地理编码或“Plus Code”。
price_level optional
类型:  number optional
地点的价格水平,评分范围为 0 到 4。价格水平的解读如下:
  • 0:免费
  • 1:价格低廉
  • 2:中等
  • 3:价格昂贵
  • 4:非常昂贵
rating optional
类型:  number optional
评分,介于 1.0 到 5.0 之间,基于用户对此地点的评价。
reviews optional
类型:  Array<PlaceReview> optional
此地点的评价列表。仅适用于 PlacesService.getDetails
types optional
类型:  Array<string> optional
此地点的类型数组(例如 ["political", "locality"]["restaurant", "establishment"])。
url optional
类型:  string optional
此地点的官方 Google 页面的网址。这是由 Google 拥有的页面,其中包含有关该地点的实用信息。仅适用于 PlacesService.getDetails
user_ratings_total optional
类型:  number optional
对此地点的 PlaceResult.rating 有贡献的用户评分的数量。
utc_offset optional
类型:  number optional
地点当前时区与世界协调时间 (UTC) 之间的偏移量(以分钟为单位)。例如,澳大利亚悉尼在夏令时比世界协调时间 (UTC) 早 11 小时,因此 utc_offset 将为 660。对于比世界协调时间 (UTC) 晚的时区,偏移量为负值。例如,对于佛得角,utc_offset-60。仅适用于 PlacesService.getDetails
utc_offset_minutes optional
类型:  number optional
地点当前时区与世界协调时间 (UTC) 之间的偏移量(以分钟为单位)。例如,澳大利亚悉尼在夏令时比世界协调时间 (UTC) 早 11 小时,因此 utc_offset_minutes 将为 660。对于比世界协调时间 (UTC) 晚的时区,偏移量为负值。例如,对于佛得角,utc_offset_minutes-60。仅适用于 PlacesService.getDetails
vicinity optional
类型:  string optional
地点的简化地址,包括街道名称、门牌号和市行政区,但不包括省/州、邮政编码或国家/地区。例如,Google 澳大利亚悉尼办事处的邻近值为 "48 Pirrama Road, Pyrmont"。仅适用于 PlacesService.getDetails
website optional
类型:  string optional
此地点的官方网站,例如商家主页。仅适用于 PlacesService.getDetails

PlaceAspectRating 接口

google.maps.places.PlaceAspectRating 接口

定义用户已评价的地点的某个方面的信息。

rating
类型:  number
此方面评分。对于单个评价,此值是一个介于 0 到 3 之间的整数。对于地点的汇总评分,此值为 0 到 30 之间的整数。
type
类型:  string
相应方面类型。例如 "food""decor""service""overall"

BusinessStatus 常量

google.maps.places.BusinessStatus 常量

PlaceResult 中返回的地点(如果是商家)的营业状态(指示地点是正常营业、暂时停业还是永久停业)。您可以按值或常量名称(例如 'OPERATIONAL'google.maps.places.BusinessStatus.OPERATIONAL)指定这些值。

通过调用 const {BusinessStatus} = await google.maps.importLibrary("places") 进行访问。请参阅 Maps JavaScript API 中的库

CLOSED_PERMANENTLY 商家已永久停业。
CLOSED_TEMPORARILY 商家暂时停业。
OPERATIONAL 商家正在正常运营。

PlaceGeometry 接口

google.maps.places.PlaceGeometry 接口

定义地点几何图形的相关信息。

location optional
类型:  LatLng optional
地点的位置。
viewport optional
类型:  LatLngBounds optional
在地图上显示此地点时的首选视口。如果地点的首选视口未知,此属性将为 null。仅适用于 PlacesService.getDetails

PlaceOpeningHours 接口

google.maps.places.PlaceOpeningHours 接口

定义地点的营业时间相关信息。

open_now optional
类型:  boolean optional
地点当前是否营业。
periods optional
类型:  Array<PlaceOpeningHoursPeriod> optional
涵盖一周每个工作日的营业时段,从星期日开始,按时间顺序排列。不包括相应地点未营业的日期。仅适用于 PlacesService.getDetails
weekday_text optional
类型:  Array<string> optional
包含七个字符串的数组,用于以特定格式表示一周内每天的营业时间。地点服务会根据当前语言设置营业时间格式,并进行本地化。此数组中元素的顺序取决于语言。有些语言以星期一作为一周的开始,有些语言则以星期日作为开始。仅适用于 PlacesService.getDetails。其他调用可能会返回空数组。
isOpen
isOpen([date])
参数: 
  • dateDate optional
返回值:  boolean|undefined
检查相应地点目前(未过任何日期)或指定日期是否营业。如果此地点没有 PlaceResult.utc_offset_minutesPlaceOpeningHours.periods,则返回 undefinedPlaceOpeningHours.periods 仅通过 PlacesService.getDetails 提供)。此方法不会考虑例外时间(例如节假日时间)。

PlaceOpeningHoursPeriod 接口

google.maps.places.PlaceOpeningHoursPeriod 接口

定义与地点营业时间相关的结构化信息。注意:如果某个地点全天营业,响应中将缺少 close 部分。客户端可以通过以下方式表示全天营业:将 open 中的 day 设置为 0,将 time 设置为 "0000",并且不包含 close

open
地点的营业时间。
close optional
类型:  PlaceOpeningHoursTime optional
地点的打烊时间。

PlaceOpeningHoursTime 接口

google.maps.places.PlaceOpeningHoursTime 接口

定义地点的开业或打烊时间。

day
类型:  number
星期几,表示为 [0, 6] 范围内的数字,从星期日开始。例如,2 表示星期二。
hours
类型:  number
PlaceOpeningHoursTime.time 的时数(一个数字),范围为 [0, 23]。系统将按地点的时区报告此值。
minutes
类型:  number
PlaceOpeningHoursTime.time 的分钟数,是一个介于 [0, 59] 范围内的数字。系统将按地点的时区报告此值。
time
类型:  string
一天中的时段,采用 24 小时制“hhmm”格式。值应在 ["0000", "2359"] 范围内。系统将按地点的时区报告时间。
nextDate optional
类型:  number optional
表示此 PlaceOpeningHoursTime 的下一次出现时间的时间戳(以从公元纪年开始计算的毫秒数表示,适合与 new Date() 搭配使用)。它是根据一周中的 PlaceOpeningHoursTime.dayPlaceOpeningHoursTime.timePlaceResult.utc_offset_minutes 计算得出的。如果 PlaceResult.utc_offset_minutesundefined,则 nextDate 将为 undefined

PlacePlusCode 接口

google.maps.places.PlacePlusCode 接口

为地点定义开放式地理编码或“Plus Code”。Plus Code 可用于在没有街道地址的地点(例如建筑物未编号,或者街道未命名)取代街道地址。

global_code
类型:  string
一个 Plus 代码,其面积为 1/8,000 度 x 1/8,000 度。例如 "8FVC9G8F+5W"
compound_code optional
类型:  string optional
一个 plus 代码,表示 1/8000 度乘 1/8000 度的区域,其中前四位字符(区域代码)会被舍弃,并替换为地理位置描述。例如 "9G8F+5W Zurich, Switzerland"。如果找不到可用于缩短代码的适当地区,则会省略此字段。

PlacePhoto 接口

google.maps.places.PlacePhoto 接口

表示地点的照片元素。

height
类型:  number
照片的高度(以像素为单位)。
html_attributions
类型:  Array<string>
要为此照片显示的提供方信息文本。
width
类型:  number
照片的宽度(以像素为单位)。
getUrl
getUrl([opts])
参数: 
返回值:  string
返回与指定选项对应的图片网址。

PhotoOptions 接口

google.maps.places.PhotoOptions 接口

定义照片请求选项。

maxHeight optional
类型:  number optional
返回图片的最大高度(以像素为单位)。
maxWidth optional
类型:  number optional
返回的图片的最大宽度(以像素为单位)。

PlaceReview 接口

google.maps.places.PlaceReview 接口

表示对地点的单条评价。

author_name
类型:  string
评价者的姓名。
language
类型:  string
表示此评价所用语言的 IETF 语言代码。请注意,此代码仅包含主要语言标记,不包含任何表示国家或地区的辅助标记。例如,所有英语评价都标记为 'en',而不是“en-AU”或“en-UK”。
profile_photo_url
类型:  string
指向评价者个人资料图片的网址。
relative_time_description
类型:  string
格式化后的近期时间字符串,以适合相应语言和国家/地区的形式表示相对于当前时间的评价时间。例如 "a month ago"
text
类型:  string
评价文本。
time
类型:  number
评价的时间戳,以秒为单位,自公元纪年开始算起。
aspects optional
类型:  Array<PlaceAspectRating> optional
评价所评分的方面。评分,评分范围为 0 到 3。
author_url optional
类型:  string optional
指向评价者个人资料的网址。如果评价者的个人资料不可用,此值将为 undefined
rating optional
类型:  number optional
此评价的评分,介于 1.0 到 5.0 之间(包括这两个数值)。