Places Service

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

PlacesService

google.maps.places.PlacesService

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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

PlaceDetailsRequest 接口

google.maps.places.PlaceDetailsRequest接口

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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 的查找地点。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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 的查找地点。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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

PlaceSearchRequest 接口

google.maps.places.PlaceSearchRequest接口

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

bounds optional
用于搜索地点的范围。如果设置了 boundslocationradius 都会被忽略。
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
与指定营业地点的搜索距离(以米为单位)。允许的最大值为 50000。
rankBy optional
类型RankBy optional
指定返回结果时使用的排名方法。请注意,当 rankBy 设置为 DISTANCE 时,您必须指定 location,但不能指定 radiusbounds
type optional
类型string optional
搜索指定类型的地点。类型会转换为请求的目标位置的当地语言,并用作查询字符串。如果还提供了查询,则该查询会连接到经过本地化的类型字符串。不同类型的结果会从响应中移除。使用此字段执行与语言和区域无关的分类搜索。此处提供了有效的类型。

TextSearchRequest 接口

google.maps.places.TextSearchRequest接口

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

bounds optional
搜索地点时用于使结果偏向的边界(可选)。如果设置了 boundslocationradius 都会被忽略。结果不会局限于这些边界以内;但其结果将排在更前面。
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 的排名选项。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

DISTANCE 排名按地点与地点的距离排序。
PROMINENCE 排名是由搜索结果的显眼程度决定的。

LocationBias typedef

google.maps.places.LocationBias类型定义符

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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

LocationRestriction 类型定义

google.maps.places.LocationRestriction类型定义符

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

LatLngBounds|LatLngBoundsLiteral

PlacesServiceStatus 常量

google.maps.places.PlacesServiceStatus 常量

PlacesService 在搜索完成后返回的状态。可以通过指定值或使用常量名称来指定变量。例如,'OK'google.maps.places.PlacesServiceStatus.OK

需要提供 &libraries=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接口

用于提取地点结果页面的其他对象。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

hasNextPage
类型boolean
指明是否有更多结果。true
nextPage
nextPage()
参数:无
返回值:无
获取下一页结果。使用与第一个搜索请求相同的回调函数。

PlaceResult 接口

google.maps.places.PlaceResult接口

定义关于地点的信息。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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_注入 ion)。
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_offset660。对于采用世界协调时间 (UTC) 的时区,偏移量为负。例如,佛得角的 utc_offset-60。仅适用于 PlacesService.getDetails
utc_offset_minutes optional
类型number optional
相对于地点当前时区的世界协调时间 (UTC) 的偏移量(以分钟为单位)。例如,澳大利亚悉尼夏令时比世界协调时间 (UTC) 早 11 小时,因此 utc_offset_minutes660。对于采用世界协调时间 (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接口

定义与用户已评价的地点某一方面相关的信息。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

rating
类型number
这方面的评分。对于单条评价,此字段为 0 到 3 之间的整数。对于地点的汇总评分,请使用 0 到 30 之间的整数。
type
类型string
宽高比类型。例如 "food""decor""service""overall"

BusinessStatus 常量

google.maps.places.BusinessStatus 常量

商家信息的商家信息状态(如果是商家),在 PlaceResult 中返回(表示该地点是正常营业还是暂停营业或永久停业)。请按值或常量名称(例如:'OPERATIONAL'google.maps.places.BusinessStatus.OPERATIONAL)指定这些内容。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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

PlaceGeometry 接口

google.maps.places.PlaceGeometry接口

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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

PlaceOpeningHours 接口

google.maps.places.PlaceOpeningHours接口

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

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

open_now optional
类型boolean optional
该地点当前是否营业。
periods optional
类型Array<PlaceOpeningHoursPeriod> optional
一周中每一天的开放时段,从星期日开始,按时间顺序排列。不包含该地点未营业的天数。仅适用于 PlacesService.getDetails
weekday_text optional
类型Array<string> optional
由 7 个字符串组成的数组,这些字符串表示一周中每一天的格式化营业时间。地点服务会根据当前语言对营业时间进行适当格式化和本地化。此数组中元素的顺序取决于语言。有些语言从周一开始,有些则从周日开始。仅适用于 PlacesService.getDetails。其他调用可能会返回空数组。
isOpen
isOpen([date])
参数
  • dateDate optional
返回值boolean|undefined
检查该地点目前在营业(未经过任何日期)还是在指定的日期。如果此地点没有PlaceResult.utc_offset_minutesPlaceOpeningHours.periods,则返回undefined(仅PlacesService.getDetails提供 PlaceOpeningHours.periods)。此方法无需考虑特殊营业时间,例如节假日营业时间。

PlaceOpeningHoursPeriod 接口

google.maps.places.PlaceOpeningHoursPeriod接口

定义关于地点营业时间的结构化信息。注意:如果地点始终处于打开状态,响应中将缺少 close 部分。客户端可以依赖始终开启的 open 时间段来表示其包含 day(值为 0)和 time(值为 "0000"),而不是 close

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

open
该地点的开业时间。
close optional
类型PlaceOpeningHoursTime optional
该地点的打烊时间。

PlaceOpeningHoursTime 接口

google.maps.places.PlaceOpeningHoursTime接口

定义地点的开始或关闭时间。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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 的下次发生时间的时间戳(以毫秒为单位,从 Epoch 起算,适合与 new Date() 配合使用)。此数据根据周的 PlaceOpeningHoursTime.dayPlaceOpeningHoursTime.timePlaceResult.utc_offset_minutes 计算得出。如果 PlaceResult.utc_offset_minutesundefined,则 nextDate 将为 undefined

PlacePlusCode 接口

google.maps.places.PlacePlusCode接口

定义地点的开放式地理位置代码或“Plus 代码”。Plus 代码可用于替换不存在的地点(建筑物没有编号或街道未命名)中的街道地址。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

global_code
类型string
包含度数 1/8000 度 x 1/8000 度区域的 Plus 代码。例如 "8FVC9G8F+5W"
compound_code optional
类型string optional
度数的 1/8000 x 1/8000 度的加号,前四个字符(区号)已删除,并替换为市行政区说明。例如,"9G8F+5W Zurich, Switzerland"。如果找不到可以缩短代码的合适市行政区,此字段将被忽略。

PlacePhoto 接口

google.maps.places.PlacePhoto接口

表示地点的照片元素。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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

PhotoOptions 接口

google.maps.places.PhotoOptions接口

定义照片请求选项。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

maxHeight optional
类型number optional
所返回图片的高度上限(以像素为单位)。
maxWidth optional
类型number optional
所返回图片的宽度上限(以像素为单位)。

PlaceReview 接口

google.maps.places.PlaceReview接口

表示对某个地点的单条评价。

需要提供 &libraries=places 网址参数。请参阅 Maps JavaScript API 中的库

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(含 1.0 和 5.0)之间的数字。