地理编码请求和响应

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

请求

Geocoding API 请求的格式如下:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

其中,outputFormat 可以是以下两个值中的任意一个:

  • json(推荐)表示以 JavaScript 对象表示法 (JSON) 的形式输出;或
  • xml 表示以 XML 格式输出

使用 API 密钥的请求需要使用 HTTPS。

有些参数是必需的,有些则是可选的。根据网址的标准,参数使用和号字符 (&) 进行分隔。

本页面的其余部分分别介绍了地理编码和反向地理编码,因为每种类型的请求都适用不同的参数。

地理编码(纬度/经度查询)参数

地理编码请求中的必需参数

  • address - 要进行地理编码的街道地址或 Plus Code。请根据相关国家/地区的邮政服务所使用的地址格式指定地址。应避免使用其他地址元素,例如商家名称和单元、房间号或楼层号。街道地址元素应以空格分隔(此处显示为网址转义为 %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    格式加号代码(如下所示)(加号经网址转义为 %2B,空格经网址转义为 %20):
    • 全局代码是一个由 4 个字符组成的区号和至少包含 6 个字符的区域代码(849VCWC8+R9 为 849VCWC8%2BR9)。
    • 复合代码是至少包含 6 个字符的本地代码,具有明确的位置信息(CWC8+R9 Mountain View, CA, USA 为 CWC8%2BR9%20Mountain%20View%20CA%20USA)。

    --OR--
    components - 包含以竖线 (|) 分隔元素的组件过滤条件。如果提供了 address,则组件过滤条件也可作为可选参数接受。 组件过滤器中的每个元素都由一个 component:value 对组成,并完全限制地理编码器中的结果。请参阅下文,详细了解组件过滤
  • key - 您的应用的 API 密钥。此密钥用于标识您的应用,以便进行配额管理。了解如何获取密钥

如需更多指导,请参阅常见问题解答

地理编码请求中的可选参数

  • bounds - 视口的边界框,要在其中使地理编码结果更显眼。此参数只会影响,而不会完全限制地理编码器中的结果。(如需了解详情,请参阅下面的视口偏向。)
  • language - 返回结果时使用的语言。
    • 请参阅支持的语言列表。Google 会经常更新支持的语言,因此该列表可能并不详尽。
    • 如果未提供 language,地理编码器会尝试使用 Accept-Language 标头中指定的首选语言,或发出请求的网域的原生语言。
    • 地理编码器会尽力提供可供用户和本地用户读取的街道地址。为实现这一目标,它会以当地语言返回街道地址,并在必要时转译为用户能看懂的脚本,并采用首选语言。所有其他地址都会以首选语言返回。地址组成部分均以从第一个组成部分中选择的同一语言返回。
    • 如果某个首选语言中没有相应名称,地理编码器会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及这些结果的返回顺序影响较小。地理编码器会根据语言以不同方式解读缩写,例如街道类型的缩写,或可能对一种语言有效但不另一种语言的同义词。例如,在匈牙利语中,utcatér 分别是街道和方形的同义词。
  • region - 区域代码,指定为 ccTLD(“顶级域名”)双字符值。此参数只会影响(而不会完全限制)地理编码器中的结果。(如需了解详情,请参阅下文的区域偏向)。
  • components - 组成部分过滤器,各元素间用竖线符 (|) 进行分隔。如果请求中不包含 address,则该组成部分过滤器是必需字段。组件过滤器中的每个元素都由一个 component:value 对组成,并完全限制地理编码器中的结果。请参阅下文,详细了解组件过滤

响应

地理编码响应以网址请求路径中的 output 标志指示的格式返回。

在此示例中,Geocoding API 请求对地点 ID“ChIJeRpOeF67j4AR9ydy_PIzPuM”进行查询的 json 响应,该 ID 是位于 1600 Amphitheatre Parkway, Mountain View, CA 的 place_ID。

此请求演示了如何使用 JSON output 标志:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

此请求演示了如何使用 XML output 标志:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

选择下面的标签页以查看示例 JSON 和 XML 响应。

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

请注意,JSON 响应包含两个根元素:

  • "status" 包含请求中的元数据。请参阅下面的状态代码
  • "results" 包含经过地理编码的地址信息和几何图形信息的数组。

通常,在进行地址查询时,只会返回 "results" 数组中的一个条目,不过在进行模糊地址查询时,地理编码器可能会返回多个结果。

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

请注意,XML 响应包含一个 <GeocodeResponse> 和两个顶级元素:

  • <status> 包含请求中的元数据。请参阅下面的状态代码
  • 零个或多个 <result> 元素,每个元素包含一组经过地理编码的地址信息和几何图形信息。

XML 响应要比 JSON 响应长得多。因此,除非您的服务出于某些原因需要 xml,否则我们建议使用 json 作为首选输出标志。此外,处理 XML 树时需要小心谨慎,以便引用正确的节点和元素。如需了解用于输出处理的一些建议设计模式,请参阅使用 XPath 解析 XML

  • XML 结果会封装在根 <GeocodeResponse> 元素中。
  • JSON 通过复数数组 (types) 表示包含多个元素的条目,而 XML 则使用多个单数元素 (<type>) 表示这些条目。
  • 空白元素在 JSON 中通过空数组表示,但在 XML 中通过任何此类元素表示。例如,未生成任何结果的响应将会在 JSON 中返回一个空的 results 数组,但在 XML 中不会返回任何 <result> 元素。

状态代码

地理编码响应对象中的 "status" 字段包含请求的状态,并且可能会包含调试信息,以帮助您查明地理编码不起作用的原因。"status" 字段可能包含以下值:

  • "OK" 表示未发生错误;地址已成功解析,并且至少返回了一个地理编码。
  • "ZERO_RESULTS" 表示地理编码成功,但未返回任何结果。如果向地理编码器传递了不存在的 address,就可能会发生这种情况。
  • OVER_DAILY_LIMIT 表示以下任意值:
    • API 密钥缺失或无效。
    • 您的帐号尚未启用结算功能。
    • 超出了您设定的用量上限。
    • 提供的付款方式不再有效(例如,信用卡已过期)。

    请参阅 Google 地图常见问题解答,了解如何解决此问题。

  • "OVER_QUERY_LIMIT" 表示您超出了配额。
  • "REQUEST_DENIED" 表示您的请求已被拒绝。
  • "INVALID_REQUEST" 通常表示缺少查询(addresscomponentslatlng)。
  • "UNKNOWN_ERROR" 表示由于服务器错误而无法处理请求。如果您重试,请求可能会成功。

错误消息

当地理编码器返回除 OK 之外的状态代码时,地理编码响应对象中可能会包含额外的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

成效

当地理编码器返回结果时,会将这些结果放在 (JSON) results 数组中。即使地理编码器没有返回任何结果(例如,如果地址不存在),它仍然会返回一个空的 results 数组。(XML 响应不包含或包含多个 &lt;result&gt; 元素。)

典型的结果包含以下字段:

  • types[] 数组表示返回结果的类型。此数组包含一组零个或多个标记,这些标记用于标识结果中返回的特征类型。例如,“芝加哥”的地理编码会返回“芝加哥”和“政治”,这表示它是一个城市,它也会返回“政治”来表明它是政治实体。
  • formatted_address 是一个包含此营业地点的人类可读地址的字符串。

    通常该地址相当于邮政地址。请注意,由于许可限制,有些国家/地区(例如英国)不允许发布真实的邮政地址。

    格式化的地址在逻辑上由一个或多个地址组成部分组成。例如,“111 8th Avenue, New York, NY”包含以下组成部分:&q 111”(街道号码)、“8th Avenue”(城市)、“NY”(纽约市)和“NY”(美国的一个州)。

    请勿以编程方式解析格式化的地址。相反,除了 API 格式的地址字段之外,您还应使用 API 响应包含的各个地址组成部分。

  • address_components[] 是一个数组,包含适用于该地址的单独组件。

    通常,每个地址组成部分都包含以下字段:

    • types[] 是一个数组,表示地址组成部分的类型。请参阅支持的类型列表。
    • long_name 是地址解析器返回的完整文本说明或地址组成部分的名称。
    • short_name 是地址组成部分的缩写文本名称(如果有)。例如,阿拉斯加州的地址组成部分可能具有“阿拉斯加”的 long_nameshort_name 为“AK”的双字母邮政缩写。

    请注意关于 address_components[] 数组的以下事实:

    • 地址组成部分的数组可能包含比 formatted_address 更多的组成部分。
    • formatted_address 中包含的政治实体之外,该数组不一定包含所有政治实体。要检索包含特定地址的所有政治实体,您应使用反向地理编码,将地址的纬度/经度作为参数传递给请求。
    • 响应的格式不能保证各个请求保持不变。具体而言,address_components 数量取决于所请求的地址,并且可能会随着同一地址而不断变化。组件可以更改在数组中的位置。该组件的类型可能会发生变化。特定组件在后续响应中可能会缺失。

    如需处理组件数组,您应解析响应并通过表达式选择适当的值。请参阅解析响应指南。

  • postcode_localities[] 是一个数组,表示邮政编码中包含的所有市行政区。仅当结果是包含多个市行政区的邮政编码时,此字段才会显示。
  • geometry 包含以下信息:
    • location 包含经过地理编码的纬度值和经度值。对于普通的地址查询,此字段通常是最重要的。
    • location_type 会存储关于指定位置的额外数据。目前支持以下值:

      • "ROOFTOP" 表示返回的结果是一个精确的地理编码,我们有精确到街道地址的位置信息。
      • "RANGE_INTERPOLATED" 表示返回的结果反映了两个精确点(例如交叉路口)之间用内插法计算得到的近似值(通常在道路上)。当某个街道地址的屋顶地理编码不可用时,通常会返回插值结果。
      • "GEOMETRIC_CENTER" 表示返回的结果是多段线(例如街道)或多边形(区域)等结果的几何中心。
      • "APPROXIMATE" 表示返回的结果是近似值。
    • viewport 包含用于显示返回结果的推荐视口,指定为两个纬度/经度值,分别用于定义视口边界框的 southwestnortheast 角。一般而言,视口用于在向用户显示结果时呈现结果。
    • bounds(可选返回)可存储可完全包含返回结果的边界框。请注意,这些边界可能与建议的视口不匹配。(例如,旧金山包含法拉隆群岛,该岛实际上是旧金山市的一部分,但不应该在视口内返回。)
  • plus_code(请参阅打开位置代码 Plus 代码)是基于纬度和经度坐标推导的编码位置引用,表示面积:1/8000 度、1/8000 度(赤道约 14 米 x 14 米)。Plus 代码可用于替换不存在的地点(建筑物没有编号或街道未命名)中的街道地址。

    Plus 代码采用全局代码和复合代码格式:

    • global_code 是包含 4 个字符的区号和至少 6 个字符的当地代码 (849VCWC8+R9)。
    • compound_code 是包含 6 个字符或更长时间的本地代码,具有明确位置(CWC8+R9,Mountain View, CA, USA)。请勿以编程方式解析此内容。
    通常,系统会同时返回全局代码和复合代码。不过,如果结果位于偏远地区(例如海洋或沙漠),系统可能只会返回全球代码。
  • partial_match 表示地理编码器未针对原始请求返回完全匹配,但能够匹配所请求的地址的一部分。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

    部分匹配最常出现在不在您传递的请求中所处的市行政区内街道地址。当请求与同一市行政区内的两个或更多位置匹配时,也可能会返回部分匹配项。例如,“Hillpar St, Bristol, UK”将同时返回 Henry Street 和 Henrietta Street 的部分匹配结果。请注意,如果请求中包含拼写错误的地址组成部分,地理编码服务可能会建议一个备用地址。以这种方式触发的建议也将被标记为部分匹配。

  • place_id 是可以与其他 Google API 搭配使用的唯一标识符。例如,您可以在 Places API 请求中使用 place_id 来获取本地商家的详细信息,例如电话号码、营业时间、用户评价等。请参阅地点 ID 概览

地址类型和地址组成部分类型

结果中的 types[] 数组表示地址类型。地址类型的示例包括街道地址、国家/地区或政治实体。address_components[] 中还有一个 types[] 数组,用于指明地址各个部分的类型。示例包括门牌号码或国家/地区。(以下是类型的完整列表。)地址可能有多种类型。这些类型可能会被视为“标签”。 例如,许多城市都带有 politicallocality 类型标记。

地理编码器在地址类型和地址组成部分类型数组中支持并返回以下类型:

  • street_address 表示精确的街道地址。
  • route 表示已命名的路线(例如“US 101”)。
  • intersection 表示主要交叉路口,通常是两条主要道路的交叉路口。
  • political 指示政治实体。此类型通常表示某个民用行政区域的多边形。
  • country 表示国家/地区政治实体,通常是地理编码器返回的最高顺序类型。
  • administrative_area_level_1 表示国家/地区级别以下的一级行政实体。在美国,这类行政级别是指州。并非所有国家/地区都有这些行政级别。在大多数情况下,admin_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 Code 可在没有街道地址(建筑物没有编号或街道未命名)中用于代替街道地址。如需了解详情,请参阅 https://plus.codes
  • postal_code 表示邮政编码,用于表示相应国家/地区内的邮政地址。
  • natural_feature 表示醒目的自然地图项。
  • airport 表示机场。
  • park 表示已命名的公园。
  • point_of_interest 表示已命名的兴趣点。通常,这些“地图注点”是不易归入其他类别的著名地方实体,如“帝国大厦”或“埃菲尔铁塔”。

空类型列表表示特定地址组成部分没有已知类型,例如法国的 Lieu-dit。

除上述内容外,地址组成部分还可能包括此处列出的类型。此列表并非详尽无遗,并且随时可能会更改。

  • floor 表示建筑物地址的楼层。
  • establishment 通常表示地点尚未分类。
  • landmark 表示附近的地点,以帮助辅助导航。
  • point_of_interest 表示已命名的兴趣点。
  • parking 表示停车场或停车结构。
  • post_box 表示特定邮政信箱。
  • postal_town 指示用于某些国家/地区的邮寄地址的分组,如 localitysublocality
  • room 表示建筑物地址的房间号。
  • street_number 表示确切的门牌号码。
  • bus_stationtrain_stationtransit_station 指示公交、火车或公共交通车站的位置。

视口自定义调整

在地理编码请求中,您可以指示地理编码服务优先显示指定视口(表示为边界框)内的结果。为此,您可以在请求网址中设置 bounds 参数。

bounds 参数定义了此边界框的西南角和东北角的纬度/经度坐标,并使用竖线 (|) 字符分隔坐标。

例如,对“Washington”的地理编码通常会返回美国的华盛顿州:

请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

但是,如果添加 bounds 参数以定义美国东北部周围的边界框,则会导致此地理编码返回华盛顿特区。

请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

区域偏向

在地理编码请求中,您可以使用 region 参数指示地理编码服务返回偏向特定区域的结果。此参数采用用于指定区域偏向的 ccTLD(国家/地区代码顶级域名)参数。大多数 ccTLD 代码都与 ISO 3166-1 代码相同,但也有一些需要注意的例外情况。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(特指“大不列颠及北爱尔兰联合王国”实体)。

对于正式启动了主 Google 地图应用的每个网域,地理编码结果都可以自定义。请注意,偏向仅优先显示特定网域的结果;如果此网域外存在更相关的结果,也可能会将其包含在内。

例如,对“Toledo”的地理编码会返回此结果,因为 Geocoding API 的默认区域设置为美国。请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=AIzaSyCaor12zcAJ3XgISkD8zsoaQ64PAlDgBrs

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

包含 region=es(西班牙)的“Toledo”地理编码请求会返回西班牙城市。

请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

组成部分过滤

在地理编码响应中,Geocoding API 可以返回仅限于特定区域的地址结果。您可以使用 components 过滤条件指定限制。过滤器包含由竖线 (|) 分隔的 component:value 对列表。过滤器值支持与其他地理编码请求相同的拼写纠正和部分匹配方法。如果地理编码器发现组成部分过滤器的部分匹配,则响应中会包含 partial_match 字段。

可过滤的 components 包括:

  • postal_codepostal_codepostal_code_prefix 匹配。
  • country 与国家/地区名称或两个字母的 ISO 3166-1 国家/地区代码匹配。该 API 遵循 ISO 标准来定义国家/地区,当使用相应国家/地区的相应 ISO 代码时,过滤效果最佳。

以下 components 可用于影响结果,但不会强制执行:

  • route 匹配路由的长名称或短名称。
  • localitylocalitysublocality 类型匹配。
  • administrative_area 匹配所有 administrative_area 级别。

关于组件过滤的注意事项:

  • 请勿在请求中重复这些组件过滤条件,否则该 API 将返回 Invalid_requestcountrypostal_coderoute
  • 如果请求包含重复的组件过滤条件,则 API 会将这些过滤条件的求值结果为 AND(而非 OR)。
  • 结果与 Google 地图一致,后者偶尔会产生意外的 ZERO_RESULTS 响应。在某些情况下,使用地点自动补全功能可能会提供更好的结果。如需了解详情,请参阅此常见问题解答
  • 对于每个地址组成部分,要么在 address 参数中指定,要么在 components 过滤条件中指定,但不能同时指定这两者。两者都指定相同的值可能会导致 ZERO_RESULTS

使用 components=country:GB 对“高街、黑斯廷斯”进行地理编码时,返回英格兰的黑斯廷斯,而不是美国的黑斯廷斯-哈德逊。

请求:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

包含 components=country:ES 的“圣克鲁斯”市行政区的地理编码请求会返回西班牙加那利群岛的圣克鲁斯 - 特内里费。

请求:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

只有当您提供相互排除的过滤器时,组件过滤才会返回 ZERO_RESULTS 响应。

请求:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

响应:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

您可以使用 components 过滤条件,在没有地址参数的情况下进行有效查询。(对完整地址进行地理编码时,如果请求包含建筑物的名称和数量,则需要 address 参数。)

请求:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}