一切就绪!

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

激活 Google Places API Web Service

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

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

地点添加

通过添加地点,您可以使用应用中的数据补充 Google 地图数据库中的数据。这使您可以:

  • 即时为您的用户更新 Google 数据库中的数据。
  • 将新地点提交至审核队列,以便添加到 Google Places 数据库中。
  • 使您的应用有别于其他具有类似功能的应用。
  • 创建针对特定用户群或地理地点的应用。
  • 改变从您的应用执行“地点搜索”的结果。
  1. 概览
  2. 添加地点
  3. 删除地点
  4. 状态代码
  5. 错误消息
  6. sensor 参数

概览

添加地点后,新地点将立即可用于应用发起的“附近地点搜索”。新地点还将进入将被考虑用于 Google 地图的审核队列中。未经审核流程的批准,新添加的地点不会出现在文本搜索或雷达搜索结果中,也不会出现在其他应用中。

对于通过您的应用添加的地点,您还可以在其通过审核之前将其删除。地点一旦通过审核并添加到 Google 数据库中,即无法再删除。未通过审核流程的地点对于提交此地点的应用仍将继续保持可见。

添加地点

地点添加请求是一个类似于下面示例的 HTTP POST 请求:


JSON
POST https://maps.googleapis.com/maps/api/place/add/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "location": {
    "lat": -33.8669710,
    "lng": 151.1958750
  },
  "accuracy": 50,
  "name": "Google Shoes!",
  "phone_number": "(02) 9374 4000",
  "address": "48 Pirrama Road, Pyrmont, NSW 2009, Australia",
  "types": ["shoe_store"],
  "website": "http://www.google.com.au/",
  "language": "en-AU"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/add/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceAddRequest>
  <location>
    <lat>-33.8669710</lat>
    <lng>151.1958750</lng>
  </location>
  <accuracy>50</accuracy>
  <name>Google Shoes!</name>
  <phone_number>(02) 9374 4000</phone_number>
  <address>48 Pirrama Road, Pyrmont, NSW 2009, Australia</address>
  <type>shoe_store</type>
  <website>http://www.google.com.au/</website>
  <language>en-AU</language>
</PlaceAddRequest>
      

请注意,URL 路径指示输入和输出的格式:

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

URL 必须包含以下参数:

  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。这样,通过您的应用添加的地点可立即供您的应用使用。如需了解详细信息,请参阅获取密钥

request body 包含有关地点的信息。它必须根据指定的 output 参数(JSON 或 XML)构建。

  • accuracy – 此请求所依赖的地点信号的精确度,单位为米。
  • address推荐使用,以提高通过审核的几率)– 要添加的地点的地址。如果地点具有格式正确、易于人工识别的地址,则更有可能通过审核流程并被添加到 Google 地图数据库中。
  • language – 报告地点名称所使用的语言。请参阅支持的语言列表及其代码。请注意,我们会经常更新支持的语言,因此,此列表可能并不全面。
  • location必填)– 地理位置,由要添加的地点的纬度和经度值指定。
  • name必填)– 地点的完整文本名称。限制为 255 个字符。
  • phone_number推荐使用,以提高通过审核的几率)– 该地点的关联电话号码。如果地点具有格式正确的电话号码,则更有可能通过审核流程并被添加到 Google 地图数据库中。此号码应采用本地格式或国际格式:
    • 本地格式因国家/地区而异。请参阅维基百科文章。例如,Google 澳大利亚悉尼分公司的本地电话号码为 (02) 9374 4000
    • 国际格式包含国家/地区代码,并且带有一个加号 (+) 前缀。例如,Google 澳大利亚悉尼分公司的国际电话号码为 +61 2 9374 4000
  • types必填)– 此地点所属的类别。尽管 types 可接受数组,但目前一个地点仅可指定一种类型。XML 请求要求使用一个 <type> 元素。请参阅支持的类型列表了解更多信息。如果支持的类型中没有任何类型与此地点匹配,您可以指定 other
  • website推荐使用,以提高通过审核的几率)– 指向此地点的官方网站(例如商家主页)的 URL。如果地点具有格式正确的网址,则更有可能通过审核流程并被添加到 Google 地图数据库中。

地点添加响应

地点添加响应的返回格式通过请求 URL 路径中的 output 参数指定。

API 会返回状态代码,如果请求成功,响应将包含新地点的以下属性:

  • place_id:用于唯一标识地点的文本标识符。要检索有关该地点的信息,请在地点详情请求的 placeid 字段中传递此标识符。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
  • scope:指示 place_id 的作用域。此字段的可能值为:
    • APP:地点 ID 仅可被您的应用识别。:地点添加响应的作用域始终为 APP,这是因为该地点尚未通过审核流程。
    • GOOGLE:地点 ID 可供其他应用以及 Google 地图使用。如上所述,地点添加响应将没有 Google 作用域。
  • reference:用于检索此地点相关附加信息的唯一令牌。reference 已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
  • id:指示此地点的唯一稳定标识符。此标识符不能用于检索此地点的相关信息,但保证在会话间有效。它可用于整合关于此地点的数据,以及在不同搜索之间验证地点识别信息。id 已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
{
  "status": "OK",
  "place_id": "CdIJN2t_tDeuEmsRUsoyG83frY4",
  "scope": "APP",
  "reference": "CiQgAAAAeTQS1RtzAyVRVjHcRiIWmWeqcAl3k7bluW7GINLDULESEHozTQhy6OHJw03ziDvY1uEaFAP_vDRhK-UbWw3Gd7Ulqm3eRjIs",
  "id": "6947fc4007436a71dbda51ef9a58627c8e8858f9"
}

删除地点

仅在以下情形下才可以删除地点:

  • 地点是由请求删除操作的应用添加的。
  • 地点添加请求未成功通过 Google 地图审核流程,因而地点仅对添加它的应用可见。

如果尝试删除不满足这些条件的地点,API 将返回 REQUEST_DENIED 状态代码。

地点删除请求是一个 HTTP POST 请求,其格式如下:


JSON
POST https://maps.googleapis.com/maps/api/place/delete/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "place_id": "place ID"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/delete/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceDeleteRequest>
  <place_id>place ID</place_id>
</PlaceDeleteRequest>
      

请注意,URL 路径指示输入和输出的格式:

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

URL 必须包含以下参数:

  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。这样,通过您的应用添加的地点可立即供您的应用使用。如需了解详细信息,请参阅获取密钥

request body 必须根据指定的 output 参数(JSON 或 XML)构建。它必须包括以下两个字段之一:

  • place_id:用于标识必须删除、从地点搜索返回的地点的字符串。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
  • 您也可以指定 reference 来标识地点。请注意,reference 已被弃用,取而代之的是 place_id。请参阅此页的弃用通告

地点删除响应

地点删除响应的返回格式通过请求 URL 路径中的 output 参数指定。

成功的删除请求会返回以下状态代码:

{
  "status": "OK"
}

状态代码

地点添加/删除请求的状态代码为:

  • OK 表示无任何错误;已成功添加或删除该地点。
  • UNKNOWN_ERROR 表示服务器端错误;重试可能会成功。
  • OVER_QUERY_LIMIT 表示您已超出配额。
  • REQUEST_DENIED 表示系统已拒绝您的请求。导致此状态代码的原因可能是试图删除由另一个应用添加的地点,或者试图删除已通过 Google 地图审核流程的地点。
  • INVALID_REQUEST 一般表示请求缺少参数。试图添加 name 大于 255 个字符的地点时,也会返回此状态代码。
  • NOT_FOUND,地点删除请求可能会返回此代码,表示传递的引用无法解析到地点。

错误消息

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

sensor 参数

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

发送以下问题的反馈:

此网页
location_on
Google Places API Web Service