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
根据查询字符串(例如,“北京烤鸭”或“南京附近的鞋店”)检索地点列表。Location 参数是可选的;如果指定了 location,则结果仅偏向于附近的结果,而不是仅限于该区域内的地点。如果您想使用任意字符串搜索地点,以及您可能不希望将搜索结果限制在特定位置,请使用 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 (如果指定)。 |
|
类型:
string optional 等同于 keyword 。此字段中的值会与 keyword 字段中的值合并,作为同一搜索字符串的一部分进行传递。 |
openNow optional |
类型:
boolean optional 将结果限制为仅显示当前正在营业的地点。 |
radius optional |
类型:
number optional 要在其内搜索“地点”的指定位置的距离(以米为单位)。允许的最大值为 50 000。 |
rankBy optional |
类型:
RankBy optional 指定返回结果时要使用的排名方法。请注意,将 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 typedef
google.maps.places.LocationBias
typedef
LocationBias 表示搜索地点时要使用的软边界或提示。结果可能来自指定区域以外的地方。如需将当前用户的 IP 地址用作偏差,可以指定字符串 "IP_BIAS"
。注意:如果使用 Circle
,则必须定义中心和半径。
LatLng|LatLngLiteral|LatLngBounds|LatLngBoundsLiteral|Circle|CircleLiteral|string
LocationRestriction typedef
google.maps.places.LocationRestriction
typedef
LocationRestriction 表示搜索地点时要使用的严格边界。
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() 参数:无
返回值:None
获取下一页结果。使用提供给第一个搜索请求的同一回调函数。 |
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 ,并且必须显示。 |
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_jection)。 |
opening_hours optional |
类型:
PlaceOpeningHours optional 定义地点的打开或关闭时间。 |
|
类型:
boolean optional 一个标记,指明该地点是永久停业还是暂时停业。如果该地点可营业,或者没有可用数据,响应中将没有该标志。 |
photos optional |
类型:
Array<PlacePhoto> optional 此地点的照片。该集合最多包含十个 PlacePhoto 对象。 |
place_id optional |
类型:
string optional 地点的唯一标识符。 |
plus_code optional |
类型:
PlacePlusCode optional 定义地点的营业地址代码或“Plus Codes”。 |
price_level optional |
类型:
number optional 该地方的价格水平(范围为 0 到 4)。价位解释如下:
|
rating optional |
类型:
number optional 一个评分(在 1.0 到 5.0 之间),这是根据用户对该地方的评价得出。 |
reviews optional |
类型:
Array<PlaceReview> optional 此“地方”的评价列表。仅适用于 PlacesService.getDetails 。 |
types optional |
类型:
Array<string> optional |
url optional |
类型:
string optional 此地点的官方 Google 页面的网址。这是由 Google 拥有的页面,其中包含有关该地方的最佳可用信息。仅适用于 PlacesService.getDetails 。 |
user_ratings_total optional |
类型:
number optional 让此地点的 PlaceResult.rating 获得的用户评分数量。 |
|
类型:
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 澳大利亚悉尼办事处的 vicinity 值为 "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
接口
定义有关地点营业时间的信息。
属性 | |
---|---|
|
类型:
boolean optional 地点当前是否正在营业。 |
periods optional |
类型:
Array<PlaceOpeningHoursPeriod> optional 每周每天的营业时间,从星期日开始,按时间顺序排列。相应地点未营业的日期不包括在内。仅适用于 PlacesService.getDetails 。 |
weekday_text optional |
类型:
Array<string> optional 由七个字符串组成的数组,以特定格式表示一周内每天的营业时间。地点服务会根据当前语言对营业时间进行适当的格式设置和本地化。此数组中元素的顺序取决于语言。有些语言以星期一作为一周的开始,有些语言则以星期日作为开始。仅适用于 PlacesService.getDetails 。其他调用可能会返回空数组。 |
方法 | |
---|---|
isOpen |
isOpen([date]) 参数:
返回值:
boolean|undefined 检查地点是现在营业(未传递日期时)还是在指定日期营业。如果此地点没有 PlaceResult.utc_offset_minutes 或 PlaceOpeningHours.periods ,则返回 undefined (只能通过 PlacesService.getDetails 使用 PlaceOpeningHours.periods )。此方法不会考虑异常营业时间,例如节假日营业时间。 |
PlaceOpeningHoursPeriod 接口
google.maps.places.PlaceOpeningHoursPeriod
接口
定义有关地点营业时间的结构化信息。注意:如果地点全天营业,响应中将缺少 close
部分。客户端可以用 open
期间表示“全天营业”,其中包含值为 0
的 day
,值为 "0000"
的 time
,且不包含 close
。
属性 | |
---|---|
open |
地点的营业时间。 |
close optional |
类型:
PlaceOpeningHoursTime optional 地点的打烊时间。 |
PlaceOpeningHoursTime 接口
google.maps.places.PlaceOpeningHoursTime
接口
定义地点的打开或关闭时间。
属性 | |
---|---|
day |
类型:
number 一周中的某天,以 [ 0 , 6 ] 范围内的数字表示,从星期日开始。例如,2 表示星期二。 |
hours |
类型:
number |
minutes |
类型:
number |
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 Codes”。Plus Codes 可用于在没有街道地址的地点(例如建筑物未编号,或者街道未命名)取代街道地址。
属性 | |
---|---|
global_code |
类型:
string 一个 Plus Code,值为 1/8000 度,表示面积为 1/8000 度。例如 "8FVC9G8F+5W" 。 |
compound_code optional |
类型:
string optional 一个 Plus Code,包含 1/8000 度、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 评价的时间戳,以自纪元以来的秒数表示。 |
|
类型:
Array<PlaceAspectRating> optional 评价所评分的方面。评分范围,范围为 0 到 3 分。 |
author_url optional |
类型:
string optional 指向评价者个人资料的网址。如果评价者的个人资料不可用,此值将为 undefined 。 |
rating optional |
类型:
number optional 此评价的评分,1.0 到 5.0 之间的数字(含 1.0 和 5.0)。 |