谷歌地图开发：地理编码和反地理编码

2019-11-09 14:41:19

字体：大中小

来源：转载

供稿：网友

谷歌地图Geocoding说明：内容主要来自谷歌官网的文档，谷歌地图android api地理和反地理编码反应迟钝内容有时不准确，这里使用的googlemap的webapi接口。嗯，需要vpn这个不多做说明了...

什么是地理编码？

地理编码是将地址（如“1600 Amphitheatre Parkway, Mountain View, CA”）转换为地理坐标（如纬度 37.423021 和经度 -122.083739）的过程，您可以借此在地图上放置标记，或在地图上定位。

反向地理编码是将地理坐标转换为可人工读取的地址的过程。Google Maps Geocoding API 的反向地理编码服务还可让您找到对应于给定的地点 ID 的地址。

Google Maps Geocoding API 提供了一种通过 HTTP 请求来访问这些服务的直接方法。

开始前的准备工作

本文档面向需要使用其中一个 Google Maps API 提供的地图中地理编码数据的网站和移动开发者。

此服务通常用于对（预先知道的）静态地址进行地理编码，以便将应用内容放置到地图上；例如，此服务不用于实时响应用户输入。有关动态地理编码（例如，在某个用户界面元素内）的信息，请查阅关于 Google Maps javaScript API 客户端地理编码器和/或 Google Play 服务 Location API 的文档。

地理编码是一项时间和资源密集型任务。只要有可能，请（使用此处所描述的 Google Maps Geocoding API 或其他地理编码服务）对已知地址进行预地理编码，并将结果存储在您自己的设计的临时缓存中。

要使用 Google Maps Geocoding API，您需要一个 API 密钥。

Google Maps Geocoding API 请求格式

Google Maps Geocoding API 请求必须采用以下形式：

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

其中，output 可以是以下值之一：

json（推荐）指示以 Javascript 对象标记 (JSON) 输出xml 指示以 XML 格式输出

如需通过 HTTP 访问 Google Maps Geocoding API，请使用：

http://maps.googleapis.com/maps/api/geocode/output?parameters

对于请求中包含敏感用户数据（例如用户的位置）的应用，不建议使用 HTTP。

有些参数是必填的，而有些是可选的。依照 URL 的标准，参数都使用“与”字符 (&) 分隔。

Google Maps API for Work 用户必须在其地理编码请求中包含有效的 client 和 signature 参数。如需了解详细信息，请参阅 Google Maps API for Work Web Services。

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

地理编码（纬度/经度查询）

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

address – 要进行地理编码的街道地址，采用相关国家/地区的全国邮政服务所使用的格式。应避免其他地址元素，例如企业名称以及单元号、套房号或楼层。或 components – 您希望获得其地理编码的组成部分过滤器。如需了解详细信息，请参阅组成部分过滤。如果提供了 address，还将接受组成部分过滤器作为可选参数。key – 您的应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。

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

bounds – 视口的边框，在其中可以使地理编码结果更显著地发生偏向。此参数只会影响，而不会完全限制地理编码器中的结果。（如需了解详细信息，请参阅下面的视口偏向。）language – 返回结果时使用的语言。请参阅支持的区域语言列表。请注意，我们会经常更新支持的语言，因此，此列表可能并不全面。如果未提供 language，地理编码器将尽可能尝试使用发送请求区域的当地语言。region – 地区代码，指定为一个 ccTLD（“顶级域名”）双字符值。此参数只会影响，而不会完全限制地理编码器中的结果。（如需了解详细信息，请参阅下面的地区偏向。）components – 组成部分过滤器，用管道符号 (|) 分隔。每个组成部分过滤器由一个 component:value 对组成，将完全限制地理编码器中的结果。如需了解详细信息，请参阅下面的组成部分过滤。Supported Languages

Language Code	Language	Language Code	Language
ar	Arabic	kn	Kannada
bg	Bulgarian	ko	Korean
bn	Bengali	lt	Lithuanian
ca	Catalan	lv	Latvian
cs	Czech	ml	Malayalam
da	Danish	mr	Marathi
de	German	nl	Dutch
el	Greek	no	Norwegian
en	English	pl	Polish
en-AU	English (Australian)	pt	Portuguese
en-GB	English (Great Britain)	pt-BR	Portuguese (Brazil)
es	Spanish	pt-PT	Portuguese (Portugal)
eu	Basque	ro	Romanian
eu	Basque	ru	Russian
fa	Farsi	sk	Slovak
fi	Finnish	sl	Slovenian
fil	Filipino	sr	Serbian
fr	French	sv	Swedish
gl	Galician	ta	Tamil
gu	Gujarati	te	Telugu
hi	Hindi	th	Thai
hr	Croatian	tl	Tagalog
hu	Hungarian	tr	Turkish
id	Indonesian	uk	Ukrainian
it	Italian	vi	Vietnamese
iw	Hebrew	zh-CN	Chinese (Simplified)
ja	Japanese	zh-TW	Chinese (Traditional)

地理编码响应

地理编码响应以 URL 请求路径中 output 标志指示的格式返回。

在此示例中，Google Maps 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 响应示例。

JSONXML

{ "results" : [ { "address_components" : [ { "long_name" : "1600", "short_name" : "1600", "types" : [ "street_number" ] }, { "long_name" : "Amphitheatre Pkwy", "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 Parkway, Mountain View, CA 94043, USA", "geometry" : { "location" : { "lat" : 37.4224764, "lng" : -122.0842499 }, "location_type" : "ROOFTOP", "viewport" : { "northeast" : { "lat" : 37.4238253802915, "lng" : -122.0829009197085 }, "southwest" : { "lat" : 37.4211274197085, "lng" : -122.0855988802915 } } }, "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA", "types" : [ "street_address" ] } ], "status" : "OK"}

请注意，JSON 响应包含两个根元素：

"status" 包含请求的元数据。请参阅下面的状态代码。"results" 包含一个有关地理编码地址信息和几何信息的数组。

虽然当地址查询比较模糊时，地理编码器可能返回多个结果，但通常地址查找只返回 "results" 数组中的一个条目。

请注意，如果您想从结果中提取值，通常需要对这些结果进行解析。JSON 的解析相对容易。如需了解一些推荐的设计模式，请参阅解析 JSON。

状态代码

地理编码响应对象中的 "status" 字段包含了请求的状态，还可能包含调试信息，以帮助您查明地理编码不工作的原因。"status" 字段可以包含以下值：

"OK" 表示未出现任何错误；已成功解析地址，并且至少返回了一个地理编码。"ZERO_RESULTS" 表示地理编码成功，但未返回任何结果。如果向地理编码器传递了一个不存在 address，就可能会发生这种情况。"OVER_QUERY_LIMIT" 表示您已超出配额。"REQUEST_DENIED" 表示系统已拒绝您的请求。"INVALID_REQUEST" 一般表示缺少查询（address、components 或 latlng）。"UNKNOWN_ERROR" 表示由于服务器发生错误，因此无法处理该请求。如果您重试一次，请求可能会成功

错误消息

当地理编码器返回 OK 以外的状态代码时，地理编码响应对象中可能会包含一个附加的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

注：此字段不保证始终出现，并且其内容可能会更改。

结果

当地理编码器返回结果时，会将这些结果放在一个 (JSON) results 数组中。即使地理编码器没有返回任何结果（例如，如果地址不存在），它仍然会返回一个空的 results 数组。（XML 响应包含零个或更多个 <result> 元素。）

典型的结果由以下字段组成：

types[] 数组表示返回结果的类型。此数组包含一组标记（可能为零个或多个），用于标识结果中所返回特征的类型。例如，“芝加哥”的地理编码返回“locality”，这表明“芝加哥”是一个城市，并且还返回“political”，这表明它是一个政治实体。

formatted_address：是一个包含此位置可人工读取的地址的字符串。通常此地址相当于“邮政地址”，有时会因国家/地区而异。（请注意，由于许可限制，某些国家（如英国）不允许发布真实的邮政地址。）此地址通常由一个或多个地址组成部分组成。例如，地址“111 8th Avenue, New York, NY”包含以下地址组成部分：“111”（街道号）、“8th Avenue”（道路）、“New York”（城市）和“NY”（美国的一个州）。这些地址组成部分包含如下所述的附加信息。

address_components[] 是包含独立的地址组成部分的数组，如上所述。通常，每个 address_component 均包含：

types[]，一个表示地址组成部分类型的数组。long_name 是地理编码器返回的地址组成部分的完整文本说明或名称。short_name 是地址组成部分的文本名称缩写（如有）。例如，Alaska 州的地址组成部分可以有 long_name“Alaska”和 short_name“AK”（使用双字母邮政缩写表示）。

请注意，address_components[] 中包含的地址组成部分可能比 formatted_address 中记录的更多。

postcode_localities[] 是一个数组，表示一个邮政编码中包含的所有地方。只有当结果是一个包含多个地方的邮政编码时，才会有此数组。

geometry 包含以下信息：

location：其中包含地理编码经度、纬度值。对于普通的地址查找，此字段通常是最重要的。

location_type 存储有关指定位置的附加数据。目前支持以下值：

"ROOFTOP" 表示返回的结果是一个精确的地理编码，我们使其位置信息精确到街道地址的精度。"RANGE_INTERPOLATED" 表示返回的结果反映了两个精确点（例如交叉路口）之间用内插法计算得到的近似值（通常在道路上）。当某个街道地址的 rooftop 地理编码不可用时，通常会返回内插值结果。"GEOMETRIC_CENTER" 表示返回的结果是某个位置（如多段线（例如街道）或多边形（地区））的几何中心。"APPROXIMATE" 表示返回的结果是近似值。viewport 包含用于显示返回结果的推荐视口，指定为两个纬度、经度值，分别定义视口边框的 southwest 和 northeast 角。视口通常用来在向用户显示结果时为该结果加边框。bounds（可选返回）存储可完全包含返回结果的边框。请注意，这些边界可能与推荐的视口不一致。（例如，旧金山包含费拉隆岛，理论上它是这个城市的一部分，但可能不应该在视口中返回。）

partial_match 表示虽然地理编码器能够匹配所请求的地址的一部分，但它未能返回原始请求的精确匹配项。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

对于请求中所传递的行政区划内不存在的街道地址，最常发生部分匹配的情况。当请求与同一行政区划中的两个或更多位置相匹配时，也可能会返回部分匹配。例如，“21 Henr St, Bristol, UK”将返回 Henry Street 和 Henrietta Street 这两项部分匹配结果。请注意，如果请求中包含拼写错误的地址组成部分，地理编码服务可能会建议一个备选地址。以这种方式触发的建议也将标记为部分匹配。

place_id 是唯一一个可以与其他 Google API 结合使用的标识符。例如，您可以在 Google Places API 请求中使用 place_id 获取当地企业的详情，如电话号码、营业时间、用户评论等。请参阅地点 ID 概览。

由于不能保证对 Google Maps Geocoding API 请求的个别响应的格式准确，因此您永远不应该假定元素处于绝对位置。（特别是，Geocoding API 响应中 address_components 的数量会根据请求的地址而有所不同，并且可以随时间而改变。）相反，您应该解析响应，并通过表达式选择合适的值。如需了解详细信息，请参阅解析 Web 服务响应。

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

结果中的 types[] 数组表示地址类型。地址类型的示例包括街道地址、国家/地区或政治实体。在 address_components[] 中也有一个 types[] 数组，用来表示地址各个部分的类型。示例包括门牌号码或国家/地区。（以下是类型的完整列表。）地址可能有多种类型。这些类型可能会被视为“标记”。例如，许多城市都标有 political 和 locality 类型。

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

street_address 表示精确的街道地址。route：表示已命名的路线（例如“US 101”）intersection：表示主要交叉路口，通常是两条主要道路的交叉路口political：表示政治实体。通常，这种类型表示某个民政管理部门的多边形country：表示国家政治实体，通常是由地理编码器返回的最高级别类型administrative_area_level_1：表示国家/地区级别以下的一级行政实体。在美国，这种行政级别就是州。并非所有国家都设有这类行政级别administrative_area_level_2：表示国家/地区级别以下的二级行政实体。在美国，这种行政级别就是县。并非所有国家都设有这类行政级别administrative_area_level_3：表示国家/地区级别以下的三级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别administrative_area_level_4：表示国家/地区级别以下的四级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别administrative_area_level_5：表示国家/地区级别以下的五级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别colloquial_area：表示实体的常用替代名称locality 表示合并的城市或城镇政治实体。ward 表示一种特定的日本行政区划类型，以便于区分某个日本地址中的多个行政区划组成部分。sublocality：表示 locality 以下的一级行政实体。某些位置可能会收到其他类型之一：从 sublocality_level_1 到 sublocality_level_5。每个 sublocality 级别都是一个行政实体。数字越大，表示的地理区域越小neighborhood 表示已命名的街区premise 表示已命名的位置，通常是具有常见名称的一栋或一群建筑物subpremise 表示指定位置以下的一级实体，通常是同名建筑群中的单个建筑物postal_code 表示邮政编码，用于国内的地址邮寄。natural_feature：表示著名的自然景观airport：表示机场park：表示已命名的公园。point_of_interest 表示已命名的景点。通常，这些“景点”是不容易归入其他类别的著名地方实体，如“帝国大厦”或“自由女神像”。

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

除了上述类型之外，地址组成部分还可能包括下列类型。

注：此列表并不全面，并且随时可能更改。

floor：表示某个建筑物地址的楼层establishment 通常表示某个尚未归类的地方。point_of_interest 表示已命名的景点。parking 表示停车场或停车设施。post_box 表示特定的邮政信箱。postal_town 表示地理区域的分组，如 locality 和 sublocality，在某些国家/地区用于邮寄地址。room 表示某个建筑物地址的房间。street_number 表示确切的门牌号码。bus_station、train_station 和 transit_station 表示巴士、火车或公交车站的位置。

视口偏向

在地理编码请求中，您可以指示让地理编码服务倾向于使用某个给定视口（表示为边框）中的结果。您可以通过设置 bounds 参数在请求 URL 中执行此操作。请注意，偏向只是倾向于使用边界以内的结果；如果在这些边界之外存在更相关的结果，也可能会将这些结果包括在内。

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

例如，“温内特卡”的地理编码一般会返回芝加哥的以下郊区：

请求：

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

响应：

{ "results" : [ { "address_components" : [ { "long_name" : "Winnetka", "short_name" : "Winnetka", "types" : [ "locality", "political" ] }, { "long_name" : "New Trier", "short_name" : "New Trier", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Cook County", "short_name" : "Cook County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Illinois", "short_name" : "IL", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Winnetka, IL, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 42.1282269, "lng" : -87.7108162 }, "southwest" : { "lat" : 42.0886089, "lng" : -87.7708629 } }, "location" : { "lat" : 42.10808340000001, "lng" : -87.735895 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 42.1282269, "lng" : -87.7108162 }, "southwest" : { "lat" : 42.0886089, "lng" : -87.7708629 } } }, "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q", "types" : [ "locality", "political" ] } ], "status" : "OK"}

然而，添加一个为洛杉矶圣费尔南多谷定义边框的 bounds 参数会使得此地理编码返回位于该位置的名为“温内特卡”的邻近地区：

请求：

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

响应：

{ "results" : [ { "address_components" : [ { "long_name" : "Winnetka", "short_name" : "Winnetka", "types" : [ "neighborhood", "political" ] }, { "long_name" : "Los Angeles", "short_name" : "LA", "types" : [ "locality", "political" ] }, { "long_name" : "Los Angeles County", "short_name" : "Los Angeles 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" ] } ], "formatted_address" : "Winnetka, Los Angeles, CA, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 34.2355209, "lng" : -118.5534191 }, "southwest" : { "lat" : 34.1854649, "lng" : -118.588536 } }, "location" : { "lat" : 34.2048586, "lng" : -118.5739621 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 34.2355209, "lng" : -118.5534191 }, "southwest" : { "lat" : 34.1854649, "lng" : -118.588536 } } }, "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ", "types" : [ "neighborhood", "political" ] } ], "status" : "OK"}

地区偏向

在地理编码响应中，Google Maps Geocoding API 返回受发送请求地区（通常是国家）影响的地址结果。例如，在美国的某个区域和在西班牙搜索“San Francisco”，可能会返回不同的结果。

您可以使用 region 参数将 Google Maps Geocoding API 设置为返回偏向于特定地区的结果。该参数带有指定地区偏向的 ccTLD（国家代码顶级域）自变量。大多数 ccTLD 代码与 ISO 3166-1 代码相同，但有一些明显的例外。例如，英国的国家代码顶级域名为“uk”(.co.uk)，而其 ISO 3166-1 代码却是“gb”（专指“大不列颠及北爱尔兰联合王国”这一实体）。

地理编码结果可以偏向于正式推出了主要 Google Maps 应用的每个区域。请注意，偏向只是倾向于使用某个特定区域的结果；如果在此区域以外存在更相关的结果，也可能会将这些结果包括在内。

例如，由于 Google Maps 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.4547053 }, "southwest" : { "lat" : 41.580266, "lng" : -83.69423700000002 } }, "location" : { "lat" : 41.6639383, "lng" : -83.55521200000001 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 41.732844, "lng" : -83.4547053 }, "southwest" : { "lat" : 41.580266, "lng" : -83.69423700000002 } } }, "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "types" : [ "locality", "political" ] }, { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Lincoln County", "short_name" : "Lincoln County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Oregon", "short_name" : "OR", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Toledo, OR, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 44.6383219, "lng" : -123.9129439 }, "southwest" : { "lat" : 44.598776, "lng" : -123.954585 } }, "location" : { "lat" : 44.621507, "lng" : -123.9384478 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 44.6383219, "lng" : -123.9129439 }, "southwest" : { "lat" : 44.598776, "lng" : -123.954585 } } }, "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo", "types" : [ "locality", "political" ] }, { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Tama County", "short_name" : "Tama County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Iowa", "short_name" : "IA", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Toledo, IA, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 42.00388600000001, "lng" : -92.56695289999999 }, "southwest" : { "lat" : 41.9784431, "lng" : -92.60007299999999 } }, "location" : { "lat" : 41.9972134, "lng" : -92.5835266 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 42.00388600000001, "lng" : -92.56695289999999 }, "southwest" : { "lat" : 41.9784431, "lng" : -92.60007299999999 } } }, "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU", "types" : [ "locality", "political" ] }, { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Lewis County", "short_name" : "Lewis County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Washington", "short_name" : "WA", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] }, { "long_name" : "98591", "short_name" : "98591", "types" : [ "postal_code" ] } ], "formatted_address" : "Toledo, WA 98591, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 46.44799889999999, "lng" : -122.8419249 }, "southwest" : { "lat" : 46.43233009999999, "lng" : -122.85575 } }, "location" : { "lat" : 46.4398305, "lng" : -122.846783 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 46.44799889999999, "lng" : -122.8419249 }, "southwest" : { "lat" : 46.43233009999999, "lng" : -122.85575 } } }, "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM", "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" : "Toledo", "types" : [ "administrative_area_level_4", "political" ] }, { "long_name" : "Vega de Toledo", "short_name" : "Vega de Toledo", "types" : [ "administrative_area_level_3", "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, Toledo, Spain", "geometry" : { "bounds" : { "northeast" : { "lat" : 39.88605099999999, "lng" : -3.9192423 }, "southwest" : { "lat" : 39.8383676, "lng" : -4.0629256 } }, "location" : { "lat" : 39.8628316, "lng" : -4.027323099999999 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 39.88605099999999, "lng" : -3.9192423 }, "southwest" : { "lat" : 39.8383676, "lng" : -4.0629256 } } }, "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y", "types" : [ "locality", "political" ] } ], "status" : "OK"}

组成部分过滤

在地理编码响应中，Google Maps Geocoding API 可以返回限制在某个特定区域的地址结果。使用 components 过滤器来指定限制。过滤器由一个 component:value 对列表组成，这些键值对用管道符号 (|) 分隔。只有符合所有过滤器的结果才会被返回。过滤器值支持与其他地理编码请求相同的用于拼写校正和部分匹配的方法。如果地理编码结果部分匹配某个组成部分过滤器，它将在响应中包含 partial_match 字段。

可以过滤的 components 包括：

route 用来匹配路由的长名称或短名称。locality 既可以匹配 locality 类型，也可以匹配 sublocality 类型。administrative_area 用来匹配所有 administrative_area 级别。postal_code 用来匹配 postal_code 和 postal_code_prefix。country 用来匹配国家/地区名称或两个字母的 ISO 3166-1 国家/地区代码。

注：要么在地址参数中指定每个地址组成部分，要么将其指定为组成部分过滤器，这两种方式只能选择其一，不可同时使用。这样做可能会导致 ZERO_RESULTS。

设置了 components=country:ES 后，“Santa Cruz”的地理编码将返回西班牙加那利群岛的圣克鲁斯特内里费。请求：

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=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" : "Santa Cruz de Tenerife", "types" : [ "administrative_area_level_4", "political" ] }, { "long_name" : "Anaga", "short_name" : "Anaga", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Santa Cruz de Tenerife", "short_name" : "TF", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Canarias", "short_name" : "CN", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Spain", "short_name" : "ES", "types" : [ "country", "political" ] } ], "formatted_address" : "Santa Cruz de Tenerife, 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"}

包含组成部分过滤器的查询将只返回匹配该过滤器的地理编码结果。如果没有找到匹配项，地理编码器会返回一个与该过滤器本身相匹配的结果。请求：

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

响应：

{ "results" : [ { "address_components" : [ { "long_name" : "Texas", "short_name" : "TX", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Texas, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 36.5007041, "lng" : -93.5080389 }, "southwest" : { "lat" : 25.8371638, "lng" : -106.6456461 } }, "location" : { "lat" : 31.9685988, "lng" : -99.9018131 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 36.5015087, "lng" : -93.5080389 }, "southwest" : { "lat" : 25.8371638, "lng" : -106.6456461 } } }, "partial_match" : true, "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY", "types" : [ "administrative_area_level_1", "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 过滤器时，可以在无地址参数的情况下进行查询，但不能在没有值的情况下指定组成部分。请求：

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

响应：

{ "results" : [ { "address_components" : [ { "long_name" : "Annegatan", "short_name" : "Annegatan", "types" : [ "route" ] }, { "long_name" : "Helsingfors", "short_name" : "Helsingfors", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Finland", "short_name" : "FI", "types" : [ "country", "political" ] } ], "formatted_address" : "Annegatan, Helsingfors, Finland", "geometry" : { "bounds" : { "northeast" : { "lat" : 60.168997, "lng" : 24.9427959 }, "southwest" : { "lat" : 60.1626627, "lng" : 24.934 } }, "location" : { "lat" : 60.1657808, "lng" : 24.938451 }, "location_type" : "GEOMETRIC_CENTER", "viewport" : { "northeast" : { "lat" : 60.168997, "lng" : 24.9427959 }, "southwest" : { "lat" : 60.1626627, "lng" : 24.934 } } }, "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM", "types" : [ "route" ] }, { "address_components" : [ { "long_name" : "Annevägen", "short_name" : "Annevägen", "types" : [ "route" ] }, { "long_name" : "Vanda", "short_name" : "Vanda", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Finland", "short_name" : "FI", "types" : [ "country", "political" ] }, { "long_name" : "01420", "short_name" : "01420", "types" : [ "postal_code" ] } ], "formatted_address" : "Annevägen, 01420 Vanda, Finland", "geometry" : { "bounds" : { "northeast" : { "lat" : 60.3282738, "lng" : 25.1162163 }, "southwest" : { "lat" : 60.32564009999999, "lng" : 25.1076474 } }, "location" : { "lat" : 60.3271069, "lng" : 25.1118046 }, "location_type" : "GEOMETRIC_CENTER", "viewport" : { "northeast" : { "lat" : 60.3283059302915, "lng" : 25.1162163 }, "southwest" : { "lat" : 60.32560796970849, "lng" : 25.1076474 } } }, "partial_match" : true, "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA", "types" : [ "route" ] }, { "address_components" : [ { "long_name" : "Anneplatsen", "short_name" : "Anneplatsen", "types" : [ "route" ] }, { "long_name" : "Helsingfors", "short_name" : "Helsingfors", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Finland", "short_name" : "FI", "types" : [ "country", "political" ] }, { "long_name" : "00100", "short_name" : "00100", "types" : [ "postal_code" ] } ], "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland", "geometry" : { "bounds" : { "northeast" : { "lat" : 60.1695664, "lng" : 24.9357125 }, "southwest" : { "lat" : 60.168997, "lng" : 24.934 } }, "location" : { "lat" : 60.1692741, "lng" : 24.9348016 }, "location_type" : "GEOMETRIC_CENTER", "viewport" : { "northeast" : { "lat" : 60.17063068029151, "lng" : 24.9362052302915 }, "southwest" : { "lat" : 60.1679327197085, "lng" : 24.9335072697085 } } }, "partial_match" : true, "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M", "types" : [ "route" ] } ], "status" : "OK"}

反向地理编码（地址查找）

术语地理编码一般是指将可人工读取的地址转换为地图上的某个位置。与之相反，将地图上的某个位置转换为可人工读取的地址的过程，就称为反向地理编码。

必填参数：您必须在反向地理编码请求中提供下列参数之一，但不可同时提供这两个参数：

要么：latlng – 经纬度值，用于指定希望获得其最接近的、可人工读取的地址的位置。或者：place_id – 您希望获得其可人工读取的地址的地方的地点 ID。地点 ID 是唯一一个可以与其他 Google API 结合使用的标识符。例如，您可以使用由 Google Maps Roads API 返回的 placeID 来获取某个拍摄点的地址。如需了解有关地点 ID 的详细信息，请参阅地点 ID 概览。只有当请求包括 API 密钥或 Google Maps API for Work 客户端 ID 时，才能指定地点 ID。

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

您可以将下列可选参数包括在反向地理编码请求中：

key – 您的应用的 API 密钥，可从 Google API Console 获得。此密钥可以标识您的应用，以便进行配额管理。language – 返回结果时使用的语言。请参阅支持的区域语言列表。请注意，我们会经常更新支持的语言，因此，此列表可能并不全面。如果未提供 language，地理编码器将尽可能尝试使用发送请求区域的当地语言。result_type – 一个或多个地址类型，用管道符号 (|) 分隔。地址类型的示例：country、street_address、postal_code。如需查看允许值的完整列表，请参阅此页面上的地址类型。如果指定了一种类型，会将结果限制于这种类型。如果指定了多种类型，该 API 将返回匹配其中任何类型的所有地址。注：此参数仅适用于包括 API 密钥或客户端 ID 的请求。location_type – 一个或多个位置类型，用管道符号 (|) 分隔。如果指定了一种类型，会将结果限制于这种类型。如果指定了多种类型，该 API 将返回匹配其中任何类型的所有地址。注：此参数仅适用于包括 API 密钥或客户端 ID 的请求。可支持以下值："ROOFTOP" 将结果限制为我们使其位置信息精确到街道地址精度的地址。"RANGE_INTERPOLATED" 将结果限制为反映了两个精确点（例如交叉路口）之间用内插法计算得到的近似值（通常在道路上）的地址。内插的范围通常表示某个街道地址的 rooftop 地理编码不可用。"GEOMETRIC_CENTER" 将结果限制为某个位置（如多段线（例如街道）或多边形（地区））的几何中心。"APPROXIMATE" 将结果限制为是近似值的地址。

如果 result_type 和 location_type 限制同时存在，那么该 API 将只返回同时匹配 result_type和 location_type 限制的结果。

纬度/经度的反向地理编码

以下查询包含了布鲁克林某个位置的纬度/经度值：

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

注：确保在将纬度和经度值传入 latlng 参数时，两者之间没有空格。

上述查询返回以下结果：

{ "results" : [ { "address_components" : [ { "long_name" : "277", "short_name" : "277", "types" : [ "street_number" ] }, { "long_name" : "Bedford Avenue", "short_name" : "Bedford Ave", "types" : [ "route" ] }, { "long_name" : "Williamsburg", "short_name" : "Williamsburg", "types" : [ "neighborhood", "political" ] }, { "long_name" : "Brooklyn", "short_name" : "Brooklyn", "types" : [ "sublocality", "political" ] }, { "long_name" : "Kings", "short_name" : "Kings", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "New York", "short_name" : "NY", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] }, { "long_name" : "11211", "short_name" : "11211", "types" : [ "postal_code" ] } ], "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA", "geometry" : { "location" : { "lat" : 40.714232, "lng" : -73.9612889 }, "location_type" : "ROOFTOP", "viewport" : { "northeast" : { "lat" : 40.7155809802915, "lng" : -73.9599399197085 }, "southwest" : { "lat" : 40.7128830197085, "lng" : -73.96263788029151 } } }, "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA", "types" : [ "street_address" ] }, ... Additional results[] ...

请注意，反向地理编码器返回了多个结果。"formatted_address" 的结果不仅有邮政地址，还包括对某个位置的任何地理命名方式。例如，对芝加哥市的某个点进行地理编码时，地理编码的点可以表示为街道地址、城市（芝加哥）、所在州（伊利诺伊州）或国家/地区（美国）。所有这些都是地理编码器的“地址”。反向地理编码器返回这些类型中的任何一种作为有效结果。

反向地理编码器会匹配政治实体（国家/地区、省、市和街区）、街道地址及邮政编码。

由以前的查询返回的 formatted_address 值的完整列表如下所示。

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA","formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA","formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA","formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA","formatted_address" : "Brooklyn, NY 11211, USA","formatted_address" : "Williamsburg, Brooklyn, NY, USA","formatted_address" : "Brooklyn, NY, USA","formatted_address" : "New York, NY, USA","formatted_address" : "New York, USA","formatted_address" : "United States",

通常，返回的地址按精确度从最具体到最不具体的顺序排列；正如本例中所示，最准确的地址在结果中摆在最突出的位置。请注意，我们会返回不同类型的地址，从最具体的街道地址到不那么具体的政治实体，如街区、市、县、州等。如果您想匹配特定类型的地址，请参阅以下有关按类型限制结果的部分。

注：反向地理编码是一种估计。地理编码器将尝试在某一误差限度范围内查找最接近的可寻址位置。如果没有找到匹配项，地理编码器会返回零个结果。

地点 ID 的反向地理编码

以下查询包含了布鲁克林某个位置的地点 ID：

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

上述查询返回以下结果：

{ "results" : [ { "address_components" : [ { "long_name" : "277", "short_name" : "277", "types" : [ "street_number" ] }, { "long_name" : "Bedford Ave", "short_name" : "Bedford Ave", "types" : [ "route" ] }, { "long_name" : "Williamsburg", "short_name" : "Williamsburg", "types" : [ "neighborhood", "political" ] }, { "long_name" : "Brooklyn", "short_name" : "Brooklyn", "types" : [ "sublocality_level_1", "sublocality", "political" ] }, { "long_name" : "Kings County", "short_name" : "Kings County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "New York", "short_name" : "NY", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] }, { "long_name" : "11211", "short_name" : "11211", "types" : [ "postal_code" ] } ], "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA", "geometry" : { "location" : { "lat" : 40.714232, "lng" : -73.9612889 }, "location_type" : "ROOFTOP", "viewport" : { "northeast" : { "lat" : 40.7155809802915, "lng" : -73.9599399197085 }, "southwest" : { "lat" : 40.7128830197085, "lng" : -73.96263788029151 } } }, "partial_match" : true, "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA", "types" : [ "street_address" ] } ], "status" : "OK"}

受类型限制的反向地理编码

以下示例将返回的地址限制为位置类型是 ROOFTOP 且地址类型是 street_address 的地址。

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

注：这些限制只适用于反向地理编码。

反向地理编码响应

反向地理编码响应的格式与地理编码响应相同。请参阅地理编码响应。下面是反向地理编码响应中可能出现的状态代码。

反向地理编码状态代码

地理编码响应对象中的 "status" 字段包含了请求的状态，还可能包含调试信息，以帮助您查明反向地理编码不工作的原因。"status" 字段可以包含以下值：

"OK" 表示未出现任何错误，并且至少返回了一个地址。"ZERO_RESULTS" 表示反向地理编码成功，但未返回任何结果。如果向地理编码器传递了某个偏远位置的 latlng 参数，就可能会发生这种情况。"OVER_QUERY_LIMIT" 表示您已超出配额。"REQUEST_DENIED" 表示系统已拒绝该请求。这可能是因为该请求包含了 result_type 或 location_type 参数，但未包含 API 密钥或客户端 ID。"INVALID_REQUEST" 通常表示下列情况之一：缺少查询（address、components 或 latlng）。提供的 result_type 或 location_type 无效。"UNKNOWN_ERROR" 表示由于服务器发生错误，因此无法处理该请求。如果您重试一次，请求可能会成功