谷歌地图 API 开发之 Geocoding API

摘要：地理编码响应地理编码响应以请求路径中标志指示的格式返回。表示地理编码成功，但未返回任何结果。通常，这种类型表示某个民政管理部门的多边形表示国家政治实体，通常是由地理编码器返回的最高级别类型表示国家地区级别以下的一级行政实体。

大部分项目还是都有要获取当前点击的坐标经纬度或者获取当前街道的信息的，然而谷歌API 的文档也并不是很直观。
官网地理编码服务地址：https://developers.google.com...
在服务栏里的地理编码里，为什么说是服务呢，用谷歌翻译了下，发现想获取坐标以及街道详情，需要调用谷歌的地理编码接口(不是完全免费的哦)，所以，算是谷歌的接口服务吧。然后人家就来了个限制政策，如下：

使用地理编码服务的标准

每天2500免费请求，客户端和的总和来计算服务器端的 查询; 启用结算进入更高的每日配额，以$ 0.50计费美元/ 1000其他要求，达10万每天的请求。

每秒50个请求，作为客户端和的总和来计算服务器端 的查询。

然而这个服务看了好久，也没看出怎么请求，于是乎，又不停的找谷歌api，找了好久，终于不负有心人，让劳资给找到了这个Google Maps Geocoding API 地址：https://developers.google.com...

下面进入正文。其实下面的都是从谷歌API copy 过来的,不要吐槽我，一点一点的粘贴复制整理也好累的 >_<

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

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

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 的标准，参数都使用“与”字符 (&) 分隔。
因为每种请求类型使用的参数不同，所以本页面的其余部分分别介绍了地理编码和反向地理编码。

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

address- 要进行地理编码的街道地址，采用相关国家/地区的全国邮政服务所使用的格式。应避免其他地址元素，例如企业名称以及单元号、套房号或楼层。
或
components - 您希望获得其地理编码的组成部分过滤器。如果提供了 address，还将接受组成部分过滤器作为可选参数。

key – 您的应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。

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

bounds – 视口的边框，在其中可以使地理编码结果更显著地发生偏向。此参数只会影响，而不会完全限制地理编码器中的结果。

language – 返回结果时使用的语言。请注意，我们会经常更新支持的语言，因此，此列表可能并不全面。如果未提供 language，地理编码器将尽可能尝试使用发送请求区域的当地语言。

region – 地区代码，指定为一个 ccTLD（“顶级域名”）双字符值。此参数只会影响，而不会完全限制地理编码器中的结果。

components – 组成部分过滤器，用管道符号 (|) 分隔。每个组成部分过滤器由一个 component:value 对组成，将完全限制地理编码器中的结果。

地理编码响应以 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响应结果实例：

{
   "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" 包含一个有关地理编码地址信息和几何信息的数组。

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

"OK" 表示未出现任何错误；已成功解析地址，并且至少返回了一个地理编码。

"ZERO_RESULTS" 表示地理编码成功，但未返回任何结果。如果向地理编码器传递了一个不存在 address，就可能会发生这种情况。

"OVER_QUERY_LIMIT" 表示您已超出配额。

"REQUEST_DENIED" 表示系统已拒绝您的请求。

"INVALID_REQUEST" 一般表示缺少查询（address、components 或 latlng）。

"UNKNOWN_ERROR" 表示由于服务器发生错误，因此无法处理该请求。如果您重试一次，请求可能会成功

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

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

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 获取当地企业的详情，如电话号码、营业时间、用户评论等。

结果中的 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 表示已命名的景点。通常，这些“景点”是不容易归入其他类别的著名地方实体，如“帝国大厦”或“自由女神像”。

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

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

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

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

要么：latlng – 经纬度值，用于指定希望获得其最接近的、可人工读取的地址的位置。

或者：place_id – 您希望获得其可人工读取的地址的地方的地点 ID。地点 ID 是唯一一个可以与其他 Google API 结合使用的标识符。例如，您可以使用由 Google Maps Roads API 返回的 placeID 来获取某个拍摄点的地址。

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

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：

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

接口返回值就不多罗列了，都差不多。

以下示例将返回的地址限制为位置类型是 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" 表示由于服务器发生错误，因此无法处理该请求。如果您重试一次，请求可能会成功

Google Maps API 之前要求您将 sensor 参数包括在内，以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。