优化地理编码时的配额使用

地理编码是将地址（“1600 Amphitheatre Parkway, Mountain View, CA”）转换为地理位置坐标（37.423021, -122.083739）的过程，您可以利用此类坐标在地图上放置标记，或在地图上定位。Google Maps Platform API 提供了两种地理编码方法：

  • 客户端地理编码，在浏览器中执行，通常是为了响应用户操作。Maps JavaScript API 提供了可为您发出请求的类。Maps JavaScript API 文档中介绍了此方法。
  • HTTP 服务器端地理编码，可让您的服务器直接向 Google 的服务器查询地理编码。Geocoding API 是提供此功能的网络服务。通常，您需要将此服务与在服务器端运行的其他代码集成。Geocoding API 文档中介绍了服务器端地理编码。

客户端和服务器端地理编码示例

以下是客户端地理编码示例，该示例会获取地址，对其进行地理编码，将地图中心移至该位置，并在该位置添加地图标记：

geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': address }, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

如需查看更多示例，请参阅 Maps JavaScript API 文档。

以下示例展示了如何使用 Python 在 Geocoding API v4 中发出服务器端地理编码请求：

import json
import urllib.request

address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key = "my-key-here"
url = f"https://geocode.googleapis.com/v4/geocode/address/{address}"
headers = {"X-Goog-Api-Key": key}

req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))

这段代码生成的 JSON 对象包含以下内容：

{
  "results": [
    {
      "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "location": {
        "latitude": 37.4224864,
        "longitude": -122.0855962
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4211700197085,
          "longitude": -122.08691558029149
        },
        "high": {
          "latitude": 37.4238679802915,
          "longitude": -122.08421761970851
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4221145,
          "longitude": -122.0860002
        },
        "high": {
          "latitude": 37.4228775,
          "longitude": -122.085133
        }
      },
      "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 41",
          "shortText": "Google Building 41",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

如需查看更多示例，请参阅 Geocoding API v4 概览和对地址进行地理编码指南。

配额和费用注意事项

本文档中概述的策略受地理编码费用、配额和速率限制的影响。

费用

地理编码请求不适用每日配额 (QPD) 限制。 相反，每个地理编码请求（无论是通过浏览器在客户端发出的请求，还是通过 Geocoding API Web 服务在服务器端发出的请求）都按请求价格计费。如需管理使用费，请考虑管理用量限额和配额。

速率限制

地理编码服务的速率限制为 3,000 QPM（每分钟查询次数），计算方式是将客户端和服务器端查询相加。

如果定期运行客户端地理编码请求（例如在移动应用中），当所有用户同时发出请求（例如在每分钟的同一秒）时，您的请求可能会返回错误。为避免这种情况，请考虑以下任一方法：

  • 在请求中引入随机间隔（抖动）。确保在整个用户群中随机发送请求。
  • 如果针对 Android 进行开发，请使用不精确的重复闹钟。
  • 如果针对 Android 进行开发，请选择适当的位置策略。

缓存

请参阅 Geocoding API 政策，了解缓存相关信息。

v4 中的服务器端架构与客户端架构

Geocoding API v4（包括 SearchDestinations、GeocodeAddress、GeocodeLocation 和 GeocodePlace）是一种服务器到服务器 API。从后端服务器调用 v4 端点具有以下重要优势：

  • 超本地化到达智能：SearchDestinations 方法 (POST /v4/geocode/destinations) 仅可通过服务器端 REST 或 gRPC 请求使用，可返回建筑物入口、可规划路线的导航点、建筑物轮廓和附近地标，这些信息在客户端浏览器地理编码器中无法获取。
  • 增强 API 安全性：服务器端调用可防止 API 密钥和 OAuth 令牌在客户端浏览器中泄露。请参阅 API 安全性。
  • 响应字段掩码：服务器端 v4 端点支持字段掩码，让您能够仅请求应用所需的字段，从而最大限度地缩减载荷大小并缩短延迟时间。

何时使用客户端浏览器查询

对于响应实时按键操作的交互式浏览器应用，请考虑将客户端地点自动补全（用于消除用户输入歧义并获取地点 ID）与对 SearchDestinations 或 GeocodePlace 的后端调用相结合，以安全地检索超本地化详情或坐标。