此页面由 Cloud Translation API 翻译。

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

术语“地理编码”通常是指将人类可读的内容翻译为转换为地图上的某个位置。反过来操作过程将地图上的某个位置转换为可人工读取的地址的过程称为 反向地理编码。

反向地理编码请求

必需参数

latlng - 纬度和经度坐标，用于指定距离最近的位置，简单易懂的地址
key - 您的应用的 API 密钥。此密钥用于标识以便管理配额了解如何获取密钥。

可选参数

这些是您可以反转的可选参数地理编码请求：

language - 返回结果时使用的语言。
- 请参阅支持的语言。Google 会经常更新支持的语言该列表可能并非详尽无遗。
- 如果未提供 language，地理编码器会尝试使用 Accept-Language 标头中指定的首选语言，或发出请求的网域的当地语言。
- 地理编码器会尽力提供符合以下要求的街道地址便于用户和本地用户查看为了实现这一目标，以当地语言返回街道地址，并将其音译为脚本供用户阅读，并遵守首选语言。所有其他地址都返回首选语言。地址组成部分均以相同的语言返回，也就是从第一个组件中选择的
- 如果某个名称没有以首选语言提供，地理编码器会使用最接近的匹配项。
region - 地区代码，已指定为 ccTLD （“顶级域”）双字符值。参数还会影响搜索结果。
result_type - 包含一个或多个地址类型的过滤器。使用竖线 (|) 分隔。如果参数包含多个那么 API 会返回与任何类型匹配的所有地址。关于处理的注意事项：result_type 参数不会 将搜索限定为指定的地址类型。相反， result_type 充当搜索后过滤器：API 会抓取所有指定 latlng 的结果，然后舍弃这些结果与指定的地址类型不匹配。以下是支持：
- street_address 表示精确的街道地址。
- route 表示已命名的路线（例如“US 101”）。
- intersection 表示主要交叉路口，通常是两条主要道路的交叉路口。
- political 表示政治实体。这种类型通常表示某些行政管理区的多边形区域。
- country 表示国家政治实体，通常列在地理编码器所返回结果的最前面。
- administrative_area_level_1 表示国家/地区级别以下的一级行政实体。在美国，这类行政级别是指州。并不是所有国家都设有这类行政级别。在大多数情况下，administrative_area_level_1 简称可高度匹配 ISO 3166-2 行政区划以及其他广为传播的列表；不过，我们无法对此做出保证，因为我们的地理编码结果基于各种信号和位置数据。
- administrative_area_level_2 表示国家/地区级别以下的二级行政实体。在美国，这类行政级别是指县。并不是所有国家都设有这类行政级别。
- administrative_area_level_3 表示国家/地区级别以下的三级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。
- administrative_area_level_4 表示国家/地区级别以下的四级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。
- administrative_area_level_5 表示国家/地区级别以下的五级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。
- administrative_area_level_6 表示国家/地区级别以下的六级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。
- administrative_area_level_7 表示国家/地区级别以下的七级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。
- colloquial_area 表示实体的常用替代名称。
- locality 表示合并的城市或城镇政治实体。
- sublocality 表示市行政区以下的一级行政实体。对于某些位置，可能会收到以下任一类型：从 sublocality_level_1 到 sublocality_level_5。每个子级市行政区级别都是一个行政实体。数字越大表示地理区域越小。
- neighborhood 表示已命名的街区。
- premise 表示已命名的位置，通常是具有常见名称的建筑或建筑群。
- subpremise 表示已命名位置以下的一级实体，通常是具有共同名称的建筑群中的单个建筑物。
- plus_code 表示经过编码的位置引用，衍生自纬度和经度。Plus Codes 可用于在没有街道地址的地点（例如建筑物未编号，或者街道未命名）取代街道地址。如需了解详情，请参阅 https://plus.codes。
- postal_code 表示国家/地区内邮寄地址所用的邮政编码。
- natural_feature 表示某个明显的自然地貌。
- airport 表示机场。
- park 表示已命名的公园。
- point_of_interest 表示已命名的地图注点。通常情况下，这些“地图注点”是当地的著名实体，无法轻易归入其他类别，例如“帝国大厦”或“埃菲尔铁塔”。
location_type - 包含一个或多个地理位置类型的过滤器。使用竖线 (|) 分隔。如果参数包含多个位置类型，则 API 会返回与任意类型匹配的所有地址。关于处理的注意事项：location_type 参数不会 将搜索范围限制为指定的位置类型。相反， location_type 充当搜索后过滤器：API 会抓取所有指定 latlng 的结果，然后舍弃这些结果。支持以下值：
- "ROOFTOP" 仅返回 Google 使其位置信息精确到街道地址精度的地址。
- "RANGE_INTERPOLATED" 仅返回反映两个近似值（通常为道路上的地址），精确的点（如交叉路口）。插值范围（一般是插值范围）表示某个街道地址的屋顶地理编码不可用。
- "GEOMETRIC_CENTER" 仅返回几何图形地点的中心，如多段线（如街道）或多边形（区域）。
- "APPROXIMATE" 仅返回是近似值。
extra_computations - 使用此参数指定响应中的以下附加功能： <ph type="x-smartling-placeholder">
- ADDRESS_DESCRIPTORS - 如需了解详情，请参阅地址描述符。
- BUILDING_AND_ENTRANCES - 参见 <ph type="x-smartling-placeholder"></ph> 入口和建筑物轮廓。
。要针对同一 API 请求启用上述多个功能，请添加 extra_computations 参数，例如：
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```

如果同时存在 result_type 和 location_type 过滤条件，则 API 仅返回同时匹配 result_type 和 location_type 值。如果所有过滤器值均不可接受， API 会返回 ZERO_RESULTS。

反向地理编码示例

以下查询包含了布鲁克林某个位置的纬度/经度值：

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

注意：在将纬度和经度值传入 latlng 参数时，请确保两者之间没有空格。

上述查询返回以下结果：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

请注意，反向地址解析器传回了多个结果。通过 "formatted_address" 的搜索结果不仅有邮政地址，以任何方式对位置进行地理命名。例如，对芝加哥市的某个点进行地理编码时，地理编码的点可以表示为街道地址、城市（芝加哥）、所在州（伊利诺伊州）或国家/地区（美国）。这些对地址解析器来说都是“地址”。反向地理编码器会返回任何这些类型的结果。

反向地理编码器会匹配政治实体（国家/地区、省、城市和社区）、街道地址和邮政编码。

由 API 返回的 formatted_address 值的完整列表如下所示。

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

此 API 会返回不同类型的地址，从最具体的定位到不太具体的政治实体（如邻近地区、州、县和市。一般来说，较为准确的地址就是如本例所示。如果您想匹配特定类型的请参阅下文中限制结果。因此，相对于可能各不相同

按类型过滤的反向地理编码

以下示例对返回的地址进行过滤，以便仅包含位置类型为ROOFTOP，地址类型为 street_address。

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

注意：这些过滤条件仅适用于反向地理编码。

反向地理编码响应

反向地理编码响应的格式与地理编码相同响应。请参阅地理编码响应。下面是反向地理编码响应中可能出现的状态代码。

反向地理编码状态代码

地理编码响应对象中的 "status" 字段包含了请求的状态，还可能包含调试信息，以帮助您查明反向地理编码不工作的原因。"status" 字段可能包含以下值：

"OK" 表示未发生任何错误，并且至少有一个错误地址。
"ZERO_RESULTS" 表示反向地理编码成功，但未返回任何结果。如果地址解析器在远程位置传递了 latlng。
"OVER_QUERY_LIMIT"表示您已超出配额。
"REQUEST_DENIED" 表示请求已被拒绝。这可能是因为请求包含 result_type 或 location_type 参数，但不包含 API 密钥。
"INVALID_REQUEST" 通常表示以下状态之一： <ph type="x-smartling-placeholder">
- 查询（address、components 或 latlng）。
- result_type 或 location_type 无效。
"UNKNOWN_ERROR" 表示因服务器错误而无法处理该请求。如果您重试一次，请求可能会成功。

反向地理编码 Plus 代码

地理编码响应中的 plus_code 字段包含一个 Plus 代码，用于最接近查询的纬度和经度。此外，JSON 结果数组在大多数情况下包含完整的地理编码结果为 plus_code 类型且地址包含加号代码。解码后的 Plus 代码与请求点之间的距离为保证小于 10 米