一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Places API Web Service

为帮助您起步,我们将引导您在 Google 开发者控制台中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Places API Web Service
  3. 创建相应密钥
继续

地点详情

从地点搜索获得 place_idreference 之后,您可以通过发起地点详情请求来请求有关特定场所或景点的更多详情。地点详情请求返回有关指定地点的更全面信息,例如完整地址、电话号码、用户评分和评论。

地点详情请求

地点详情请求是一个 HTTP URL,其格式如下:

https://maps.googleapis.com/maps/api/place/details/output?parameters

其中,output 可以是以下值之一:

  • json(推荐)指示以 JavaScript 对象标记 (JSON) 输出
  • xml 指示以 XML 格式输出

系统要求提供特定参数才能发起搜索请求。依照 URL 的标准,所有参数都使用“与”字符 (&) 分隔。下面枚举了各个参数及其可能的值。

  • key必填)– 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。这样,通过您的应用添加的地点可立即供您的应用使用。如需了解详细信息,请参阅获取密钥
  • placeidreference必须提供两者之一,但不必两个都提供):
    • placeid - 从地点搜索中返回的、用于唯一标识地点的文本标识符。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
    • reference - 从地点搜索中返回的、用于唯一标识地点的文本标识符。reference 现已被弃用,取而代之的是 placeid。请参阅此页的弃用通告
可选参数
  • extensions可选)– 表示地点详情响应是否应包括附加字段。附加字段可以包括需要附加许可证的高级数据,或者通常很少请求的值。Extensions 参数目前处于实验阶段。Extensions 参数支持的值为:
    • review_summary 包括由 Google 编辑人员挑选的丰富而又简洁的评论。
  • language可选)– 语言代码,表示返回结果所应使用的语言(如提供该语言的话)。请注意,有些字段可能无法以所请求的语言显示。请参阅支持的语言列表及其代码。请注意,我们会经常更新支持的语言,因此,此列表可能并不全面。

以下是通过 placeid 请求地点的详情的示例:

https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4&key=YOUR_API_KEY

请注意,您需要将此示例中的密钥替换为您自己的 API 密钥,才能使该请求在您的应用中发挥作用。

以下示例使用已弃用的 reference 参数:

https://maps.googleapis.com/maps/api/place/details/json?reference=CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g&key=YOUR_API_KEY

地点详情响应

地点详情响应的返回格式通过请求 URL 路径中的 output 标志指定。


JSON
{
   "html_attributions" : [],
   "result" : {
      "address_components" : [
         {
            "long_name" : "48",
            "short_name" : "48",
            "types" : [ "street_number" ]
         },
         {
            "long_name" : "Pirrama Road",
            "short_name" : "Pirrama Road",
            "types" : [ "route" ]
         },
         {
            "long_name" : "Pyrmont",
            "short_name" : "Pyrmont",
            "types" : [ "locality", "political" ]
         },
         {
            "long_name" : "NSW",
            "short_name" : "NSW",
            "types" : [ "administrative_area_level_1", "political" ]
         },
         {
            "long_name" : "AU",
            "short_name" : "AU",
            "types" : [ "country", "political" ]
         },
         {
            "long_name" : "2009",
            "short_name" : "2009",
            "types" : [ "postal_code" ]
         }
      ],
      "formatted_address" : "48 Pirrama Road, Pyrmont NSW, Australia",
      "formatted_phone_number" : "(02) 9374 4000",
      "geometry" : {
         "location" : {
           "lat" : -33.8669710,
           "lng" : 151.1958750
         },
         "viewport" : {
            "northeast" : {
               "lat" : -33.8665053,
               "lng" : 151.1960371
            },
            "southwest" : {
               "lat" : -33.8669293,
               "lng" : 151.1952183
            }
         }
      },
      "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "id" : "4f89212bf76dde31f092cfc14d7506555d85b5c7",
      "international_phone_number" : "+61 2 9374 4000",
      "name" : "Google Sydney",
      "place_id" : "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "scope" : "GOOGLE",
      "alt_ids" : [
         {
            "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
            "scope" : "APP"
         }
      ],
      "rating" : 4.70,
      "reference" : "CnRsAAAA98C4wD-VFvzGq-KHVEFhlHuy1TD1W6UYZw7KjuvfVsKMRZkbCVBVDxXFOOCM108n9PuJMJxeAxix3WB6B16c1p2bY1ZQyOrcu1d9247xQhUmPgYjN37JMo5QBsWipTsnoIZA9yAzA-0pnxFM6yAcDhIQbU0z05f3xD3m9NQnhEDjvBoUw-BdcocVpXzKFcnMXUpf-nkyF1w",
      "reviews" : [
         {
            "aspects" : [
               {
                  "rating" : 3,
                  "type" : "quality"
               }
            ],
            "author_name" : "Simon Bengtsson",
            "author_url" : "https://plus.google.com/104675092887960962573",
            "language" : "en",
            "rating" : 5,
            "text" : "Just went inside to have a look at Google. Amazing.",
            "time" : 1338440552869
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Felix Rauch Valenti",
            "author_url" : "https://plus.google.com/103291556674373289857",
            "language" : "en",
            "rating" : 5,
            "text" : "Best place to work :-)",
            "time" : 1338411244325
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Chris",
            "language" : "en",
            "rating" : 5,
            "text" : "Great place to work, always lots of free food!",
            "time" : 1330467089039
         }
      ],
      "types" : [ "establishment" ],
      "url" : "http://maps.google.com/maps/place?cid=10281119596374313554",
      "vicinity" : "48 Pirrama Road, Pyrmont",
      "website" : "http://www.google.com.au/"
   },
   "status" : "OK"
}
      
XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceDetailsResponse>
 <status>OK</status>
 <result>
  <name>Google Sydney</name>
  <vicinity>48 Pirrama Road, Pyrmont</vicinity>
  <type>establishment</type>
  <formatted_phone_number>(02) 9374 4000</formatted_phone_number>
  <formatted_address>48 Pirrama Road, Pyrmont NSW, Australia</formatted_address>
  <address_component>
   <long_name>48</long_name>
   <short_name>48</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Pirrama Road</long_name>
   <short_name>Pirrama Road</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Pyrmont</long_name>
   <short_name>Pyrmont</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>NSW</long_name>
   <short_name>NSW</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>AU</long_name>
   <short_name>AU</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>2009</long_name>
   <short_name>2009</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
     <lat>-33.8669710</lat>
     <lng>151.1958750</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8669293</lat>
     <lng>151.1952183</lng>
    </southwest>
    <northeast>
     <lat>-33.8665053</lat>
     <lng>151.1960371</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.7</rating>
  <url>http://maps.google.com/maps/place?cid=10281119596374313554</url>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png</icon>
  <place_id>ChIJN1t_tDeuEmsRUsoyG83frY4</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CnRsAAAAoGXc0eAcQOoO1A7sU58repRnghwM5q7UtsZFhVtjYtfKN_LFAPhdhBfUAU8m0EzeSyP0cDBi7kazZwNjlIMUqktqIanMiymuRDS8c539M6KCJNUMkjw22WXxtl3QoR25fIf-7YJnpza6bMIuFZ1CKBIQuBsbXu8xkbUNofECCkdvmxoU5k3Lpbr8XNCbofIKtsZxj8GloGA</reference>
  <id>4f89212bf76dde31f092cfc14d7506555d85b5c7</id>
  <international_phone_number>+61 2 9374 4000</international_phone_number>
  <website>http://www.google.com.au/</website>
  <review>
   <time>1338440552869</time>
   <text>Just went inside to have a look at Google. Amazing.</text>
   <author_name>Simon Bengtsson</author_name>
   <author_url>https://plus.google.com/104675092887960962573</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1338411244325</time>
   <text>Best place to work :-)</text>
   <author_name>Felix Rauch Valenti</author_name>
   <author_url>https://plus.google.com/103291556674373289857</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1330467089039</time>
   <text>Great place to work, always lots of free food!</text>
   <author_name>Chris</author_name>
   <author_url>https://maps.google.com/maps/user?uid=211457841236072500285</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
 </result>
</PlaceDetailsResponse>

JSON 响应包含三个根元素:

  • "status" 包含请求的元数据。请参阅下面的状态代码
  • "result" 包含有关所请求地点的详细信息。有关这些结果的详情,请参阅地点详情结果
  • "html_attributions" 包含一组有关此列表的提供方说明,这些说明必须显示给用户。

请参阅使用 Javascript 处理 JSON,了解如何解析 JSON 响应。

XML 响应包含一个 <PlaceDetailsResponse> 和三个顶级元素:

  • <status> 包含请求的元数据。请参阅状态代码
  • <result> 元素包含有关某个场所的详细信息。有关这些结果的详情,请参阅地点详情结果
  • <html_attributions> 包含一组必须向用户显示的提供方说明。

如需了解输出处理的推荐设计模式,请参阅使用 XPath 解析 XML

状态代码

地点响应对象中的 "status" 字段包含请求的状态,还可包含调试信息,以帮助您查出地点请求失败的原因。"status" 字段可以包含以下值:

  • OK 表示未出现错误,成功检测到地点,并且至少返回一个结果。
  • UNKNOWN_ERROR 表示服务器端错误;重试可能会成功。
  • ZERO_RESULTS 表示引用有效,但是不再引用有效的结果。如果场所不再经营,可能会出现此状态。
  • OVER_QUERY_LIMIT 表示您已超出配额。
  • REQUEST_DENIED 表示系统已拒绝您的请求,这通常是因为缺少有效的 key 参数。
  • INVALID_REQUEST 一般表示缺少查询 (reference)。
  • NOT_FOUND 表示在 Places 数据库中未找到引用的位置。

错误消息

当 Google 地点服务返回 OK 以外的状态代码时,在详情响应对象中可能会包含附加的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

地点详情结果

当“地点”服务从详情请求中返回结果时,会将这些结果放在一个 result 数组中。每个结果均可能包含以下字段:

  • address_components[] 是一个数组,其中包含用于构成给定地址的各个地址组成部分。例如,地址“111 8th Avenue, New York, NY”包含以下地址组成部分:“111”(街道号)、“8th Avenue”(道路)、“New York”(城市)和“NY”(美国的一个州)。通常,每个 address_component 均包含:
    • types[],一个表示地址组成部分类型的数组。
    • long_name 是地址组成部分的完整文本说明或名称。
    • short_name 是地址组成部分的文本名称缩写(如有)。例如,Alaska 州的地址组成部分可以有 long_name“Alaska”和 short_name“AK”(使用双字母邮政缩写表示)。
  • formatted_address 是一个包含此地点可人工读取的地址的字符串。通常此地址相当于“邮政地址”,有时会因国家/地区而异。此地址一般由一个或多个 address_component 字段组成。
  • formatted_phone_number 包含此地点以其当地格式表示的电话号码。例如,Google 澳大利亚悉尼分公司的 formatted_phone_number(02) 9374 4000
  • geometry 包含以下信息:
    • location 包含此地点的地理编码经度、纬度值。
    • viewport 包含在地图上将此地点显示为 LatLngBounds(如果已知)时的首选视口。
  • icon 包含推荐图标的网址,在地图上显示此结果时可能会向用户显示此图标。
  • id 包含指示此地点的唯一稳定标识符。此标识符可能无法用于检索有关此地点的信息,但是可用于合并有关此地点的数据,并在不同的搜索中验证地点的同一性。由于 ID 偶尔会变化,因此,建议您将存储的地点 ID 与后来针对同一地点的详情请求返回的 ID 进行比较,并在必要时进行更新。id 现已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
  • international_phone_number 包含此地点以国际格式表示的电话号码。国际格式包含国家/地区代码,并且带有一个加号 (+) 前缀。例如,Google 澳大利亚悉尼分公司的 international_phone_number+61 2 9374 4000
  • name 包含返回结果的可人工读取名称。对于 establishment 结果,这通常是指商家名称。
  • opening_hours 包含以下信息:
    • open_now 是表示该地点当前是否正在营业的布尔值。
    • periods[] 是一个持续七天的营业时段数组,这些营业时段从星期日开始,按时间顺序排列。每个时段均包含:
      • open 包含一对用于说明该地点营业时段的日期和时间对象:
        • day 是一个介于 0 到 6 之间的数字,对应于从星期日开始一周内的某天。例如,2 表示星期二。
        • time 可包含一天中的某个时间,采用 24 小时制 hhmm 格式。值的范围为 0000–2359。系统将按该地点的时区报告 time
      • close 可包含一对用于说明该地点何时关闭的日期和时间对象。:如果该地点全天开放,响应中将缺少 close 部分。客户可以通过下述方法来表示全天开放,将 open 时段的 day 值设置为 0,time 值设置为 0000 且不包含 close
    • weekday_text 是包含 7 个字符串的数组,这些字符串表示以特定格式表示的一周内每一天的开放时间。如果地点详情请求中指定了 language 参数,则“地点”服务会格式化并本地化该语言的相应开放时间。此数组中的元素排序取决于 language 参数。有些语言的一周从星期一开始,有些语言则从星期日开始。
  • permanently_closed 是布尔标志,指示地点是否永久关闭(true 值)。如果地点未永久关闭,响应中将不会显示该标志。
  • photos[]photo 对象数组,每个对象均包含对图像的引用。一个地点详情请求最多可以返回十张照片。有关地点照片以及如何在应用中使用图像的详情,请参阅地点照片文档。photo 对象的描述如下:
    • photo_reference – 执行照片请求时用于识别照片的字符串。
    • height – 图像最大高度。
    • width – 图像最大宽度。
    • html_attributions[] – 包含任何必需的提供方说明。此字段将始终存在,但可能为空。
  • place_id:用于唯一标识地点的文本标识符。要检索有关该地点的信息,请在 Places API 请求的 placeId 字段中传递此标识符。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
  • scope:指示 place_id 的作用域。可能的值为:
    • APP:地点 ID 仅可被您的应用识别。这是因为您的应用添加了此地点,且此地点尚未通过审核流程。
    • GOOGLE:地点 ID 可供其他应用以及 Google 地图使用。
  • alt_ids - 一个数组,由该地点的零个、一个或多个备选地点 ID 组成,每个备选 ID 都具有各自的作用域。注:此数组可能为空或不存在。如存在,则可包含以下字段:
    • place_id – 拥有备选地点 ID 最可能的原因是,如果您的应用添加一个地点并收到应用作用域地点 ID,那么在通过审核流程后,会收到 Google 作用域地点 ID。
    • scope – 备选地点 ID 的范围将始终为 APP,其指示备选地点 ID 只能由您的应用识别。
    例如,假设您的应用添加一个地点,并接收 AAA 作为新地点的 place_id。之后,该地点通过审核流程,并且接收 BBB 作为其 Google 作用域的 place_id。从此刻起,此地点的信息将包含:
        "results" : [
          {
            "place_id" : "BBB",
            "scope" : "GOOGLE",
            "alt_ids" : [
              {
                "place_id" : "AAA",
                "scope" : "APP",
              }
            ],
          }
        ]
        
  • price_level - 地点的价格水平,范围为 0 到 4 级。特定值指示的精确度因地区而异。价位解释如下:
    • 0 – 免费
    • 1 – 便宜
    • 2 – 中等
    • 3 – 昂贵
    • 4 – 非常昂贵
  • rating 包含基于用户总体评论的地点评分,范围从 1.0 到 5.0。
  • reference 包含可用于将来查询详情服务的令牌。此令牌可能与详情服务请求中使用的引用不同。建议您定期更新存储的地点引用。尽管此令牌唯一标识该地点,但是反之则不然。一个地点可以有多个有效的引用令牌。reference 现已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
  • reviews[] 是一个最多包含五条评论的 JSON 数组。如果地点详情请求中指定了 language 参数,则“地点”服务会调整结果,倾向于显示用该语言编写的评论。每条评论均由若干部分组成:
    • aspects 包含一个 AspectRating 对象集合,其中每个对象提供对该场所一个属性的评分。该集合中的第一个对象被认为是主要评分指标。各个 AspectRating 的描述如下:
      • type 表示评分指标名称。支持以下类型:appealatmospheredecorfacilitiesfoodoverallqualityservice
      • rating 表示用户针对该特定评分指标的评分,范围为 0 至 3。
    • author_name 表示提交评论的用户的姓名。匿名评论的作者统称为“A Google user”。
    • author_url 是指向用户 Google+ 个人资料(若有的话)的 URL。
    • language 表示用户评论所用语言的 IETF 语言代码。此字段仅包含主要语言标记,而不包含表示国家或地区的辅助标记。例如,所有英语评论都标记为“en”,而不是“en-AU”或“en-UK”等。
    • rating 表示用户对此地点的总体评分。此参数是一个整数,范围为 1 至 5。
    • text 表示用户的评论。通过 Google Places 评论位置时,文本评论是可选项。因此,此字段可能为空。请注意,此字段可以包含简单的 HTML 标记。例如,实体引用 &amp; 可以表示“与”字符。
    • time 表示提交评论的时间,以自 UTC 时间 1970 年 1 月 1 日 0:00:00 以来累计的秒数计算。
  • types[] 包含描述给定结果的特征类型数组。请参阅支持的类型列表了解更多信息。如果为结果分配不止一个类型,XML 响应将包含多个 <type> 元素。
  • url 包含此地点官方 Google 页面的 URL。这将显示由 Google 拥有的、包含该地点最佳可用信息的页面。在任何向用户显示该地点详细结果的屏幕上,应用必须与该页面相关联或者嵌入此页面。
  • utc_offset 包含此地点当前时区偏离 UTC 时间的分钟数。例如,对于澳大利亚悉尼的地点,在使用夏令时期间,此参数为 660(偏离 UTC 时间 +11 小时),对于加利福尼亚州的地点,在未使用夏令时期间,此参数为 -480(偏离 UTC 时间 -8 小时)。
  • vicinity 列出该地点的简化地址,包括街道名称、门牌号和行政区划,但不包括州/省、邮政编码或国家/地区。例如,Google 澳大利亚悉尼分公司的 vicinity 值为 48 Pirrama Road, Pyrmont
  • website 列出此地点的官方网站,例如商家主页。

并非所有地点都可使用多维评分。如果评论太少,那么,详情响应要么包含一个 1.0 至 5.0 之间的旧版评分,要么根本不包含任何评分。

高级数据

除了如上所列字段,拥有 Premium Plan 许可的 Google Places API 客户还可能会接收到以下字段。这些字段将作为 result 字段的顶级子字段显示。

  • aspects 包含一个 AspectRating 对象集合,其中每个对象提供对该场所的一个属性的综合评分。该集合中的第一个对象被认为是主要评分指标。各个 AspectRating 的描述如下:
    • type 表示评分指标名称。例如氛围、服务、食物、总体评论等。
    • rating 是指对此特定评分指标的综合评分,范围为 0 至 30 之间。请注意,综合评分的范围为 0 至 30,但评论中显示的评分范围为 0 至 3 之间。
  • review_summary 包括由 Google 编辑人员挑选的丰富而又简洁的评论。除非您在详情请求中传递 extensions=review_summary 参数,否则不会显示此字段。请注意,此字段可能无法以所请求的语言显示。
  • zagat_selected 表示该地点已被选为 Zagat 精选地点。拥有 Zagat 标签的地点,要么以其始终如一的高品质服务而闻名,要么拥有与众不同的特色。
如需了解详细信息,请参阅高级数据

以下示例显示 aspectsreview_summary 字段在响应正文中的显示方式:

"aspects" : [
   {
      "rating" : 24,
      "type" : "food"
   },
   {
      "rating" : 21,
      "type" : "decor"
   },
   {
      "rating" : 24,
      "type" : "service"
   }
],

...

"review_summary" : "For a meal that's a \"leisurely celebration\",
Mountain View \"foodies\" head to this \"lovely\" old Victorian house, where
\"artful\", \"high-end\" New French tasting dinners that \"look great and taste
even better\" are enhanced by sommelier-selected wines and service that
\"anticipates your every need\"; a garden out back supplies some ingredients,
while four dining areas provide \"lovely decor and ambiance\"; P.S. an
abbreviated tasting menu is also available."

sensor 参数

Google Places API Web Service 之前要求您包括 sensor 参数,以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。

发送以下问题的反馈:

此网页
location_on
Google Places API Web Service