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
根据关键字或类型检索特定地点附近的地点列表。必须始终指定位置，可以通过传递 LatLngBounds 或 location 和 radius 参数来指定。传递给回调的 PlaceResult 是完整 PlaceResult 的子集。您的应用可以发送“地点详情”请求，传递所需地点的 PlaceResult.place_id，以获取每个地点的更详细 PlaceResult。PlaceSearchPagination 对象可用于提取更多结果页面（如果这是结果的最后一页或只有一页结果，则为 null）。
textSearch
textSearch(request, callback)
参数： 
返回值：None
根据查询字符串（例如“北京烤鸭”或“南京附近的鞋店”）检索地点列表。位置参数是可选参数；指定位置后，系统仅会偏向于显示附近的结果，而不会仅限于该区域内的地点。当您想使用任意字符串搜索地点，以及不想将搜索结果限制为特定位置时，请使用 textSearch。PlaceSearchPagination 对象可用于提取更多结果页面（如果这是结果的最后一页或只有一页结果，则为 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，系统会忽略 location 和 radius。
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，但不能指定 radius 或 bounds。
type optional
类型：  string optional
搜索指定类型的地点。此类型会翻译为请求目标位置的本地语言，并用作查询字符串。如果还提供了查询，系统会将其附加到本地化类型字符串。系统会从响应中舍弃其他类型的结果。使用此字段可执行不依赖于语言和地区的分类搜索。有效类型详见此处。

TextSearchRequest 接口

google.maps.places.TextSearchRequest 接口

要发送给 PlacesService 的文本搜索请求。
bounds optional
类型：  LatLngBounds|LatLngBoundsLiteral optional
用于在搜索地点时偏向结果的边界（可选）。如果设置了 bounds，系统会忽略 location 和 radius。结果不会仅限于这些边界内，但这些边界内的结果排名会更高。
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])
参数： 
  • date：Date optional
返回值：  boolean|undefined
检查相应地点目前（未过任何日期）或指定日期是否营业。如果此地点没有 PlaceResult.utc_offset_minutes 或 PlaceOpeningHours.periods，则返回 undefined（PlaceOpeningHours.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.day、PlaceOpeningHoursTime.time 和 PlaceResult.utc_offset_minutes 计算得出的。如果 PlaceResult.utc_offset_minutes 为 undefined，则 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 之间（包括这两个数值）。