地理编码请求和响应

请求

Google Geocoding API 请求采用以下形式:

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

其中 outputFormat 可以是以下任何一个值:

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

必须提供 HTTPS。

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

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

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

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

  • address - 要进行地理编码的街道地址或 Plus Code。根据相关国家/地区的邮政服务所使用的地址格式指定地址。应避免其他地址元素,例如企业名称和单元、房间或楼层号。街道地址元素应以空格分隔(如下所示,通过网址转义为 %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    按如下格式设置 Plus 代码(加号经网址转义为 %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 标志指示的格式返回,或默认以 JSON 格式返回。

在此示例中,Geocoding API 针对地点 ID 为“ChIJeRpOeF67j4AR9ydy_PIzPuM”的查询请求 json 响应。此地点 ID 对应的是位于 1600 Amphitheatre Parkway, Mountain View, CA 的建筑物。

此请求演示了如何使用 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 响应包含零个或多个 <result> 元素。)

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

  • types[] 数组表示返回结果的类型。此数组包含零个或多个标记,用于标识结果中所返回的地图项的类型。例如,“Chicago”的地理编码会返回“locality”,表示“Chicago”是一个城市;同时返回“political”,表示它是一个政治实体。如果地址组成部分没有已知的类型,组成部分可能具有空的类型数组。API 可能会根据需要添加新的类型值。如需了解详情,请参阅地址类型和地址组成部分
  • formatted_address 是一个字符串,其中包含此位置直观易懂的地址。

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

    设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如,地址“111 8th Avenue, New York, NY”包含以下组成部分:“111”(门牌号)、“8th Avenue”(道路名称)、“New York”(城市)和“NY”(美国州名)。

    请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分,API 响应除了包含设有格式的地址字段外,还包含这些组成部分。

  • address_components[] 是一个数组,其中包含适用于该地址的各个组成部分。

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

    • types[] 是一个数组,表示地址组成部分的类型。请参阅支持的类型列表。
    • long_name 是地理编码器返回的地址组成部分的完整文本说明或名称。
    • short_name 是地址组成部分的缩写文本名称(如果有)。例如,阿拉斯加州的地址组成部分可能包含 long_name“Alaska”和 short_name“AK”(使用 2 个字母的邮编缩写)。

    address_components[] 数组的注意事项如下:

    • 地址组成部分的数组包含的组成部分可能多于 formatted_address
    • 除了 formatted_address 中包含的政治实体之外,数组不一定会纳入包含地址的所有政治实体。若要检索包含特定地址的所有政治实体,您应使用反向地理编码,并将地址的纬度/经度作为参数传递给请求。
    • 两次请求之间的响应格式不一定相同。特别是,address_components 的数量因所请求的地址而异,对于同一个地址,数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组成部分。

    如需处理组成部分的数组,您应解析响应,并通过表达式选择合适的值。请参阅有关 解析响应的指南。

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

      • "ROOFTOP" 表示返回的结果是一个精确的地理编码,我们获得的位置信息可精确到街道地址。
      • "RANGE_INTERPOLATED" 表示返回的结果反映了两个精确点(例如交叉路口)之间用插值计算得到的近似值(通常为道路上)。 当某个街道地址的屋顶地理编码不可用时,通常会返回插值结果。
      • "GEOMETRIC_CENTER" 表示返回的结果是多段线(例如街道)或多边形(例如区域)等结果的几何中心。
      • "APPROXIMATE" 表示返回的结果是近似值。
    • viewport 包含用于显示返回结果的推荐视口,并指定为两个纬度和经度值,分别定义视口边界框的 southwestnortheast 角。通常,视口会在向用户显示结果时用作结果的框架。
    • bounds(选择性返回)存储可完全包含返回结果的边界框。请注意,这些边界可能与建议的视口不一致。(例如,旧金山包含法拉隆岛,理论上讲,该岛是旧金山的一部分,但不应该在视口中返回)。
  • plus_code(请参阅开放位置代码Plus 代码)是根据纬度和经度坐标得出的经过编码的位置引用,表示的区域范围为 1/8000 度、1/8000 度(赤道约 14 米 x 14 米)或更小的区域。Plus Codes 可用于在没有地址的地方(例如建筑物未编号,或者街道未命名)取代街道地址。API 不一定会返回 Plus 代码。

    当服务返回 Plus 代码时,系统会将其格式设置为全局代码和混合代码:

    • global_code 是包含 4 个字符的区号和至少包含 6 个字符的区域代码 (849VCWC8+R9)。
    • compound_code 是至少包含 6 个字符的区域代码,具有明确的位置信息(CWC8+R9, Mountain View, CA, USA)。请勿以程序化方式解析此内容。
    在适用的情况下,该 API 会同时返回全局代码和混合代码。但是,如果结果是在偏远位置(例如海洋或沙漠),系统可能只会返回全局代码。
  • partial_match 表示地理编码器无法返回与原始请求完全匹配的结果,尽管它能够匹配所请求地址的一部分内容。建议您检查一下原始请求中是否存在拼写错误和/或地址不完整的情况。

    部分匹配的最常见原因是请求中所传递的市行政区内不存在相关街道地址。当请求与同一市行政区中的两个或更多位置相匹配时,也可能会返回部分匹配。例如,无论是 Henry Street 还是 Henrietta Street,“Hillpar St, Bristol, UK”都会返回部分匹配。请注意,如果请求中包含拼写错误的地址组成部分,地理编码服务可能会推荐备选地址。通过这种方式触发的建议也将标记为部分匹配。

  • 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 表示国家/地区级别以下的一级行政实体。在美国,这类行政级别是指州。并不是所有国家都设有这类行政级别。在大多数情况下,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 表示已命名的地图注点。通常情况下,这些“地图注点”是当地的著名实体,无法轻易归入其他类别,例如“帝国大厦”或“埃菲尔铁塔”。

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

除了上述类型之外,地址组成部分还可能包括此处列出的类型。此列表并非详尽无遗,并且可能会发生变化。

  • floor 表示某个建筑物地址的楼层。
  • establishment 通常表示某个尚未归类的地点。
  • landmark 表示附近的地点,可用作辅助导航的参考。
  • point_of_interest 表示已命名的地图注点。
  • parking 表示停车场或停车楼。
  • post_box 表示特定的邮箱。
  • postal_town 表示地理区域分组(例如 localitysublocality),在某些国家/地区用于邮寄地址。
  • room 表示某个建筑物地址的房间。
  • street_number 表示精确的门牌号。
  • bus_stationtrain_stationtransit_station 分别表示公交车、火车或公共交通车站的位置。

视口自定义调整

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

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

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

请求:

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 地图应用的每个网域,都可以对地理编码结果进行偏向。请注意,自定义调整只是优先显示特定网域的结果;如果此网域外存在更相关的结果,也可能会将这些结果包括在内。

例如,由于 Geocoding API 的默认网域设置为美国,因此“托莱多”的地理编码会返回以下结果。请求:

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

响应:

{
   "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

针对“High St, Hastings”的地理编码,其中包含 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"
}

针对“Santa Cruz”(圣克鲁斯)市行政区的地理编码请求(值为 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"
}