反向地理编码(地址查询)请求和响应

“地理编码”这一术语通常指将便于用户理解的地址转换为地图上的某个位置的过程。与之相反,将地图上的某个位置转换为直观易懂的地址的过程称为“反向地理编码”。

反向地理编码请求

必需参数

  • latlng - 纬度和经度坐标,用于指定您希望从哪个位置了解最接近的、人类可读懂的地址。
  • key - 您的应用的 API 密钥。此密钥用于标识您的应用,以便进行配额管理。了解如何获取密钥

可选参数

以下是可包含在反向地理编码请求中的可选参数:

  • language - 返回结果时使用的语言。
    • 请参阅支持的语言列表。Google 会经常更新支持的语言,因此该列表可能并非详尽无遗。
    • 如果未提供 language,地理编码器会尝试使用 Accept-Language 标头中指定的首选语言,或发送请求的网域的本地语言。
    • 地理编码器会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标,它会返回当地语言的街道地址,如有必要,可将其音译为可由用户阅读的文字,同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分均以同一种语言返回,该语言是从第一个组成部分中选择的语言。
    • 如果某个名称在首选语言中没有对应项,则地理编码器会使用最接近的匹配项。
  • region - 地区代码,已指定为 ccTLD(“顶级域名”)双字符值。该参数还会根据适用法律影响结果。
  • result_type - 一个或多个地址类型的过滤条件,以竖线 (|) 分隔。如果参数包含多个地址类型,API 会返回与任何类型匹配的所有地址。 关于处理的说明:result_type 参数不会将搜索restrict在指定的地址类型中。相反,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_1sublocality_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 参数不会restrict将搜索范围限制为指定的位置类型。相反,location_type 充当搜索后过滤器:API 会提取指定 latlng 的所有结果,然后舍弃与指定位置类型不匹配的结果。 支持使用以下值:
    • "ROOFTOP" 仅返回 Google 拥有其位置信息精确到街道地址的地址。
    • "RANGE_INTERPOLATED" 仅返回能反映两个精确点(例如交叉路口)之间用插值计算的近似地址(通常为道路上)的地址。插值范围通常表示某个街道地址的屋顶地理编码不可用。
    • "GEOMETRIC_CENTER" 仅返回多段线(例如街道)或多边形(区域)等位置的几何图形中心。
    • "APPROXIMATE" 仅返回特征为近似的地址。
  • extra_computations - 此参数允许使用的值为 ADDRESS_DESCRIPTORS。如需了解详情,请参阅 地址描述符

如果同时存在 result_typelocation_type 过滤条件,则 API 仅返回与 result_typelocation_type 值都匹配的结果。如果所有过滤条件值均不可接受,API 会返回 ZERO_RESULTS

反向地理编码示例

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

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

上述查询返回以下结果:

{
   "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" 结果不仅有邮政地址,还包括对某个位置进行的任何地理位置命名的方式。例如,对芝加哥市的某个点进行地理编码时,经过地理编码的点可以标注为街道地址、城市(芝加哥)、所在州(伊利诺伊州)或国家/地区(美国)。这些对地址解析器来说都是“地址”。反向地理编码器会将这些类型中的任何一种返回为有效结果。

反向地理编码器会匹配政治实体(国家/地区、省、市和街区)、街道地址以及邮政编码。

上一个查询返回的 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_typelocation_type 参数,但未包含 API 密钥。
  • "INVALID_REQUEST" 通常表示以下各项之一:
    • 缺少查询(addresscomponentslatlng)。
    • 提供的 result_typelocation_type 无效。
  • "UNKNOWN_ERROR" 表示因服务器错误而无法处理该请求。如果您重试一次,请求可能会成功。

反向地理编码 Plus 代码

地理编码响应中的 plus_code 字段包含一个 Plus 代码,该代码最接近所查询的纬度和经度。此外,在大多数情况下,JSON 结果数组还包含具有 plus_code 类型的完整地理编码结果以及包含 Plus 代码的地址。可保证解码后的 Plus Code 与请求点之间的距离小于 10 米。