README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  tidy = TRUE
)
```

<!-- Place this tag in your head or just before your close body tag. -->
<!--<script async defer src="https://buttons.github.io/buttons.js"></script>-->

# [amapGeocode](https://github.com/womeimingzi11/amapGeocode)

<!-- badges: start -->
[![Total downloads badge](https://cranlogs.r-pkg.org/badges/grand-total/amapGeocode?color=blue)](https://CRAN.R-project.org/package=amapGeocode)
[![CRAN status](https://www.r-pkg.org/badges/version/amapGeocode)](https://CRAN.R-project.org/package=amapGeocode)
[![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/297431889.svg)](https://zenodo.org/badge/latestdoi/297431889)
[![Codecov test coverage](https://codecov.io/gh/womeimingzi11/amapGeocode/branch/master/graph/badge.svg)](https://codecov.io/gh/womeimingzi11/amapGeocode?branch=master)
[![R-CMD-check](https://github.com/womeimingzi11/amapGeocode/workflows/R-CMD-check/badge.svg)](https://github.com/womeimingzi11/amapGeocode/actions)
<!-- badges: end -->

中文版介绍: [博客](https://blog.washman.top/post/amapgeocode-%E4%BD%BF%E7%94%A8r%E8%BF%9B%E8%A1%8C%E9%AB%98%E5%BE%B7%E5%9C%B0%E5%9B%BE%E5%9C%B0%E7%90%86%E7%BC%96%E7%A0%81-%E9%80%86%E7%BC%96%E7%A0%81.zh-hans/) or [知乎](https://zhuanlan.zhihu.com/p/264281505)

## Introduction  <img src="man/figures/hexSticker-logo.png" align="right" width="100"/>

Geocoding and Reverse Geocoding Services are widely used to provide data about coordinate and location information, including longitude, latitude, formatted location name, administrative region with different levels. There are some packages can provide geocode service such as [tidygeocoder](https://CRAN.R-project.org/package=tidygeocoder), [baidumap](https://github.com/badbye/baidumap) and [baidugeo](https://github.com/ChrisMuir/baidugeo). However, some of them do not always provide precise information in China, and some of them are unavailable with the upgrade backend API.

amapGeocode is built to provide high precise geocoding and reverse geocoding service, and it provides an interface for the AutoNavi(高德) Maps API geocoding services. API docs can be found [here](https://lbs.amap.com/) and [here](https://lbs.amap.com/api/webservice/summary/). Here are two main functions to use, one is `getCoord()` which needs a character location name as an input, while the other one is `getLocation()` which needs two numeric longitude and latitude values as inputs.

The `getCoord()` function extracts coordinate information from input character location name and outputs the results as `data.table`, `XML` or `JSON (as list)`. And the `getLocation()` function extracts location information from input numeric longitude and latitude values and outputs the results as `data.table`, `XML` or `JSON (as list)`. With the `data.table` format as output, it's highly readable and can be used as an alternative of `data.frame`

amapGeocode is inspired by [baidumap](https://github.com/badbye/baidumap) and [baidugeo](https://github.com/ChrisMuir/baidugeo). If you want to choose the Baidu Map API, these packages are good choices.

However, AutoNavi has significant high precise, in my case, the Results from Baidu were unsatisfactory.

## BIG NEWS: Parallel is Here! But you need a `plan`

Since `v0.5.1`, parallel framework is implemented by [`furrr` package](https://CRAN.R-project.org/package=furrr), of which backend is [`future package`](https://arxiv.org/abs/2008.00553). Refering to [*A Future for R: Best Practices for Package Developers*](https://CRAN.R-project.org/package=future/vignettes/future-7-for-package-developers.html) and avoiding potential modification to the future strategy, we have removed the automatically parallel operation from every function in `amapGeocode`.

To turn on parallel operation support, just call `future::plan(multisession) # or any other future strategy`.

Since `v0.5`, parallel operation finally comes to `amapGeocode` with the `parallel` package as the backend. There is a really huge performance improvement for batch queries. And you are welcomed to make a benchmark by following command.

```r
library(amapGeocode)
library(future)
library(readr)
sample_site <-
  read_csv("https://gist.githubusercontent.com/womeimingzi11/0fa3f4744f3ebc0f4484a52649f556e5/raw/47a69157f3e26c4d3bc993f3715b9ba88cda9d93/sample_site.csv")

str(sample_site)

# Here is the old implement
start_time <- proc.time()
old <- lapply(sample_site$address, amapGeocode:::getCoord.individual)
proc.time() - start_time

# Here is the new implement
plan(multisession)
start_time <- proc.time()
new <- getCoord(sample_site$address)
proc.time() - start_time

```

*While parallel support is a totally threads depending operation, so you will get completely different speed on different devices.*

## Installation

You can install the released version of amapGeocode from [CRAN](https://CRAN.R-project.org/package=amapGeocode) with:
``` r
install.packages("amapGeocode")
```
To install the development version, run following command:
``` r
remotes::install_github('womeimingzi11/amapGeocode')
```

## Usage
### Geocoding
Before start geocoding and reverse geocoding, please apply a [AutoNavi Map API Key](https://lbs.amap.com/dev/). Set `amap_key` globally by following command:

```{r set amap_key, eval=FALSE, include=FALSE}
options(amap_key = "REPLACE THIS BY YOUR KEY")
```

Then get results of geocoding, by `getCoord` function. 

```{r getCoord_to_table_as_TRUE}
library(amapGeocode)
# An individual request
res <-
  getCoord("四川省博物馆")
knitr::kable(res)
# Batch requests
res <-
  getCoord(c(
    "四川省博物馆",
    "成都市博物馆",
    "四川省成都市武侯区金楠天街"
  ))
knitr::kable(res)
```

The responses we get from **AutoNavi Map API** is **JSON** or **XML**. For readability, we transform them to [`data.table`](https://CRAN.R-project.org/package=data.table), by setting `output` argument as `data.table` by default.

If you want to extract information from **JSON** or **XML**. The results can further be parsed by `extractCoord`.

```{r getCoord_to_table_as_FALSE}
# An individual request
res <-
  getCoord("四川省博物馆", output = "JSON")
res
```

`extractCoord` is created to get a result as a data.table.

```{r extractCoord}
tb <-
  extractCoord(res)
knitr::kable(tb)
```
### Reverse Geocoding

get results of reverse geocoding, by `getLocation` function. 

```{r getLocation_to_table_as_TRUE}
res <-
  getLocation(103.9960,30.6475)
knitr::kable(res)
```

`extractLocation` is created to get a result as a data.table.

### Get Subordinate Administrative Region

get results of reverse geocoding, by `getAdmin` function.

There is a difference between getAdmin and other function, no matter the `output` argument is `data.table` or not, the result won't be a jointed table by different parent administrative region. For example, with the `output = data.table`, all the lower level administrative region of Province A and Province B will be bound as one data.table, respectively. But the table of province A and table of province B won't be bound further.

Because this function supports different administrative region levels, it is nonsense to bind their results.

```{r getAdmin_to_table_as_TRUE}
res <-
  getAdmin(c("四川省", "成都市", "济宁市"))
knitr::kable(res)
```

`extractAdmin` is created to get results as tibble.

### Convert coordinate point from other coordinate system to AutoNavi

get results of reverse geocoding, by `convertCoord` function, here is how to convert coordinate from gps to AutoNavi.

**Please not, this is still a very experimental function because I have no experience at converting coordinates. The implementation of this input method is not as delicate as I expect. If you have any good idea, please let me know or just fork repo and pull a reques.**

```{r convertCoord_to_table_as_TRUE}
res <-
  convertCoord("103.9960,30.6475", coordsys = "gps")
knitr::kable(res)
```

`extractConvertCoord` is created to get result as data.table.

## Bug report
It's very common for API upgrades to make the downstream application, like amapGeocode,which is unavailable. Feel free to [let me know](mailto://chenhan28@gmail.com) once it's broken or just open an <a class="github-button" href="https://github.com/womeimingzi11/amapGeocode/issues" data-color-scheme="no-preference: light; light: light; dark: dark;" data-size="large" aria-label="Issue womeimingzi11/amapGeocode on GitHub">Issue</a>.

## Acknowledgements
Hex Sticker was created by [hexSticker package](https://github.com/GuangchuangYu/hexSticker) with the world data from  [rnaturalearth](https://CRAN.R-project.org/package=rnaturalearth).

## Code of Conduct
Please note that the amapGeocode project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.