谷歌舆图 API 开辟之 Geocoding API

2024年4月19日 142次阅读来源: 旅图灬

大部份项目照样都有要猎取当前点击的坐标经纬度或许猎取当前街道的信息的，但是谷歌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 请求花样

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 相应包含零个或更多个 <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 猎取本地企业的概况，如电话号码、营业时间、用户批评等。

地点范例和地点构成部份范例

效果中的 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 的反向地舆编码

以下查询包含了布鲁克林某个位置的地点 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" 示意因为效劳器发作毛病，因而没法处理该请求。假如您重试一次，请求可以会胜利

sensor 参数

Google Maps API 之前请求您将 sensor 参数包含在内，以指导您的运用是不是运用传感器来肯定用户的位置。但该参数如今不再是必填项。

    原文作者：旅图灬
    原文地址: https://segmentfault.com/a/1190000006173834
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。