conv_coord: Generic function to convert geographic coordinates

In madlogos/asesgeo: ASES Analytic Toolkit on Geographics

Description

The general function that converts lat/lon coordintes from one GCS to another GCS including WGS-84, GCJ-02 and BD-09 either locally or by calling Baidu Maps API.

Usage

convCoord(lat, lon, from = c("WGS-84", "GCJ-02", "BD-09"),
  to = c("WGS-84", "GCJ-02", "BD-09"), output = c("all", "raw"),
  api = NULL, force = FALSE, accurate_cn_bou = TRUE, key = NULL,
  time = 0, idf = TRUE, messaging = FALSE, ...)

Arguments

lat	numeric vector, the latitudes
lon	numeric vector, the longitudes
from	character, the inputting GCS, "WGS-84", "GCJ-02", or "BD-09"
to	character, the outputting GCS, "WGS-84", "GCJ-02", or "BD-09"
output	character, the output format, "all" or "raw". Default "all". 'all": the structured data.frame of results comprising of 'lat' and 'lng'. 'raw': the raw JSON data. You can then parse the results using parse_convcoords(). It is only effective when setting a specific api (api mode conversion).
api	character, call 'baidu' or 'gaode' maps api. Note that baidu API only supports the transformations from WGS-84 or GCJ-02 to BD-09, and gaode API only supports the tranformations from WGS-84 or BD-09 to GCJ-02. Other coodinate conversions must be done locally. As the conversion result is the same, it's recommended to perform conversions locally. Default NULL, indicating that local algorithm is applied.
force	logical, whether convert the coordinates regardless if they locate inside China. Default FALSE, indicating that only coordinates inside China will be converted. It is only effective when api is NULL (local mode).
accurate_cn_bou	logical, whether use accurate China boundary to convert the coordinates. It is only effective when api is NULL (local mode). Default TRUE. The WGS-84 ==> GCJ-02 conversion will only be conducted in coordinates inside China. When using the accurate China boundary, the function will check if the coordinates are actually inside China's territory. When set FALSE, the function will use a very vague rectangle to reprensent China boundary.
key	character. When api is TRUE, a web api will be called. The key is thus mandatory. If key is not properly provided, the api will report errors. Default NULL, which indicates that get_api_key() will be called to set the api key.
time	numeric, time interval when calling the APIs. This is used to avoid the overuse. Default 0.
idf	logical, whether add an identifier column to the result. Default TRUE.
messaging	logical, whether print message during processing. Default FALSE.
...	other arguments to pass to the function.

Details

The original function turns on api, which calls Google or Baidu APIs and may thus be slow. This version by default turns off api and applies built-in conversion functions to do the trick and thus performs faster.
Note that the APIs have usage limits (baidu: 100 lat/lon coordinates per query, gaode: 40 lon/lat coordinates per query).
Since the results of coordinate conversion using API method and local algorithms are basically the same, it is recommended to use local algorithms.

Value

a 2-col data.frame ([lng, lat]) of transformed coordinates.

Author(s)

Jun Cai ([e-mail]), PhD student from Center for Earth System Science, Tsinghua University
Yiying Wang ([e-mail])

References

Baidu web API for coordinate conversion at http://lbsyun.baidu.com/index.php?title=webapi/guide/changeposition
Gaode web API for coordinate conversion at https://lbs.amap.com/api/webservice/guide/api/convert

See Also

• local transforming functions: wgs_to_gcj(), gcj_to_bd(), gcj_to_wgs(), wgs_to_bd(), bd_to_wgs(), bd_to_gcj() and get_api_key().
  

• asesgeo:::get_cn_bou(): a list of the 'accurate China boundary' in 'WGS-84', 'GCJ-02' and 'BD-09', which are all sp::SpatialPolygons objects.
  

• is_out_of_china(): see how points aer distinguished as in or out of China.

Examples

## Not run: 
# latitude/longitude coordinates of Beijing railway station
## WGS-84: (39.90105, 116.42079)
## GCJ-02: (39.90245, 116.42703)
## BD-09:  (39.90851, 116.43351)
ak <- <Your baidu map api key>
conv_coord(39.90105, 116.42079, from='WGS-84', to='GCJ-02')
conv_coord(39.90105, 116.42079, from='WGS-84', to='GCJ-02', api='baidu', 
           key=ak)
conv_coord(39.90105, 116.42079, from='WGS-84', to='BD-09')
conv_coord(39.90105, 116.42079, from='WGS-84', to='BD-09', api='baidu', 
           key=ak)
conv_coord(39.90245, 116.42703, from='GCJ-02', to='WGS-84')

# not supported by baidu or gaode map api, return NAs
conv_coord(39.90245, 116.42703, from='GCJ-02', to='WGS-84', api='baidu', 
           key=ak)
conv_coord(39.90245, 116.42703, from='GCJ-02', to='BD-09')
conv_coord(39.90245, 116.42703, from='GCJ-02', to='BD-09', api='baidu', 
           key=ak)
conv_coord(39.90851, 116.43351, from='BD-09', to='GCJ-02')

# not supported by baidu or gaode map api, return NAs
conv_coord(39.90851, 116.43351, from='BD-09', to='GCJ-02', api='baidu', 
           key=ak)
conv_coord(39.90851, 116.43351, from='BD-09', to='WGS-84')

# not supported by baidu or gaode map api, return NAs
conv_coord(39.90851, 116.43351, from='BD-09', to='WGS-84', api='baidu', 
           key=ak)

# convert multiple coordinates
lat <- c(39.99837, 39.98565)
lng <- c(116.3203, 116.2998)
conv_coord(lat, lng, from='WGS-84', to='GCJ-02')

## End(Not run)

madlogos/asesgeo documentation built on Aug. 9, 2019, 9:53 a.m.