forked from dkahle/ggmap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
173 lines (119 loc) · 7.78 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
output:
md_document:
variant: markdown_github
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE, cache = FALSE,
comment = "# ",
fig.path = "tools/README-",
dpi = 67
)
```
<!-- badges: start -->
[](https://cran.r-project.org/package=ggmap)
[](https://travis-ci.org/dkahle/ggmap)
[](https://ci.appveyor.com/project/dkahle/ggmap)
<!-- badges: end -->
### _Attention!_
Google has [recently changed its API requirements](https://developers.google.com/maps/documentation/geocoding/usage-and-billing), and __ggmap__ users are now required to register with Google. From a user's perspective, there are essentially three ramifications of this:
1. Users must register with Google. You can do this at https://cloud.google.com/maps-platform/. While it will require a valid credit card (sorry!), there seems to be a fair bit of free use before you incur charges, and even then the charges are modest for light use.
2. Users must enable the APIs they intend to use. What may appear to __ggmap__ users as one overarching "Google Maps" product, Google in fact has several services that it provides as geo-related solutions. For example, the [Maps Static API](https://developers.google.com/maps/documentation/maps-static/intro) provides map images, while the [Geocoding API](https://developers.google.com/maps/documentation/geocoding/intro) provides geocoding and reverse geocoding services. Apart from the relevant Terms of Service, generally __ggmap__ users don't need to think about the different services. For example, you just need to remember that `get_googlemap()` gets maps, `geocode()` geocodes (with Google, DSK is done), etc., and __ggmap__ handles the queries for you. _However_, you do need to enable the APIs before you use them. You'll only need to do that once, and then they'll be ready for you to use. Enabling the APIs just means clicking a few radio buttons on the Google Maps Platform web interface listed above, so it's easy.
3. Inside R, after loading the new version of __ggmap__, you'll need provide __ggmap__ with your API key, a [hash value](https://en.wikipedia.org/wiki/Hash_function) (think string of jibberish) that authenticates you to Google's servers. This can be done on a temporary basis with `register_google(key = "[your key]")` or permanently using `register_google(key = "[your key]", write = TRUE)` (note: this will overwrite your `~/.Renviron` file by replacing/adding the relevant line). If you use the former, know that you'll need to re-do it every time you reset R.
Your API key is _private_ and unique to you, so be careful not to share it online, for example in a GitHub issue or saving it in a shared R script file. If you share it inadvertantly, just get on Google's website and regenerate your key - this will retire the old one. Keeping your key private is made a bit easier by __ggmap__ scrubbing the key out of queries by default, so when URLs are shown in your console, they'll look something like `key=xxx`. (Read the details section of the `register_google()` documentation for a bit more info on this point.)
The new version of __ggmap__ is now on CRAN soon, but you can install the latest version, including an important bug fix in `mapdist()`, here with:
```{r attn, eval=FALSE}
if(!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("dkahle/ggmap")
```
<hr>
# ggmap
__ggmap__ is an R package that makes it easy to retrieve raster map tiles from popular online mapping services like [Google Maps](https://developers.google.com/maps/documentation/static-maps/?hl=en) and [Stamen Maps](http://maps.stamen.com) and plot them using the [__ggplot2__](https://github.com/tidyverse/ggplot2) framework:
```{r maptypes}
library("ggmap")
us <- c(left = -125, bottom = 25.75, right = -67, top = 49)
get_stamenmap(us, zoom = 5, maptype = "toner-lite") %>% ggmap()
```
Use `qmplot()` in the same way you'd use `qplot()`, but with a map automatically added in the background:
```{r qmplot}
library("dplyr")
library("forcats")
# define helper
`%notin%` <- function(lhs, rhs) !(lhs %in% rhs)
# reduce crime to violent crimes in downtown houston
violent_crimes <- crime %>%
filter(
offense %notin% c("auto theft", "theft", "burglary"),
-95.39681 <= lon & lon <= -95.34188,
29.73631 <= lat & lat <= 29.78400
) %>%
mutate(
offense = fct_drop(offense),
offense = fct_relevel(offense, c("robbery", "aggravated assault", "rape", "murder"))
)
# use qmplot to make a scatterplot on a map
qmplot(lon, lat, data = violent_crimes, maptype = "toner-lite", color = I("red"))
```
All the __ggplot2__ geom's are available. For example, you can make a contour plot with `geom = "density2d"`:
```{r qmplot2, eval=FALSE}
qmplot(lon, lat, data = violent_crimes, maptype = "toner-lite", geom = "density2d", color = I("red"))
```
In fact, since __ggmap__'s built on top of __ggplot2__, all your usual __ggplot2__ stuff (geoms, polishing, etc.) will work, and there are some unique graphing perks __ggmap__ brings to the table, too.
```{r styling}
robberies <- violent_crimes %>% filter(offense == "robbery")
qmplot(lon, lat, data = violent_crimes, geom = "blank",
zoom = 14, maptype = "toner-background", darken = .7, legend = "topleft"
) +
stat_density_2d(aes(fill = ..level..), geom = "polygon", alpha = .3, color = NA) +
scale_fill_gradient2("Robbery\nPropensity", low = "white", mid = "yellow", high = "red", midpoint = 650)
```
Faceting works, too:
```{r faceting}
qmplot(lon, lat, data = violent_crimes, maptype = "toner-background", color = offense) +
facet_wrap(~ offense)
```
## Google Maps and Credentials
[Google Maps](http://developers.google.com/maps/terms) can be used just as easily. However, since Google Maps use a center/zoom specification, their input is a bit different:
```{r google_maps}
get_googlemap("waco texas", zoom = 12) %>% ggmap()
```
Moreover, you can get various different styles of Google Maps with __ggmap__ (just like Stamen Maps):
```{r google_styles, eval=FALSE}
get_googlemap("waco texas", zoom = 12, maptype = "satellite") %>% ggmap()
get_googlemap("waco texas", zoom = 12, maptype = "hybrid") %>% ggmap()
get_googlemap("waco texas", zoom = 12, maptype = "roadmap") %>% ggmap()
```
Google's geocoding and reverse geocoding API's are available through `geocode()` and `revgeocode()`, respectively:
```{r geocode}
geocode("1301 S University Parks Dr, Waco, TX 76798")
revgeocode(c(lon = -97.1161, lat = 31.55098))
```
There is also a `mutate_geocode()` that works similarly to [__dplyr__](https://github.com/hadley/dplyr)'s `mutate()` function:
```{r mutate_geocode}
tibble(address = c("white house", "", "waco texas")) %>%
mutate_geocode(address)
```
Treks use Google's routing API to give you routes (`route()` and `trek()` give slightly different results; the latter hugs roads):
```{r route_trek}
trek_df <- trek("houson, texas", "waco, texas", structure = "route")
qmap("college station, texas", zoom = 8) +
geom_path(
aes(x = lon, y = lat), colour = "blue",
size = 1.5, alpha = .5,
data = trek_df, lineend = "round"
)
```
(They also provide information on how long it takes to get from point A to point B.)
Map distances, in both length and anticipated time, can be computed with `mapdist()`). Moreover the function is vectorized:
```{r mapdist}
mapdist(c("houston, texas", "dallas"), "waco, texas")
```
## Installation
* From CRAN: `install.packages("ggmap")`
* From Github:
```{r, eval=FALSE}
if (!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("dkahle/ggmap")
```