地理编码请求和响应

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

请求

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
    按如下格式设置 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。

此请求演示了如何使用 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[] 数组表示返回结果的类型。此数组包含一组零个或多个标记,用于标识结果中返回的地图项类型。例如,“芝加哥”的地理编码会返回“市行政区”,表示“芝加哥”是一个城市;同时返回“政治”,表示它是一个政治实体。如果地址组成部分没有已知类型,那么组成部分可能包含空类型数组。该 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[] 是一个数组,表示邮政编码中包含的所有市行政区。仅当结果是包含多个市行政区的邮政编码时,此字段才会显示。
  • geometry 包含以下信息:
    • location 包含经过地理编码的纬度和经度值。对于正常的地址查询,此字段通常是最重要的。
    • location_type 会存储有关指定位置的其他数据。目前支持以下值:

      • "ROOFTOP" 表示返回的结果是一个精确的地理编码,我们有精确到街道地址的位置信息。
      • "RANGE_INTERPOLATED" 表示返回的结果反映了两个精确点(例如十字路口)之间用内插法计算得到的近似值(通常在道路上)。当某个街道地址的屋顶地理编码不可用时,通常会返回插值结果。
      • "GEOMETRIC_CENTER" 表示返回的结果是多段线(例如街道)或多边形(例如区域)等结果的几何图形中心。
      • "APPROXIMATE" 表示返回的结果是近似值。
    • viewport 包含用于显示返回结果的建议视口,指定为两个纬度/经度值,分别定义视口边界框的 southwestnortheast 角。通常,视口会在向用户显示结果时对结果进行框架处理。
    • bounds(可选返回)存储可完全包含返回结果的边界框。请注意,这些边界可能与推荐的视口不匹配。(例如,旧金山包含法拉隆岛,理论上它是这个城市的一部分,但不应该在视口中返回)。
  • plus_code(请参阅打开的位置代码 Plus Code)是经过编码的位置引用,衍生自纬度和经度坐标,表示面积: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 的默认网域设置为美国,因此“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"
}

组成部分过滤

在地理编码响应中,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 地图一致,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"
}

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

请求:

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