Geocoding API v4 方法的默认配额为每秒 25 次查询次数 (QPS)。如需了解如何申请更高的配额，请参阅查看和管理配额，然后选择Geocoding API作为服务。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

对位置进行反向地理编码

欧洲经济区 (EEA) 开发者

反向地理编码会将地图位置转换为人类可读的地址。您可以使用位置的纬度和经度坐标来表示地图位置。

当您对某个位置进行反向地理编码时，响应会包含以下内容：

地点 ID 的地址
地址的 Plus Codes
地址详情

此 API 会返回不同类型的地址，从最具体的街道地址到不那么具体的政治实体，例如街区、市、县和州。最准确的地址通常是第一个结果。如果您想匹配特定类型的地址，请使用 types 参数。

反向地理编码请求

反向地理编码请求是 HTTP GET 请求。您可以将位置指定为非结构化字符串：

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

也可以指定为一组结构化的纬度和经度坐标（以查询参数表示）：

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

您通常会在处理 HTML 表单中捕获的位置组成部分时使用结构化格式。

将所有其他参数作为网址参数传递，或者对于 API 密钥或字段掩码等参数，在标头中作为 GET 请求的一部分传递。例如：

传递非结构化位置字符串

非结构化位置是指格式为以逗号分隔的纬度和经度坐标字符串的位置：

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

或采用 curl 命令：

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

传递结构化位置

使用 location 查询参数（类型为 LatLng）指定结构化位置。借助 LatLng 对象，您可以将纬度和经度指定为单独的查询参数：

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

使用 OAuth 发出请求

Geocoding API v4 支持使用 OAuth 2.0 进行身份验证。如需将 OAuth 与 Geocoding API 搭配使用，必须为 OAuth 令牌分配正确的范围。 Geocoding API 支持以下范围，可用于反向地理编码：

https://www.googleapis.com/auth/maps-platform.geocode - 与所有 Geocoding API 方法搭配使用。
https://www.googleapis.com/auth/maps-platform.geocode.location - 仅与 GeocodeLocation 搭配使用，用于反向地理编码。

此外，您还可以将通用的 https://www.googleapis.com/auth/cloud-platform 范围用于所有 Geocoding API 方法。此范围在开发期间非常有用，但在生产环境中则不适用，因为这是一个通用范围，允许访问所有方法。

如需了解详情和示例，请参阅使用 OAuth。

反向地理编码响应

反向地理编码会返回一个 GeocodeLocationResponse 对象，其中包含：

表示地点的 results 数组，其中包含 GeocodeResult 对象。

Geocoding API 响应在 GeocodeResult 中的两个主要位置包含 types 数组：
1. GeocodeResult.types：此数组表示结果的总体类型。可能的值来自 Places API 使用的地点类型。如需了解详情，请参阅地点类型表 A 和表 B。
2. GeocodeResult.addressComponents[].types：每个地址组成部分都有一个 types 数组，用于表示地址中该特定部分的类型。这些值来自地址类型和地址组成部分类型表，Places API 使用该表。
反向地理编码器会在 results 数组中返回多个结果。结果不仅有邮政地址，还包括对某个位置进行的任何地理位置上的命名。例如，对芝加哥市的某个点进行地理编码时，经过地理编码的点可以标注为街道地址、城市（芝加哥）、所在州（伊利诺伊州）或国家/地区（美国）。这些对地理编码器来说都是“地址”。反向地理编码器会将这些类型中的任何一种作为有效结果返回。
类型为 PlusCode 的 plusCode 字段包含最能近似请求中的纬度和经度的 Plus Code。此外， `results` results数组的每个元素都包含一个 Plus Code。解码后的 Plus Code 与请求点之间的距离小于 10 米。

注意：API 并非始终返回 Plus Codes。

完整的 JSON 对象采用以下形式：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

必需参数

地理位置

用于指定您要获取距离最近的人类可读地址的纬度和经度坐标。

可选参数

languageCode

用于返回结果的语言。
- 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
- 如果未提供 languageCode，API 会默认使用该位置的本地语言和脚本。如果您指定了无效的语言代码，API 会返回 INVALID_ARGUMENT 错误。
- API 会尽力提供用户和当地人都能看懂的街道地址。为实现此目标，它会以本地语言返回街道地址，并在必要时将其音译为用户可读的脚本，同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分全部以同一种语言返回，该语言是从第一个组成部分中选择的。
- 如果首选语言中没有名称，API 会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集以及返回结果的顺序影响不大。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。
regionCode

区域代码，采用双字符 CLDR 代码值。没有默认值。大多数 CLDR 代码都与 ISO 3166-1 代码相同。
对地址进行地理编码（即正向地理编码）时，此参数可以影响但不会完全限制服务返回指定区域的结果。对位置或地点进行地理编码（即反向地理编码或地点地理编码）时，此参数可用于设置地址的格式。在所有情况下，此参数都可能会根据适用法律影响结果。
granularity

一个或多个位置细分单位，以单独的查询参数形式指定，如 Granularity 所定义。如果您指定了多个 granularity 参数，API 会返回与任何细分单位匹配的所有地址。

granularity 参数不会将搜索范围限制为指定的地理位置细分单位。相反， granularity 会充当搜索后过滤条件。API 会提取指定 location 的所有结果，然后舍弃与指定地理位置细分单位不匹配的结果。

如果您同时指定了 types 和 granularity，则 API 将仅返回与两者都匹配的结果。例如：
```
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY
```
类型

一个或多个地址类型，以单独的查询参数形式指定。可能的值来自地点类型（新）页面上的地址类型和地址组成部分类型表。如果您指定了多个 types 参数，API 会返回所有与任何类型匹配的地址。

types 参数不会 将搜索范围限制为指定的地址类型。相反， types 会充当搜索后过滤条件。API 会提取指定位置的所有结果，然后舍弃与指定地址类型不匹配的结果。

如果您同时指定了 types 和 granularity，则 API 将仅返回与两者都匹配的结果。例如：
```
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY
```

FieldMask

创建响应字段掩码，以指定要在响应中返回的字段。使用网址参数 $fields 或 fields，或者使用 HTTP 标头 X-Goog-FieldMask，将响应字段掩码传递给方法。例如，以下请求将仅返回响应的 placeID 字段。

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

响应为：

{
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

如需了解详情，请参阅选择要返回的字段。

对位置进行反向地理编码 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

反向地理编码请求

传递非结构化位置字符串

传递结构化位置

使用 OAuth 发出请求

反向地理编码响应

必需参数

地理位置

可选参数

languageCode

regionCode

granularity

类型

FieldMask

对位置进行反向地理编码