地理编码请求和响应

请求

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 选择返回的结果集以及结果的返回顺序影响较小。 地理编码器对缩写词的解读因语言而异，例如街道类型的缩写词，或者在一种语言中有效但在其他语言中无效的同义词。例如，utca 和 tér 在匈牙利语中分别是街道和广场的同义词。
  • region - 地区代码，指定为一个 ccTLD（“顶级域名”）双字符值。此参数只会影响但不会完全限制地理编码器中的结果。（如需了解详情，请参阅下文的地区自定义调整部分）。根据适用法律，此参数也可能会影响结果。
  • components - 一个组成部分过滤器，其元素由竖线 (|) 分隔。如果请求不包含 address，则必须使用组成部分过滤器。组成部分过滤器中的每个元素由一个 component:value 对组成，并会完全限制地理编码器中的结果。如需了解详情，请参阅下文的组成部分过滤。
  • extra_computations - 使用此参数在响应中指定以下其他功能： 如需为同一 API 请求启用上述多个功能，请在每个功能的请求中添加 extra_computations 参数，例如： 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

响应

地理编码响应以网址请求中的 output 标志指示的格式返回，默认情况下以 JSON 格式返回。

在此示例中，Geocoding API 请求针对地址“1600 Amphitheatre Parkway, Mountain View, CA”查询的 json 响应。

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

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&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"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "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" 通常表示缺少查询参数（address、components 或 latlng）。
  • "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 包含用于显示返回结果的推荐视口，指定为两个纬度/经度值，分别定义视口边界框的 southwest 和 northeast 角。通常，该视口用于在向用户显示结果时对结果进行框架处理。
    • bounds（可选返回）存储可完全包含返回结果的边框。请注意，这些边界可能与推荐的视口不一致。（例如，旧金山包含法拉隆群岛，理论上后者是前者的一部分，但可能不应该在视口中返回。）
  • plus_code（请参阅 Open Location Code 和 Plus Codes）是一种编码的位置引用，派生自纬度和经度坐标，表示一个区域：1/8000 度 x 1/8000 度（赤道上约 14 米 x 14 米）。Plus Code 可用于在没有地址的地点（例如建筑物未编号，或者街道未命名）取代街道地址。该 API 不一定会返回 Plus 代码。

    如果服务确实返回了 Plus Code，其格式为全局代码和混合代码：

    • 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[] 数组，用于指示地址各个部分的类型。例如门牌号或国家/地区。（以下是类型的完整列表。）地址可能有多种类型。这些类型可能会被视为“标记”。 例如，许多城市都带有 political 和 locality 类型的标记。

地理编码器以地址类型和地址组成部分类型数组这两种形式支持并返回以下类型：

  • 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 表示已命名的地图注点。通常情况下，这些“地图注点”是当地的著名实体，无法轻易归入其他类别，例如“帝国大厦”或“埃菲尔铁塔”。

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

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

  • floor 表示某个建筑物地址的楼层。
  • establishment 通常表示某个尚未归类的地点。
  • landmark 表示附近的地点，可用作辅助导航的参考。
  • point_of_interest 表示已命名的地图注点。
  • parking 表示停车场或停车楼。
  • post_box 表示特定的邮箱。
  • postal_town 表示地理区域分组（例如 locality 和 sublocality），在某些国家/地区用于邮寄地址。
  • room 表示某个建筑物地址的房间。
  • street_number 表示精确的门牌号。
  • bus_station、train_station 和 transit_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 地图主应用的每个网域，都可以对地理编码结果进行偏向设置。请注意，自定义调整只是优先显示特定网域的结果；如果在此网域以外存在更相关的结果，也可能会将这些结果包括在内。

例如，由于 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（西班牙）对“托莱多”的地理编码请求将返回西班牙的城市。

请求：

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_code 与 postal_code 和 postal_code_prefix 匹配。
  • country 用于匹配国家/地区名称或两个字母的 ISO 3166-1 国家/地区代码。该 API 按照 ISO 标准来定义国家/地区，因此，过滤时使用国家/地区对应的 ISO 代码，效果最好。

以下 components 可能会影响结果，但不会强制执行：

  • route 用于匹配路线的全称或简称。
  • locality 用于匹配 locality 和 sublocality 类型。
  • administrative_area 用于匹配所有 administrative_area 级别。

关于组成部分过滤的注意事项：

  • 请勿在请求中重复这些组件过滤条件，否则 API 将返回 Invalid_request：country、postal_code、route
  • 如果请求包含重复的组成部分过滤条件，则 API 会将这些过滤条件视为 AND，而不是 OR。
  • 结果与 Google 地图一致，后者有时会产生意外的 ZERO_RESULTS 响应。在某些用例中，使用地点自动补全可能会提供更好的结果。如需了解详情，请参阅此常见问题解答。
  • 对于每个地址组成部分，可以在 address 参数或 components 过滤器中指定，但不能同时在两者中指定。在这两者中指定相同的值可能会导致 ZERO_RESULTS。

使用 components=country:GB 对“High St, Hastings”进行地理编码时，系统会返回英格兰黑斯廷斯的结果，而不是美国哈得孙黑斯廷斯的结果。

请求：

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