地理编码请求和响应

请求

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 Codes(加号经网址转义为 %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 分别是 street 和 Square 的同义词 匈牙利语
  • region - 地区代码,已指定为 ccTLD (“顶级域”)双字符值。此参数只会 影响,而不是完全限制地理编码器中的结果。(有关 请参阅下面的地区自定义调整)。通过 参数也会影响适用法律所规定的结果。
  • components - 包含元素的组成部分过滤条件 使用竖线 (|) 分隔。组成部分过滤条件为 如果请求不包含 address,则此属性为必需属性。 组成部分过滤器中的每个元素都包含一个 component:value 对,并完全限制结果 。查看更多信息 组成部分过滤
  • extra_computations - 使用此参数可在响应中指定以下附加功能: 。 要针对同一 API 请求启用上述多个功能,请添加 extra_computations 参数, 例如:
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

响应

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

在此示例中,Geocoding API 请求一个 json 对“1600 Amphitheatre Parkway, Mountain View, CA”。

此请求演示了如何使用 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,以获取用于输出处理的一些建议设计模式。

: <ph type="x-smartling-placeholder">
    </ph>
  • XML 结果封装在根 <GeocodeResponse> 元素中。
  • JSON 通过复数数组 (types) 表示包含多个元素的条目, 而 XML 使用多个单数元素 (<type>) 表示这些元素。
  • JSON 中通过空数组来表示空元素,但在 XML 中则完全看不到任何此类元素。未生成任何结果的响应将返回空 results 数组(在 JSON 中),但在 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> elements.)

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

  • 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 包含以下信息: <ph type="x-smartling-placeholder">
      </ph>
    • location 包含经过地理编码的纬度值和经度值。普通 通常这个字段最为重要。
    • location_type 存储有关指定位置的其他数据。通过 目前支持以下值:

      • "ROOFTOP",表示返回的结果是 我们可以提供精确到街道地址的位置信息。
      • "RANGE_INTERPOLATED" 表示返回的结果反映了插值到两个精确点(例如交叉路口)之间的大概位置(通常是在道路上)。当街道的屋顶地理编码不可用时,通常会返回插值结果 地址。
      • "GEOMETRIC_CENTER" 表示 返回的结果是 如多段线(如街道)或多边形(区域)的结果。
      • "APPROXIMATE" 表示返回的结果是大致位置。
    • viewport 包含建议用于显示的视口 返回的结果,指定为两个纬度/经度值,分别定义 southwest和 视口边界框的 northeast 角。视口通常用来在向用户显示结果时为该结果加边框。
    • bounds(可选返回)存储边界框 可完全包含返回的结果。请注意,这些边界可能与 建议视口(例如,在旧金山, 法拉隆群岛 理论上是城市的一部分,但可能不应该在视口中返回。)
  • plus_code(请参阅 打开位置代码Plus Codes)是一种编码 通过纬度和经度坐标衍生的位置参考, 表示面积:1/8000 度 x 1/8000 度(约 14 米 x 赤道 14 米)或更小。Plus Codes 可以用于 没有地址的地点(没有建筑物的信息)中的街道地址 或街道未命名)。该 API 并不总是返回加号编码。

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

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

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

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

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

结果中的 types[] 数组表示地址类型。地址类型的示例包括街道地址、 或政治实体。在 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 参数定义了此边框的西南角和东北角的纬度/经度坐标,并使用竖线字符 (|) 分隔这些坐标。

例如,“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 代码相同,但有一些明显的例外。例如,United 英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb” (技术上适用于“英国 北爱尔兰”)。

地理编码结果可以偏向于正式推出了主要 Google 地图应用的每个区域。请注意,自定义调整仅 优先显示针对特定网域的结果;如果有更相关的结果 也可能包含在内。

例如,“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"
}

“Toledo”的地理编码请求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_codepostal_code匹配 和postal_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"
}