Introduction to packagemapsapi
Michael Dorman
2023-07-21
Introduction
Themapsapi package provides an interface to the GoogleMaps APIs, currently four of them:
Functionsmp_directions,mp_matrix andmp_geocode are used to access the Directions, Matrix andGeocode APIs, respectively. They return anxml_documentobject (packagexml2) with the response contents.
Given adirections response, functions
mp_get_routesandmp_get_segmentscan be usedto process the response document into a spatial layer. Functionmp_get_routesgives each alternative as a separate line,while functionmp_get_segmentsgives each segment (that is,a portion of the route associated with specific driving instructions) asa separate line.Given adistance matrix response, function
mp_get_matrixcan be used to obtain distance/durationmatrices.Given ageocode response, functions
mp_get_pointsandmp_get_boundscan be used toobtain geocoded locations as a point or polygon (bounds) layer.
The fourth functionmp_map is used to access the MapsStatic API. It returns astars raster RGB image, which canbe used as background in maps.
Installation
The CRAN version can be installed with:
install.packages("mapsapi")The development version can be installed usingremotes:
install.packages("remotes")remotes::install_github("michaeldorman/mapsapi")Once installed, the package can be loaded withlibrary:
library(mapsapi)A Google Maps APIs key is required to use the package:
key = "AIz....."Directions
The following expression queries the Directions API for drivingdirections from Tel-Aviv and Haifa. Note that locations can be specifiedas a coordinate pair, a textual address or ansf spatialobject. For example:
doc = mp_directions( origin = c(34.81127, 31.89277), destination = "Haifa", alternatives = TRUE, key = key, quiet = TRUE)Alternatively, we can use the sample response data included in thepackages:
library(xml2)doc = as_xml_document(response_directions_driving)Given the response object, we can usemp_get_routes tocreate a spatial layer of route lines:
r = mp_get_routes(doc)Here is the resulting object:
r## Simple feature collection with 2 features and 11 fields## Geometry type: LINESTRING## Dimension: XY## Bounding box: xmin: 34.76391 ymin: 31.87341 xmax: 35.10642 ymax: 32.79439## Geodetic CRS: WGS 84## alternative_id leg_id summary distance_m distance_text## 1-1 1 1 Yitzhak Rabin Hwy/Route 6 126121 126 km## 2-1 2 1 Hwy 2/Kvish HaHof 122251 122 km## duration_s duration_text duration_in_traffic_s duration_in_traffic_text## 1-1 5265 1 hour 28 mins NA NA## 2-1 5402 1 hour 30 mins NA NA## departure_time arrival_time geometry## 1-1 <NA> <NA> LINESTRING (34.81144 31.892...## 2-1 <NA> <NA> LINESTRING (34.81144 31.892...and a visualization usingleaflet:
library(leaflet)pal = colorFactor(palette = "Dark2", domain = r$alternative_id)leaflet() %>% addProviderTiles("CartoDB.DarkMatter") %>% addPolylines(data = r, opacity = 1, weight = 7, color = ~pal(alternative_id))Separate segments can be extracted from the same response usingmp_get_segments:
seg = mp_get_segments(doc)Here are the first six features of the resulting object:
head(seg)## Simple feature collection with 6 features and 12 fields## Geometry type: LINESTRING## Dimension: XY## Bounding box: xmin: 34.80859 ymin: 31.88656 xmax: 34.82317 ymax: 31.89256## Geodetic CRS: WGS 84## alternative_id leg_id segment_id summary travel_mode## 1-1-1 1 1 1 Yitzhak Rabin Hwy/Route 6 driving## 1-1-2 1 1 2 Yitzhak Rabin Hwy/Route 6 driving## 1-1-3 1 1 3 Yitzhak Rabin Hwy/Route 6 driving## 1-1-4 1 1 4 Yitzhak Rabin Hwy/Route 6 driving## 1-1-5 1 1 5 Yitzhak Rabin Hwy/Route 6 driving## 1-1-6 1 1 6 Yitzhak Rabin Hwy/Route 6 driving## instructions## 1-1-1 Head <b>southwest</b> on <b>Bnei Moshe St</b> toward <b>Negba St</b>## 1-1-2 Turn <b>left</b> onto <b>Negba St</b>## 1-1-3 Turn <b>left</b> onto <b>Rachel Hirshenzon St</b>## 1-1-4 Turn <b>right</b> onto <b>Herzl St</b>/<wbr/><b>Route 412</b>## 1-1-5 Turn <b>left</b> onto <b>Abarbanel St</b>## 1-1-6 At the roundabout, continue straight onto <b>Derech Jerusalem</b>## distance_m distance_text duration_s duration_text departure_time## 1-1-1 322 0.3 km 65 1 min <NA>## 1-1-2 180 0.2 km 36 1 min <NA>## 1-1-3 327 0.3 km 75 1 min <NA>## 1-1-4 548 0.5 km 108 2 mins <NA>## 1-1-5 503 0.5 km 83 1 min <NA>## 1-1-6 364 0.4 km 52 1 min <NA>## arrival_time geometry## 1-1-1 <NA> LINESTRING (34.81144 31.892...## 1-1-2 <NA> LINESTRING (34.80859 31.890...## 1-1-3 <NA> LINESTRING (34.80968 31.889...## 1-1-4 <NA> LINESTRING (34.81257 31.891...## 1-1-5 <NA> LINESTRING (34.81437 31.886...## 1-1-6 <NA> LINESTRING (34.81956 31.887...and a visualization:
pal = colorFactor( palette = sample(colors(), length(unique(seg$segment_id))), domain = seg$segment_id )leaflet(seg) %>% addProviderTiles("CartoDB.DarkMatter") %>% addPolylines(opacity = 1, weight = 7, color = ~pal(segment_id), popup = ~instructions)Distance Matrix
The following expression queries the Distance Matrix API to obtain amatrix of driving distance and duration between all combinations ofthree locations: Tel-Aviv, Jerusalem and Beer-Sheva.
locations = c("Tel-Aviv", "Jerusalem", "Beer-Sheva")doc = mp_matrix( origins = locations, destinations = locations, key = key, quiet = TRUE)Alternatively, we can use the sample response data included in thepackages:
doc = as_xml_document(response_matrix)Themp_get_matrix function can then be used to processthe XML response into amatrix. Possible values of thematrix include:
distance_m—Distance, in metersdistance_text—Distance, textual descriptionduration_s—Duration, in secondsduration_text—Duration, textual description
m = mp_get_matrix(doc, value = "distance_m")colnames(m) = locationsrownames(m) = locationsm## Tel-Aviv Jerusalem Beer-Sheva## Tel-Aviv 0 66866 108728## Jerusalem 68524 0 118083## Beer-Sheva 110858 106562 0Geocode
The following expression queries the Directions API for geocoding asingle address:
doc = mp_geocode( addresses = "Tel-Aviv", key = key, quiet = TRUE)Alternatively, we can use the sample response data included with thepackage:
doc = list("Tel-Aviv" = as_xml_document(response_geocode))Given the response object, we can usemp_get_points tocreate a spatial layer of geocoded point locations:
pnt = mp_get_points(doc)pnt## Simple feature collection with 1 feature and 5 fields## Geometry type: POINT## Dimension: XY## Bounding box: xmin: 34.78177 ymin: 32.0853 xmax: 34.78177 ymax: 32.0853## Geodetic CRS: WGS 84## id status address address_google location_type## 1 1 OK Tel-Aviv Tel Aviv-Yafo, Israel APPROXIMATE## pnt## 1 POINT (34.78177 32.0853)Here is a visualization usingleaflet:
leaflet() %>% addProviderTiles("CartoDB.DarkMatter") %>% addCircleMarkers(data = pnt)Or the bounds:
bounds = mp_get_bounds(doc)bounds## Simple feature collection with 1 feature and 4 fields## Geometry type: POLYGON## Dimension: XY## Bounding box: xmin: 34.74252 ymin: 32.02925 xmax: 34.85198 ymax: 32.14661## Geodetic CRS: WGS 84## id status address address_google geometry## 1 1 OK Tel-Aviv Tel Aviv-Yafo, Israel POLYGON ((34.74252 32.02925...And a visualization usingleaflet:
leaflet() %>% addProviderTiles("CartoDB.DarkMatter") %>% addPolygons(data = bounds)Static maps
Themp_map function can be used to access the MapsStatic API to download an RGB image with a map.
Here is an example:
r = mp_map(center = "31.253205,34.791914", zoom = 14, key = key, quiet = TRUE)Alternatively, we can use the sample response data included with thepackage:
r = response_mapThe result is astars raster, which can be plotted withplot:
library(stars)plot(r)## Loading required package: abind## Loading required package: sf## Linking to GEOS 3.10.2, GDAL 3.4.1, PROJ 8.2.1; sf_use_s2() is TRUEor withggplot2:
library(ggplot2)cols = attr(r[[1]], "colors")ggplot() + geom_stars(data = r, aes(x = x, y = y, fill = color)) + scale_fill_manual(values = cols, guide = FALSE) + coord_sf()## Warning: The `guide` argument in `scale_*()` cannot be `FALSE`. This was deprecated in## ggplot2 3.3.4.## ℹ Please use "none" instead.## This warning is displayed once every 8 hours.## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was## generated.