Travis-CI Build Status Coverage Status

Introduction

rmapzen is a client for the Mapzen API. For more information, see https://mapzen.com/documentation/. The project is available on github as well as CRAN.

Isochrones

The isochrone service allows you to “[compute] areas that are reachable within specified time intervals from a location, and returns the reachable regions as contours of polygons or lines that you can display on a map”. Below is an example of finding places within driving distance of UC Berkeley, and plotting them using the leaflet package.

ucb <- mz_geocode("UC Berkeley")
isos <- mz_isochrone(
    ucb,
    costing_model = mz_costing$auto(),
    contours = mz_contours(c(10, 20, 30)),
    polygons = TRUE
)

library(leaflet)
leaflet(as_sp(isos)) %>%
    addProviderTiles("CartoDB.DarkMatter") %>%
    addPolygons(color = ~color, weight = 1) %>%
    addLegend(colors = ~color, 
              labels = ~paste(contour, "minutes"),
              title = "Drive times from <br/> UC Berkeley Campus")

Vector tile service

rmapzen provides an interface to Mapzen’s vector tiles service. Tile requests can be specified using the x, y, zoom coordinates of the tile service, as well as with a lat/long bounding box. For instance, continuing the previous example:

library(dplyr)
library(sf)
library(ggplot2)

# mz_bbox is a generic that returns the bounding box of an object
ucb_tiles <- mz_vector_tiles(mz_bbox(isos))

# vector tiles return all layers (roads, water, buildings, etc) in a list
roads <- as_sf(ucb_tiles$roads) %>% filter(kind != "ferry")
water <- as_sf(ucb_tiles$water)

# make a quick static map that includes roads and oceans as reference
ggplot() +
    geom_sf(data = water, 
            fill = "lightblue", colour = NA) + 
    geom_sf(data = roads, 
            size = .2, colour = "gray30") + 
    geom_sf(data = as_sf(isos), 
            colour = "black", size = .1,
            fill = "gray20", alpha = .3) + 
    theme_void()

sf and Spatial*DataFrame conversion

As some of the above examples illustrate, any object returned by a Mapzen service can be converted to the appropriate Spatial*DataFrame or sf object using the generics as_sp and as_sf, for easy interoperability with other packages. You can also convert most objects directly to data frames, allowing for use within tidy pipelines:

library(dplyr)
as.data.frame(hard_rock) %>%
    select(name, confidence, region, locality, neighbourhood)
## # A tibble: 10 x 5
##                  name confidence          region       locality
##                 <chr>      <dbl>           <chr>          <chr>
##  1     Hard Rock Café      0.902       Stockholm      Stockholm
##  2     Hard Rock Cafe      0.962 Västra Götaland       Göteborg
##  3   Rock'n Roll Café      0.662           Skåne           <NA>
##  4       Carolas Cafe      0.661           Skåne       Furulund
##  5         Cafe Charm      0.661  Västernorrland      Sundsvall
##  6         Cafe capri      0.661       Stockholm Upplands Väsby
##  7          Cafeteria      0.661       Jönköping           <NA>
##  8 CaféHarpaviljongen      0.661       Stockholm      Stockholm
##  9      Cafe Columbia      0.661    Östergötland           Kisa
## 10         Cafékoppen      0.661       Stockholm      Stockholm
## # ... with 1 more variables: neighbourhood <chr>

Mapzen list methods

Currently, the following methods are available to pull out commonly used pieces of a response:

  • mz_coordinates (only available for search results)
  • mz_bbox
mz_coordinates(hard_rock)
## # A tibble: 10 × 2
##         lon      lat
##       <dbl>    <dbl>
## 1  18.05484 59.34408
## 2  11.97425 57.70123
## 3  13.83493 55.93419
## 4  13.09754 55.77635
## 5  17.30462 62.38921
## 6  17.94834 59.39728
## 7  14.13232 57.58279
## 8  18.08074 59.34991
## 9  15.63464 57.98744
## 10 17.96348 59.28589
mz_bbox(ucb_tiles)
## # A tibble: 1 × 4
##     min_lon min_lat   max_lon max_lat
## *     <dbl>   <dbl>     <dbl>   <dbl>
## 1 -123.0469 37.1603 -121.6406 38.2727

A more detailed example

Say you have an afternoon meeting at the TransAmerica center in San Francisco, and would like to visit a local museum afterwards. Here’s how to make a map of museums within walking distance:

# first geocode the TransAmerica Center
trans_america <- mz_geocode("TransAmerica Center, San Francisco CA")

# then identify the area that is within 15 minutes walking distance
walkable <- mz_isochrone(
    trans_america,
    costing_model = mz_costing$pedestrian(),
    contours = mz_contours(15))

# now search for museums, but limit the search to areas within "walkable"
museums <- mz_search(
    "Museum", 
    boundary.rect = mz_bbox(walkable), 
    layers = mz_layers$venue, 
    size = 15
)

# use the leaflet package to draw the map
leaflet(as_sp(walkable)) %>%
    addProviderTiles("CartoDB.DarkMatter") %>%
    addPolygons(color = "#ffffff", weight = 1) %>%
    addMarkers(
        data = trans_america, 
        lat = ~geocode_latitude, 
        lng = ~geocode_longitude,
        popup = "TransAmerica Center") %>%
    addCircleMarkers(
        data = as_sp(museums), 
        weight = 1,
        radius = 7,
        opacity = 1,
        popup = ~name,
        color = "#ff0000")

Convenience features

Several of the search functions take, optionally, the arguments layers, sources, and boundary.country (the latter requires ISO-3166 codes). If you’re using an IDE with auto-complete, the objects mz_layers, mz_sources, and mz_countries should make it easier to get the correct codes.

Easy lookup for ISO-3166 codes

Easy lookup for ISO-3166 codes

Similarly, argument constructors are available for easier specifications of isochrone and search requests.

  • mz_costing
  • mz_costing_options
  • mz_location
  • mz_contours
  • mz_date_time

Installation

rmapzen is available on CRAN. To install:

install.packages("rmapzen")

You’ll also need to acquire an API key, and then set the MAPZEN_KEY environment variable:

Sys.setenv(MAPZEN_KEY = "mapzen-xxxxxx")