Geocoding API v4 使用入门

欧洲经济区 (EEA) 开发者

如果您的账单邮寄地址在欧洲经济区，自 2025 年 7 月 8 日起，您在使用服务时需遵守 Google Maps Platform 欧洲经济区服务条款。具体功能因区域而异。 了解详情。

准备工作： 在开始使用 Geocoding API 之前，请确保您的项目已关联结算账号并且启用了 Geocoding API 。我们建议创建多个 Project Owner 和 Billing Administrator，确保您的团队中始终有担任这些角色的成员。如需了解详情，请参阅在 Cloud 控制台中进行设置。

Geocoding API v4 提供两个核心功能系列：目的地搜索（用于获取丰富的超本地化属性）和基本地理编码（坐标与地址转换）。不确定要使用哪种方法？请参阅选择地理编码方法。

• 搜索目的地 (SearchDestinations)：检索目的地的详细到达信息，包括建筑物入口、可规划路线的导航点、建筑物/场地轮廓、子目的地和附近地标。
• Geocoding (GeocodeAddress)：将街道地址转换为纬度和经度坐标，以便放置基本标记或使地图居中。
• 反向地理编码 (GeocodeLocation)：将地理坐标转换为人类可读的街道地址。
• 地点地理编码 (GeocodePlace)：查找已知地点 ID 的格式化地址和坐标。

请求和响应示例

您可以通过 HTTP 接口访问 Geocoding API。以下是搜索目的地、正向地理编码和反向地理编码的快速入门示例。

搜索目的地请求和响应（超本地化到达数据）

以下示例向 SearchDestinations 发送了一个 HTTP POST 请求，以查询“1600 Amphitheatre Parkway, Mountain View, CA”。请注意，SearchDestinations 需要一个 X-Goog-FieldMask 标头来指定要返回的字段：

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA"
  }
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/destinations"

以下是一个 SearchDestinations 响应示例，其中显示了建筑物轮廓多边形、首选入口、可规划路线的导航点和附近地标：

{
  "destinations": [
    {
      "primary": {
        "displayName": { "text": "Googleplex", "languageCode": "en" },
        "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "location": { "latitude": 37.4220656, "longitude": -122.0840897 },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.084958, 37.422145],
              [-122.084112, 37.422610],
              [-122.083510, 37.421980],
              [-122.084958, 37.422145]
            ]
          ]
        }
      },
      "entrances": [
        {
          "location": { "latitude": 37.422189, "longitude": -122.084215 },
          "tags": ["PREFERRED"]
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "Eg...",
          "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" },
          "location": { "latitude": 37.421912, "longitude": -122.084301 },
          "travelModes": ["DRIVE"],
          "usages": ["DROPOFF", "PICKUP"]
        }
      ],
      "landmarks": [
        {
          "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } },
          "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" },
          "straightLineDistanceMeters": 85.4
        }
      ]
    }
  ]
}

地理编码请求和响应（纬度/经度查询）

以下示例请求“1600 Amphitheatre Parkway, Mountain View, CA”的纬度和经度，并指定输出必须采用 JSON 格式。

curl -H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

您可以通过在网络浏览器中输入网址来测试此功能（请务必将 YOUR_API_KEY 替换为您的实际 API 密钥）。 响应包括地址的纬度和经度。

如需详细了解如何 构建地理编码请求网址、可用参数以及 了解响应，请参阅开发者指南。

下面是一个 JSON 格式的地理编码响应示例：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "location": {
        "latitude": 37.4438238,
        "longitude": -122.0869895
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4424748197085,
          "longitude": -122.0883384802915
        },
        "high": {
          "latitude": 37.445172780291493,
          "longitude": -122.08564051970852
        }
      },
      "formattedAddress": "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": "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"
      ]
    }
  ]
}

反向地理编码请求和响应（地址查询）

以下示例请求获取美国纽约州布鲁克林区中与给定纬度/经度对应的地址。它指定输出必须采用 JSON 格式。

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEY

您可以在网络浏览器中输入该网址进行测试（请务必将“YOUR_API_KEY”替换为您的实际 API 密钥）。 响应中包含纬度和经度位置的人类可读地址。

如需详细了解如何 构建反向地理编码请求网址、可用参数以及 了解响应，请参阅开发者指南。

下面是一个 JSON 格式的反向地理编码响应示例：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "location": {
        "latitude": 37.4225657,
        "longitude": -122.08465439999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421214719708509,
          "longitude": -122.08603273029148
        },
        "high": {
          "latitude": 37.423912680291508,
          "longitude": -122.0833347697085
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4225178,
          "longitude": -122.08484599999998
        },
        "high": {
          "latitude": 37.422609600000008,
          "longitude": -122.0845215
        }
      },
      "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "Google Building 40",
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 40",
          "shortText": "Google Building 40",
          "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"
          ]
        }
      ],
      "types": [
        "street_address",
        "subpremise"
      ]
    },
    ... Additional results truncated in this example[] ...
}

身份验证、配额、价格和政策

身份验证

如需使用 Geocoding API，您必须先启用该 API 并获取适当的身份验证凭证。如需了解详情，请参阅 Google Maps Platform 使用入门。

配额和价格

如需详细了解为 Geocoding API 设置的配额和价格，请参阅用量和结算页面。

注意：在预览版期间，Geocoding API v4 方法的每秒查询次数 (QPS) 上限为 25 次。如需了解如何申请更高的配额，请参阅 查看和管理配额，然后选择 Geocoding API 作为服务。

警告：由于存在安全风险，您不应直接从客户端 JavaScript 调用 Geocoding API v4 方法。如果您不顾建议执意这样做，请注意，申请更高的配额会增加 API 密钥滥用的潜在影响。请参阅安全注意事项。

政策

使用 Geocoding API 时，必须遵守 API 政策。