地理编码请求和响应

欧洲经济区 (EEA) 开发者

请求

Geocoding API 请求采用以下格式：

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

其中，outputFormat 可以是以下任一值：

  • json（推荐）表示以 JavaScript 对象表示法 (JSON) 格式输出；或者
  • xml 表示以 XML 格式输出

必须使用 HTTPS。

某些参数是必需的，而有些则是可选的。依照网址的标准，参数使用“与”符号 (&) 分隔。

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

地理编码（纬度/经度查找）参数

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

  • key - 您应用的 API 密钥。此密钥用于标识您的应用，以便进行配额管理。了解如何获取密钥。

  • 您必须在请求中指定 address 和/或 components：

    • address - 要进行地理编码的街道地址或 Plus Code。根据相关国家/地区的邮政服务所使用的地址格式指定地址。应避免使用其他地址元素，例如企业名称、单元号、房间号或楼层号。街道地址元素应以空格分隔（此处显示为网址转义的 %20）： 
      address=24%20Sussex%20Drive%20Ottawa%20ON
       按如下格式设置 Plus Codes（加号经网址转义为 %2B，空格经网址转义为 %20）：
      • 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码（849VCWC8+R9 为 849VCWC8%2BR9）。
      • 混合代码是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9 Mountain View, CA, USA 为 CWC8%2BR9%20Mountain%20View%20CA%20USA）。
    • components - 一种组件过滤器，其中的元素以竖线 (|) 分隔。如果提供了 address，则组件过滤器也可作为可选参数接受。 组成部分过滤条件中的每个元素都包含一个 component:value 对，并且会完全限制地理编码器中的结果。如需了解详情，请参阅下文的组成部分过滤。

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

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

  • 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 响应长得多。因此，我们建议您使用 json 作为首选输出标志，除非您的服务因某种原因需要 xml。此外，处理 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" 表示返回的结果反映了插值到两个精确点（例如交叉路口）之间的大概位置（通常是在道路上）。 当某个街道地址的 rooftop 地理编码不可用时，通常会返回插值结果。
      • "GEOMETRIC_CENTER" 表示返回的结果是多段线（例如街道）或多边形（区域）等结果的几何图形中心。
      • "APPROXIMATE" 表示返回的结果是大概位置。
    • viewport 包含用于显示返回结果的推荐视口，以两个纬度/经度值表示，这两个值用于定义视口边界框的 southwest 和 northeast 角。通常，视口用于在向用户显示结果时框定结果。
    • bounds（选择性返回）存储可完全包含返回结果的边界框。ليزانشئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئلئ（例如，旧金山包含法拉隆群岛，理论上后者是前者的一部分，但不应该在视口中返回）。
  • plus_code（请参阅 Open Location Code 和 Plus Codes）是经过编码的位置引用，衍生自纬度和经度坐标，表示面积不超过 1/8, 000 度 x 1/8, 000 度（在赤道处约为 14 米 x 14 米）的区域。在没有地址的地点（例如建筑物未编号，或者街道未命名），Plus Codes 可用于取代街道地址。该 API 并不总是返回 Plus Code。

    如果服务确实返回了 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_component 字段中的 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 地图应用正式发布的每个网域，地理编码结果都可以偏向特定地区。请注意，自定义调整只是优先显示特定网域的结果；如果在此网域以外存在更相关的结果，也可能会将这些结果包括在内。

例如，由于地理编码 API 的默认网域设置为美国，因此“Toledo”的地理编码会返回以下结果：请求：

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

组成部分过滤

在地理编码响应中，地理编码 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 回答。在某些使用情形下，使用地点自动补全功能可能会提供更好的结果。argas 如需了解详情，请参阅此常见问题解答。
  • 对于每个地址组成部分，您可以在 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"
}