一切就绪!

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

激活 Google Places API Web Service

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

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

地点搜索

Google Places API Web Service 可以让您按多个类别查询地点信息,如:场所、知名景点、地理位置等。您可以通过邻近感应或文本字符串搜索地点。地点搜索返回地点列表并附有每个地点的相关概要信息;其他信息可通过地点详情查询获得。

附近地点搜索请求

Places API 的较早版本把附近地点搜索称为地点搜索。

通过附近地点搜索,您可以搜索指定区域内的地点。您可以通过提供关键字或指定您正搜索的地点的类型来细化搜索请求。

附近地点搜索请求是一个 HTTP URL,其格式如下:

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

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

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

系统要求提供特定参数才能发起附近地点搜索请求。依照 URL 的标准,所有参数都使用“与”字符 (&) 分隔。

必填参数

  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。这样,通过您的应用添加的地点可立即供您的应用使用。如需了解详细信息,请参阅获取密钥
  • location – 检索地点信息所围绕的纬度/经度。必须指定为“纬度,经度”形式。
  • radius – 定义返回地点结果的范围(以米为单位)。所允许的最大半径为 50000 米。请注意,如果 rankby=distance(见下面可选参数部分中的描述)已指定,则不得包含 radius
  • 如果 rankby=distance(见下面可选参数部分中的描述)已指定,那么需要提供 keywordnametypes 中的一个或多个参数。

可选参数

  • keyword – 与 Google 为此地点编入索引的所有内容进行匹配的词语,包括但不仅限于名称、类型和地址,以及客户评论和其他第三方内容。
  • language – 语言代码,表示返回结果所应使用的语言(如提供该语言的话)。搜索功能同样偏向于所选的语言;使用所选语言的结果排名更高。请参阅支持的语言列表及其代码。请注意,我们会经常更新支持的语言,因此,此列表可能并不全面。
  • minpricemaxprice可选)– 将结果仅限制为指定范围内的地点。有效值的范围在 0(最实惠)和 4(最昂贵)之间,包括 0 和 4 本身。特定值所表示的准确数量因区域而异。
  • name - 与 Google 为此地点编入索引的所有内容匹配时所对照的字词。相当于 keywordname 字段不再受限于地点名称。此字段中的值与 keyword 字段中的值相结合,作为同一搜索字符串的一部分进行传递。我们建议所有搜索字词仅使用 keyword 参数。
  • opennow – 仅返回发送查询时营业的地点。如果您在查询中包含此参数,就不会返回在 Google Places 数据库中未指定开放时间的地点。
  • rankby – 指定结果列出的顺序。请注意,如果指定 radius(见上面所需参数部分中的描述),就不能添加 rankby。可能的值为:
    • prominence(默认)。此选项根据重要性对结果排序。优先列出指定区域的知名地点。知名度受 Google 索引中地点排序、全球知名度和其他因素影响。
    • distance。此选项按其与指定的 location 之间的距离以升序偏向搜索结果。当指定 distance 时,需要提供 keywordnametype 中的一个或多个参数。
  • types – 将结果限制为与指定类型匹配的地点。只能指定一个类型(如果提供了多个类型,系统会忽略第一项之后的所有类型)。请参阅支持的类型列表
  • types已弃用)- 将结果限制为至少与指定类型中的一个类型匹配的地点。请使用竖线符号分割类型,例如:
    type1|type2|etc
  • pagetoken – 返回上次所运行的搜索的后续 20 个结果。设置 pagetoken 参数将用上次使用的同一参数执行搜索 – 将忽略除 pagetoken 之外的所有参数。
  • zagatselected已弃用)- 添加此参数(只是参数名,无关联值),以将您的搜索限制为 Zagat 精选商家位置。此参数不得包含 truefalse 值。zagatselected 参数是试验性的,并且只向具有 Premium Plan 许可的 Google Places API 客户提供。

Google Maps APIs Premium Plan 客户注意事项:您必须在请求中添加 API 密钥。应在请求中添加 clientsignature 参数。

附近搜索示例

下面是一个搜索请求示例,以“restaurant”类型搜索澳大利亚悉尼某位置 500 米半径范围内包含“cruise”一词的地点:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

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

文本搜索请求

Google Places API Text Search Service 是一个根据一个字符串(如,“pizza in New York”或“shoe stores near Ottawa”或“123 Main Street”)返回一组地点相关信息的网络服务。该服务返回一个匹配此文本字符串和已设定的任何位置偏向的地点列表响应。

该服务在自动系统中进行地址模糊查询时尤其有用,字符串的非地址组成部分可能与商家以及地址匹配。举例来说,不完整的地址、格式不正确的地址,或者包含商家名称等非地址组件的请求可以使用地址模糊查询。

搜索响应将包含一个地点列表。如需了解有关响应中任何地点的详细信息,您可以发送一个地点详情请求。

Google Places 搜索服务具有相同的使用限制。但是,文本搜索服务在计算请求次数时需要乘以 10 倍。也就是说,您每进行一次文本搜索请求,将从您的配额中扣除 10 次请求。如果您的 Google Maps APIs Premium Plan 购买合同中已包含 Google Places API,倍数可能不同。请参阅 Google Maps APIs Premium Plan 文档了解详情。

文本搜索请求是一个 HTTP URL,其格式如下:

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

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

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

系统要求提供特定参数才能发起搜索请求。依照 URL 的标准,所有参数都使用“与”字符 (&) 分隔。

必填参数

  • query - 要搜索的文本字符串,例如:“restaurant”或“123 Main Street”。Google 地点服务将会根据该字符串返回候选匹配,并根据感知的相关度对结果排序。如果搜索请求中还使用了 type 参数,此参数将变为可选参数。
  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。这样,通过您的应用添加的地点可立即供您的应用使用。请参阅获取 Google Places API Web Service 的密钥,了解如何创建 API 项目并获取密钥。

可选参数

  • location – 检索地点信息所围绕的纬度/经度。必须指定为“纬度,经度”形式。如果您指定了 location 参数,您还必须指定 radius 参数。
  • radius – 定义偏向地点结果的范围(以米为单位)。所允许的最大半径为 50000 米。此地区内的结果排名将高于搜索范围外的结果;但是,可能包含搜索半径外的知名地点结果。
  • language – 语言代码,表示返回结果所应使用的语言(如提供该语言的话)。搜索功能同样偏向于所选的语言;使用所选语言的结果排名更高。请参阅支持的语言列表及其代码。请注意,我们会经常更新支持的语言,因此,此列表可能并不全面。
  • minpricemaxprice可选)– 将结果仅限制为指定价位内的地点。有效值范围在 0(最实惠)和 4(最昂贵)之间,包括 0 和 4 本身。特定值所表示的准确数量因区域而异。
  • opennow – 仅返回发送查询时营业的地点。如果您在查询中包含此参数,就不会返回在 Google Places 数据库中未指定开放时间的地点。
  • pagetoken – 返回上次所运行的搜索的后续 20 个结果。设置 pagetoken 参数将用上次使用的同一参数执行搜索 – 将忽略除 pagetoken 之外的所有参数。
  • types – 将结果限制为与指定类型匹配的地点。只能指定一个类型(如果提供了多个类型,系统会忽略第一项之后的所有类型)。请参阅支持的类型列表
  • types已弃用)- 将结果限制为至少与指定类型中的一个类型匹配的地点。请使用竖线符号分割类型(type1|type2|etc)。
  • zagatselected已弃用)- 添加此参数(只是参数名,无关联值),以将您的搜索限制为 Zagat 精选商家位置。此参数不得包含 truefalse 值。zagatselected 参数是试验性的,并且只向具有 Premium Plan 许可的 Google Places API 客户提供。

通过传递 locationradius 参数,可以使结果偏向指定的圆形区域内。这将让 Google 地点服务优先显示此范围内的结果。定义区域以外的结果也会显示。

Google Maps APIs Premium Plan 客户注意事项:您必须在请求中添加 API 密钥。应在请求中添加 clientsignature 参数。

文本搜索示例

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

示例 1:以下示例显示悉尼附近的餐厅搜索。

https://maps.googleapis.com/maps/api/place/textsearch/xml?query=restaurants+in+Sydney&key=YOUR_API_KEY

示例 2:以下示例显示不完整的地址搜索,在这种情况下,街道地址不包含城市或州或国家/地区。

https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&key=YOUR_API_KEY

示例 3:以下示例显示示例 2 中相同的不完整地址搜索,并且包含 locationradius 参数来偏向于感兴趣的地区的结果。比较示例 2 和示例 3 的结果。

https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&location=42.3675294,-71.186966&radius=10000&key=YOUR_API_KEY

雷达搜索请求

Google Places API Radar Search Service 允许您一次最多搜索 200 个地点,但其不如一般通过文本搜索或附近地点搜索请求返回的结果那么详尽。通过雷达搜索,您可以创建可帮助用户识别一定地理区域内特定兴趣范围的应用。

搜索响应最多可包含 200 个地点,且对于每个地点,只包含以下信息:

  • 包含地理坐标的 geometry 字段。
  • place_id,您可用在地点详情请求中,以获得关于地点的更多信息。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
  • 弃用的 reference 字段。请参阅此页的弃用通告

雷达搜索请求是一个 HTTP URL,其格式如下:

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

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

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

系统要求提供特定参数才能发起搜索请求。依照 URL 的标准,所有参数都使用“与”字符 (&) 分隔。

必填参数

  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。这样,通过您的应用添加的地点可立即供您的应用使用。请参阅获取 Google Places API Web Service 的密钥,了解如何创建 API 项目并获取密钥。
  • location – 检索地点信息所围绕的纬度/经度。必须指定为“纬度,经度”形式。
  • radius – 定义返回地点结果的范围(以米为单位)。所允许的最大半径为 50000 米。
  • 雷达搜索请求至少必须包含 keywordnametype 中的一个参数。

可选参数

  • keyword – 与 Google 为此地点编入索引的所有内容进行匹配的词语,包括但不仅限于名称、类型和地址,以及客户评论和其他第三方内容。
  • language – 语言代码,表示返回结果所应使用的语言(如提供该语言的话)。搜索功能同样偏向于所选的语言;使用所选语言的结果排名更高。请参阅支持的语言列表及其代码。请注意,我们会经常更新支持的语言,因此,此列表可能并不全面。
  • minpricemaxprice可选)– 将结果仅限制为指定价位内的地点。有效值范围在 0(最实惠)和 4(最昂贵)之间,包括 0 和 4 本身。特定值所表示的准确数量因区域而异。
  • name - 与 Google 为此地点编入索引的所有内容匹配时所对照的字词。相当于 keywordname 字段不再受限于地点名称。此字段中的值与 keyword 字段中的值相结合,作为同一搜索字符串的一部分进行传递。我们建议所有搜索字词仅使用 keyword 参数。
  • opennow – 仅返回发送查询时营业的地点。如果您在查询中包含此参数,就不会返回在 Google Places 数据库中未指定开放时间的地点。
  • types – 将结果限制为与指定类型匹配的地点。只能指定一个类型(如果提供了多个类型,系统会忽略第一项之后的所有类型)。请参阅支持的类型列表
  • types已弃用)- 将结果限制为至少与指定类型中的一个类型匹配的地点。请使用竖线符号分割类型(type1|type2|etc)。
  • zagatselected已弃用)- 添加此参数(只是参数名,无关联值),以将您的搜索限制为 Zagat 精选商家位置。此参数不得包含 truefalse 值。zagatselected 参数是试验性的,并且只向具有 Premium Plan 许可的 Google Places API 客户提供。

Google Maps APIs Premium Plan 客户注意事项:您必须在请求中添加 API 密钥。应在请求中添加 clientsignature 参数。

雷达搜索示例

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

示例 1:以下示例返回的是英国伦敦附近的博物馆列表。

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=51.503186,-0.126446&radius=5000&type=museum&key=YOUR_API_KEY

示例 2:使用 keywordtype 参数的组合,您可以执行更为精确的查询。以下示例显示的是用户描述为素食的巴黎餐馆和咖啡馆。

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=48.859294,2.347589&radius=5000&type=cafe&keyword=vegetarian&key=YOUR_API_KEY

搜索响应

搜索响应以 URL 请求路径中 output 标志指示的格式返回。

以下示例显示的是附近地点搜索响应。文本搜索响应类似,不过它返回 formatted_address,而不是 vicinity 属性。雷达搜索只包括有限的字段,如上文所述。

JSON
{
   "html_attributions" : [],
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870775,
               "lng" : 151.199025
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "21a0b251c9b8392186142c798263e289fe45b4aa",
         "name" : "Rhythmboat Cruises",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 270,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAF-LjFR1ZV93eawe1cU_3QNMCNmaGkowY7CnOf-kcNmPhNnPEG9W979jOuJJ1sGr75rhD5hqKzjD8vbMbSsRnq_Ni3ZIGfY6hKWmsOf3qHKJInkm4h55lzvLAXJVc-Rr4kI9O1tmIblblUpg2oqoq8RIQRMQJhFsTr5s9haxQ07EQHxoUO0ICubVFGYfJiMUPor1GnIWb5i8",
               "width" : 519
            }
         ],
         "place_id" : "ChIJyWEHuEmuEmsRm9hTkapTCrk",
         "scope" : "GOOGLE",
         "alt_ids" : [
            {
               "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
               "scope" : "APP"
            }
         ],
         "reference" : "CoQBdQAAAFSiijw5-cAV68xdf2O18pKIZ0seJh03u9h9wk_lEdG-cP1dWvp_QGS4SNCBMk_fB06YRsfMrNkINtPez22p5lRIlj5ty_HmcNwcl6GZXbD2RdXsVfLYlQwnZQcnu7ihkjZp_2gk1-fWXql3GQ8-1BEGwgCxG-eaSnIJIBPuIpihEhAY1WYdxPvOWsPnb2-nGb6QGhTipN0lgaLpQTnkcMeAIEvCsSa0Ww",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "Pyrmont Bay Wharf Darling Dr, Sydney"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866891,
               "lng" : 151.200814
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "45a27fd8d56c56dc62afc9b49e1d850440d5c403",
         "name" : "Private Charter Sydney Habour Cruise",
         "photos" : [
            {
               "height" : 426,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAL3n0Zu3U6fseyPl8URGKD49aGB2Wka7CKDZfamoGX2ZTLMBYgTUshjr-MXc0_O2BbvlUAZWtQTBHUVZ-5Sxb1-P-VX2Fx0sZF87q-9vUt19VDwQQmAX_mjQe7UWmU5lJGCOXSgxp2fu1b5VR_PF31RIQTKZLfqm8TA1eynnN4M1XShoU8adzJCcOWK0er14h8SqOIDZctvU",
               "width" : 640
            }
         ],
         "place_id" : "ChIJqwS6fjiuEmsRJAMiOY9MSms",
         "scope" : "GOOGLE",
         "reference" : "CpQBhgAAAFN27qR_t5oSDKPUzjQIeQa3lrRpFTm5alW3ZYbMFm8k10ETbISfK9S1nwcJVfrP-bjra7NSPuhaRulxoonSPQklDyB-xGvcJncq6qDXIUQ3hlI-bx4AxYckAOX74LkupHq7bcaREgrSBE-U6GbA1C3U7I-HnweO4IPtztSEcgW09y03v1hgHzL8xSDElmkQtRIQzLbyBfj3e0FhJzABXjM2QBoUE2EnL-DzWrzpgmMEulUBLGrtu2Y",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "Australia"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870943,
               "lng" : 151.190311
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "30bee58f819b6c47bd24151802f25ecf11df8943",
         "name" : "Bucks Party Cruise",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAA48AX5MsHIMiuipON_Lgh97hPiYDFkxx_vnaZQMOcvcQwYN92o33t5RwjRpOue5R47AjfMltntoz71hto40zqo7vFyxhDuuqhAChKGRQ5mdO5jv5CKWlzi182PICiOb37PiBtiFt7lSLe1SedoyrD-xIQD8xqSOaejWejYHCN4Ye2XBoUT3q2IXJQpMkmffJiBNftv8QSwF4",
               "width" : 800
            }
         ],
         "place_id" : "ChIJLfySpTOuEmsRsc_JfJtljdc",
         "scope" : "GOOGLE",
         "reference" : "CoQBdQAAANQSThnTekt-UokiTiX3oUFT6YDfdQJIG0ljlQnkLfWefcKmjxax0xmUpWjmpWdOsScl9zSyBNImmrTO9AE9DnWTdQ2hY7n-OOU4UgCfX7U0TE1Vf7jyODRISbK-u86TBJij0b2i7oUWq2bGr0cQSj8CV97U5q8SJR3AFDYi3ogqEhCMXjNLR1k8fiXTkG2BxGJmGhTqwE8C4grdjvJ0w5UsAVoOH7v8HQ",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "37 Bank St, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867591,
               "lng" : 151.201196
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "a97f9fb468bcd26b68a23072a55af82d4b325e0d",
         "name" : "Australian Cruise Group",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 242,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAABjeoPQ7NUU3pDitV4Vs0BgP1FLhf_iCgStUZUr4ZuNqQnc5k43jbvjKC2hTGM8SrmdJYyOyxRO3D2yutoJwVC4Vp_dzckkjG35L6LfMm5sjrOr6uyOtr2PNCp1xQylx6vhdcpW8yZjBZCvVsjNajLBIQ-z4ttAMIc8EjEZV7LsoFgRoU6OrqxvKCnkJGb9F16W57iIV4LuM",
               "width" : 200
            }
         ],
         "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
         "scope" : "GOOGLE",
         "reference" : "CoQBeQAAAFvf12y8veSQMdIMmAXQmus1zqkgKQ-O2KEX0Kr47rIRTy6HNsyosVl0CjvEBulIu_cujrSOgICdcxNioFDHtAxXBhqeR-8xXtm52Bp0lVwnO3LzLFY3jeo8WrsyIwNE1kQlGuWA4xklpOknHJuRXSQJVheRlYijOHSgsBQ35mOcEhC5IpbpqCMe82yR136087wZGhSziPEbooYkHLn9e5njOTuBprcfVw",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "32 The Promenade, King Street Wharf 5, Sydney"
      }
   ],
   "status" : "OK"
}

JSON 响应最多包含四个根元素:

  • "status" 包含请求的元数据。请参阅下面的状态代码
  • "results" 包含地点数组及各个地点的信息。请参阅搜索结果以了解关于这些结果的信息。对于每次查询,Places API 最多可返回 20 个 establishment 结果。另外,可能返回 political 结果,其用于识别请求区域。
  • html_attributions 包含一组有关此列表的提供方说明,这些说明必须显示给用户。
  • next_page_token 包含可用于最多返回 20 个其他结果的标记。如果没有其他结果要显示,就不会返回 next_page_token。可返回结果的最大数量为 60。发出 next_page_token 的时间与其生效时间之间有短暂延迟。

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

XML
<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Rhythmboat Cruises</name>
  <vicinity>Pyrmont Bay Wharf Darling Dr, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8707750</lat>
    <lng>151.1990250</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJyWEHuEmuEmsRm9hTkapTCrk</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CoQBdAAAAChhtoQX_467esHavS0Sj9DrY306W3_uDXKmB2us8Eh7_dX7rDuln18i_uqocF_LmzRptuFr6WZs7aeBSLFq8VFmckxFjsXDaqMdd3gvxi_5dIwPTEugQQYG9oJA-YnYfPBvjGtuoMfNnjyU2GuxGRmJjCO77pEAbsTLq44eBG5jEhAvkKHCGqIzqgC9tdOb1dSqGhRA1hhG4pvILD5OEAq6W8L8sXbkug</reference>
  <id>21a0b251c9b8392186142c798263e289fe45b4aa</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAiRA8ls6lx5LTfLuHJtLYvz73LXIMa5EVsHz2OUjh70LBPBnIEULZ57w076gOuyCeJqP041_v-ek3I5C4IkqW7YgA0EBybwywfIcUXsj5W_qiJR2yaXHXI-FmDM6j1zaS0sJQnNJhe4Bl9W42Jx16phIQRmNOWKGIemKLgzNEPcCnmBoUGgr0gWQBwWd8HAseR-5ie3JYuIM</photo_reference>
   <width>519</width>
   <height>270</height>
  </photo>
 </result>
 <result>
  <name>Private Charter Sydney Habour Cruise</name>
  <vicinity>Australia</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8668910</lat>
    <lng>151.2008140</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJqwS6fjiuEmsRJAMiOY9MSms</place_id>
  <scope>GOOGLE</scope>
  <reference>CpQBhQAAAKGKrbbnAW3_eAypKW9bhAzAuSmaqAogs7MTFxsntDqCzt-gKD9nz-zqNsk0uJsl0yCUYpNYjHz_yzmh3J_4TTxpxIqdaq2uDvfoTYtvm8FkxMAkK3cS7k9t3Ze2aHRWnxlN9hczK2xlc5taDE7xAGOHF5Xe5IlVV1wV66sOrWrlHtGh47lqT9Id86eG2OmlVhIQo4djLtRkceg-zaYjULYEjRoUToVEyOUVCFfZMUs_E7ZLSzjFmcg</reference>
  <id>45a27fd8d56c56dc62afc9b49e1d850440d5c403</id>
  <photo>
   <photo_reference>CnRnAAAAUW97jpK2_C2Lh4jLPVKZlhyS84mqZxvVmWFdc6jdl3XxjzKbYdbJpz0PGW5eFRw6kTKYNZM9QvRf-csFegHILZxLCLJ-6ZnbdEXbVM4kBzOb-rhchJx1KC6LHs_vVWP8bK96569lFYRf7Hn8ylQrlhIQb69_dcZVwqQhREsHW6azWhoU0XMWqZMBBzx-hgpduAaeErOFg8E</photo_reference>
   <width>640</width>
   <height>426</height>
  </photo>
 </result>
 <result>
  <name>Bucks Party Cruise</name>
  <vicinity>37 Bank St, Pyrmont</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8709430</lat>
    <lng>151.1903110</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJLfySpTOuEmsRsc_JfJtljdc</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBdAAAAOMUoYamsekTDxBDVyKZ-E54VQ6HjirVzAZBBwz5gcn5KTfmemmwmOAtLcvRScp1NLQmj-fBYzEO2Gq_cO4Dc12PG0_twzDv9zq3KIyNQVuO-r0n1eQVj8Dlng-n4c1F2hMxufCNVp4-QfjMj81qXJm0invQMUc1xNgZRyiOpLe9EhDLn0KiVWEFKOURYsWrHRouGhR7YMJxYmFs-OXjKyzQKGdQXLrzPw</reference>
  <id>30bee58f819b6c47bd24151802f25ecf11df8943</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAjboYP9Ujxe5SmZFN5AJc42AWtpYFX9wYdqjcTXavXJlfoXdHPC2hErdbHcaeYJBNPV6CzoDc2RLw_w9HofGOhCWHtoAl9b3g8TZZjnZobnAHxoljUdgV8PXyd-pCO-QHKOtiKfIdUmF4HRj2QHj6OhIQhLNpoKNKP8MNjk90M4KGrhoUW2NyBgsWjRpUEoWlt0fD48BhEcQ</photo_reference>
   <width>800</width>
   <height>600</height>
  </photo>
 </result>
 <result>
  <name>Australian Cruise Group</name>
  <vicinity>32 The Promenade, King Street Wharf 5, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675910</lat>
    <lng>151.2011960</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJrTLr-GyuEmsRBfy61i59si0</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBeAAAAJZA0WY2pKnZ6nNnxNd_pSDA2NilDLfGDf7pTt7VssxB5tMYE7400w3HZHRav2unpKRhEp7lrh0yKcVdSfKYIz85k1SExoLGmYD8NIf1dPr8KlkRWOYZUTLGp623r5hAzEGk94mPleF4s50pWqLrhAzwvJb1tGj2ak-2PXQORkeTEhAfTj6tMFo_tRWZYOnYCxiVGhQA3n-KV7AW5MvJlGaIDHuLyyEBBA</reference>
  <id>a97f9fb468bcd26b68a23072a55af82d4b325e0d</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAhTkpwozMoZx_NXMkIrKdcEGe46BmPy3GPCfS-gkCK5PlR8rFDY9DtD_7wFYAIdhVoZz3I9QguRNbil5y37jTU-03GJ_LqVw_avSxFkT0g2kU0K5z2VYnAsgNsrbsK_EVglhg5PrDybC1tAVKCXSGsRIQOcdlAVnC1Qc46YLWjlqdyxoUL5JGZgczfo1jxLxhDeGs8OvBQCk</photo_reference>
   <width>200</width>
   <height>242</height>
  </photo>
 </result>
</PlaceSearchResponse>

XML 响应包含一个 <PlaceSearchResponse> 和最多四个顶级元素:

  • <status> 包含请求的元数据。请参阅下面的状态代码
  • <result> 元素(零个或多个),每个此类元素都包含某个场所的相关信息。请参阅附近地点搜索结果以了解关于这些结果的信息。对于每次查询,Places API 最多可返回 20 个 establishment 结果。另外,可能返回 political <type> 结果或街道,其用于识别请求区域。
  • next_page_token 包含可用于最多返回 20 个其他结果的标记。如果没有其他结果要显示,就不会返回 next_page_token。可返回结果的最大数量为 60。第一次发出后,next_page_token 将保持活动状态 2 秒钟。
  • html_attributions 包含一组有关此列表的提供方说明,这些说明必须显示给用户。

状态代码

搜索响应对象中的 "status" 字段包含了请求的状态,还可能包含调试信息,以帮助您跟踪请求失败原因。"status" 字段可以包含以下值:

  • OK 表示未出现错误,成功检测到地点,并且至少返回一个结果。
  • ZERO_RESULTS 表示搜索成功,但未返回任何结果。如果给搜索传递某个偏远位置的 latlng 参数,可能会发生这种情况。
  • OVER_QUERY_LIMIT 表示您已超出配额。
  • REQUEST_DENIED 表示系统已拒绝您的请求,这通常是因为缺少有效的 key 参数。
  • INVALID_REQUEST 一般表示所需查询参数(locationradius)丢失。

错误消息

当 Google 地点服务返回 OK 以外的状态代码时,搜索响应对象中可能还会有额外的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

搜索结果

当 Google 地点服务从搜索返回 JSON 结果时,它将这些结果放置在 results 数组中。即使服务没有返回结果(例如,如果 location 比较偏远),它仍然会返回空的 results 数组。XML 响应包含零个或更多个 <result> 元素。

results 数组的每个元素包含来自特定区域(locationradius)的单个结果,按知名度排序。

结果可能还包含必须向用户显示的提供方说明信息。下面是一个 JSON 格式的提供方说明的示例:

"html_attributions" : [
      "Listings by \u003ca href=\"http://www.example.com/\"\u003eExample Company\u003c/a\u003e"
],
下面是一个 XML 格式的提供方说明:
<html_attribution>Listings by <a href="http://www.example.com/">Example Company</a></html_attribution>

results 数组中的每个结果可能均包含以下字段:

  • icon 包含推荐图标的 URL,显示此结果时可能会向用户显示此图标。
  • id 包含指示此地点的唯一稳定标识符。此标识符可能不用于检索关于此地点的信息,但保证在会话间有效。它可用于整合关于此地点的数据,以及在不同搜索之间验证地点识别信息。id 现已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
  • geometry 包含关于结果的几何信息,一般包括地点的 location(地理编码)和用于识别其一般覆盖区域的 viewport(可选)。
  • name 包含返回结果的可人工读取名称。对于 establishment 结果,这通常是指商家名称。
  • opening_hours 可能包含以下信息:
    • open_now 是表示该地点当前是否正在营业的布尔值。
  • photos[]photo 对象数组,每个对象均包含对图像的引用。地点搜索最多将返回一个 photo 对象。对地点执行地点详情请求最多可返回十张照片。有关地点照片以及如何在应用中使用图像的详情,请参阅地点照片文档。photo 对象的描述如下:
    • photo_reference – 执行照片请求时用于识别照片的字符串。
    • height – 图像最大高度。
    • width – 图像最大宽度。
    • html_attributions[] – 包含任何必需的提供方说明。此字段将始终存在,但可能为空。
  • place_id – 用于唯一标识地点的文本标识符。要检索有关该地点的信息,请在 Places API 请求的 placeId 字段中传递此标识符。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
  • scope – 指示 place_id 的作用域。可能的值为:
    • APP:地点 ID 仅可被您的应用识别。这是因为您的应用添加了此地点,且此地点尚未通过审核流程。
    • GOOGLE:地点 ID 可供其他应用以及 Google 地图使用。
    scope 字段只包含在附近地点搜索结果和地点详情结果中。您可以通过附近地点搜索和地点详情请求只检索应用作用域地点。如果响应中没有 scope 字段,则可以安全地假定作用域为 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。请参阅此页的弃用通告
  • types[] 包含描述给定结果的特征类型数组。请参阅支持的类型列表了解更多信息。如果为结果分配不止一个类型,XML 响应将包含多个 <type> 元素。
  • vicinity 包含附近位置的特征名称。此特征往往指的是给定结果内的街道或街区。对于附近地点搜索,仅返回 vicinity 属性。
  • formatted_address 是一个包含此地点可人工读取的地址的字符串。此地址往往相当于“邮政编码”。formatted_address 属性只为文本搜索返回。
  • permanently_closed 是布尔标志,指示地点是否永久关闭(true 值)。如果地点未永久关闭,响应中将不会显示该标志。

高级数据

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

  • aspects 包含单个 AspectRating 对象,即对场所的主要评分。各个 AspectRating 的描述如下:
    • type 表示评分指标名称。支持以下类型:appealatmospheredecorfacilitiesfoodoverallqualityservice
    • rating 是指对此特定评分指标的综合评分,范围为 0 至 30 之间。请注意,综合评分的范围为 0 至 30,但评论中显示的评分范围为 0 至 3 之间。
  • zagat_selected 表示该地点已被选为 Zagat 精选地点。拥有 Zagat 标签的地点,要么以其始终如一的高品质服务而闻名,要么拥有与众不同的特色。
如需了解详细信息,请参阅高级数据

访问其他结果

默认情况下,对于每次查询,每个附近地点搜索或文本搜索最多返回 20 个 establishment 结果;但是,每个搜索最多可返回 60 个结果,分三页显示。如果您的搜索将返回超过 20 个结果,那么搜索响应将包含一个额外值 – next_page_token。将 next_page_token 值传递至新搜索的 pagetoken 参数,以查看下一组结果。如果 next_page_token 为空或未返回,则表示没有更多结果。发出 next_page_token 的时间与其生效时间之间有短暂延迟。在它可用前请求下一页将返回 INVALID_REQUEST 响应。使用相同的 next_page_token 重试请求将返回下一页结果。

例如,在以下查询中,我们搜索澳大利亚悉尼达令港附近的餐馆,并且按距离对结果排序。您可以看到,响应中包含 next_page_token 属性。

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&rankby=distance&types=food&key=YOUR_API_KEY
{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867217,
               "lng" : 151.195939
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png",
         "id" : "7eaf747a3f6dc078868cd65efc8d3bc62fff77d7",
         "name" : "Biaggio Cafe - Pyrmont",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAmWmj0BqA0Jorm1_vjAvx1n6c7ZNBxyY-U9x99-oNyOxvMjDlo2npJzyIq7c3EK1YyoNXdMFDcRPzwLJtBzXAwCUFDGo_RtLRGBPJTA2CoerPdC5yvT2SjfDwH4bFf5MrznB0_YWa4Y2Qo7ABtAxgeBIQv46sGBwVNJQDI36Wd3PFYBoUTlVXa0wn-zRITjGp0zLEBh8oIBE",
               "width" : 900
            }
         ],
         "place_id" : "ChIJIfBAsjeuEmsRdgu9Pl1Ps48",
         "scope" : "GOOGLE",
         "price_level" : 1,
         "rating" : 3.4,
         "reference" : "CoQBeAAAAGu0wNJjuZ40DMrRe3mpn7fhlfIK1mf_ce5hgkhfM79u-lqy0G2mnmcueTq2JGWu9wsgS1ctZDHTY_pcqFFJyQNV2P-kdhoRIeYRHeDfbWtIwr3RgFf2zzFBXHgNjSq-PSzX_OU6OT2_3dzdhhpV-bPezomtrarW4DsGl9uh773yEhDJT6R3V8Fyvl_xeE761DTCGhT1jJ3floFI5_c-bHgGLVwH1g-cbQ",
         "types" : [ "cafe", "bar", "restaurant", "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866786,
               "lng" : 151.195633
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
         "id" : "3ef986cd56bb3408bc1cf394f3dad9657c1d30f6",
         "name" : "Doltone House",
         "photos" : [
            {
               "height" : 1260,
               "html_attributions" : [ "From a Google User" ],
               "photo_reference" : "CnRwAAAAeM-aLqAm573T44qnNe8bGMkr_BOh1MOVQaA9CCggqtTwuGD1rjsviMyueX_G4-mabgH41Vpr8L27sh-VfZZ8TNCI4FyBiGk0P4fPxjb5Z1LrBZScYzM1glRxR-YjeHd2PWVEqB9cKZB349QqQveJLRIQYKq2PNlOM0toJocR5b_oYRoUYIipdBjMfdUyJN4MZUmhCsTMQwg",
               "width" : 1890
            }
         ],
         "place_id" : "ChIJ5xQ7szeuEmsRs6Kj7YFZE9k",
         "scope" : "GOOGLE",
         "reference" : "CnRvAAAA22k1PAGyDxAgHZk6ErHh_h_mLUK_8XNFLvixPJHXRbCzg-gw1ZxdqUwA_8EseDuEZKolBs82orIQH4m6-afDZV9VcpggokHD9x7HdMi9TnJDmGb9Bdh8f-Od4DK0fASNBL7Me3CsAWkUMWhlNQNYExIQ05W7VbxDTQe2Kh9TiL840hoUZfiO0q2HgDHSUyRdvTQx5Rs2SBU",
         "types" : [ "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "aspects" : [
            {
               "rating" : 23,
               "type" : "overall"
            }
         ],
      ...
   ],
   "status" : "OK"
}

要查看下一组结果,您可以提交新查询,将 next_page_token 结果传递至 pagetoken 参数。例如:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY

设置 pagetoken 后,任何其他参数都会被忽略。此查询将执行与之前相同的搜索,但将返回一组新的结果。在第一次查询后,您最多可以请求新页面两次。每个结果页面必须依次显示。两页或更多页搜索结果不会作为单次查询的结果显示。请注意,每次搜索都算作使用限制中的一次请求。

sensor 参数

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

发送以下问题的反馈:

此网页
location_on
Google Places API Web Service