Introduction to rmapzen

Tarak Shah

2023-03-07

Introduction

rmapzen is a client for any implementation of the Mapzen API. Though Mapzen itself has gone out of business, rmapzen can be set up to work with any provider who hosts Mapzen’s open-source software, including geocode.earth, Nextzen, and NYC GeoSearch from NYC Planning Labs. For more information, see https://www.mapzen.com/documentation/. The project is available on github as well as CRAN.

rmapzen provides access to the following Mapzen API services:

Set-up

rmapzen works with API providers who implement the Mapzen API. In order to specify provider information (such as URL and API key), use mz_set_host. There are custom set-up functions for the following providers:

As of this writing, there are no public providers offering the Mapzen isochrone service.

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. Multiple tiles are stitched together and returned as an object of class mz_vector_tiles. See ?mz_vector_tiles. The sample data set ca_tiles contains zoomed out vector tile data for all of California as well as parts of neighboring states.

ca_tiles
#> Mapzen vector tile data
#> Layers: (count of features in parentheses)
#>     water (144)
#>     buildings (0)
#>     places (28)
#>     transit (10)
#>     pois (30)
#>     boundaries (22)
#>     roads (308)
#>     earth (4)
#>     landuse (176)

Each element of a vector tile response includes point, line, and/or polygon data for an individual map layer, and has class mapzen_vector_layer. Like other response types, the mapzen_vector_layer can be converted to sf and sp objects for further processing, using the generic functions as_sf and as_sp.

# points of interest
as_sf(ca_tiles$pois)
#> Registered S3 method overwritten by 'geojsonsf':
#>   method        from   
#>   print.geojson geojson
#> Simple feature collection with 30 features and 11 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -123.536 ymin: 32.009 xmax: -112.58 ymax: 48.808
#> Geodetic CRS:  WGS 84
#> # A tibble: 30 × 12
#>    kind   prote…¹ area  opera…² name:…³ source min_z…⁴ tier  osm_r…⁵ name  id   
#>    <chr>  <chr>   <chr> <chr>   <chr>   <chr>  <chr>   <chr> <chr>   <chr> <chr>
#>  1 natio… 2       1377… United… <NA>    opens… 5.58    1     TRUE    Crat… 5471…
#>  2 natio… 2       2035… United… <NA>    opens… 5.29    1     TRUE    Moun… 6c47…
#>  3 natio… 2       2132… United… Nation… opens… 3.6     1     TRUE    Deat… 4e80…
#>  4 natio… 2       2543… United… <NA>    opens… 5.13    1     TRUE    Crat… a710…
#>  5 natio… 2       2552… United… Sequoi… opens… 5.13    1     TRUE    Sequ… e7fc…
#>  6 natio… 2       2740… United… Nation… opens… 5.08    1     TRUE    Nort… 7bfb…
#>  7 natio… 2       2812… United… Kings-… opens… 5.06    1     TRUE    King… 553d…
#>  8 natio… 2       4671… United… Joshua… opens… 4.7     1     TRUE    Josh… 09bc…
#>  9 natio… 2       4858… United… Yosemi… opens… 4.67    1     TRUE    Yose… 4815…
#> 10 natio… 2       7790… United… Olympi… opens… 4.33    1     TRUE    Olym… e1e8…
#> # … with 20 more rows, 1 more variable: geometry <POINT [°]>, and abbreviated
#> #   variable names ¹​protect_class, ²​operator, ³​`name:de`, ⁴​min_zoom,
#> #   ⁵​osm_relation

sf and Spatial*DataFrame conversion

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)
library(sf)
as_sf(oakland_public) %>%
    select(name, confidence, region, locality, neighbourhood)
#> Simple feature collection with 25 features and 5 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -122.2854 ymin: 37.73742 xmax: -122.1749 ymax: 37.84632
#> Geodetic CRS:  WGS 84
#> # A tibble: 25 × 6
#>    name                 confi…¹ region local…² neigh…³             geometry
#>    <chr>                  <dbl> <chr>  <chr>   <chr>            <POINT [°]>
#>  1 Oakland Public Libr…   0.926 Calif… Oakland Shafter (-122.2625 37.83824)
#>  2 Oakland Public Libr…   0.926 Calif… Oakland Rockri…    (-122.2511 37.84)
#>  3 Lakeview Branch Oak…   0.664 Calif… Oakland <NA>     (-122.249 37.80919)
#>  4 Golden Gate Branch …   0.663 Calif… Oakland Gaskill (-122.2822 37.83937)
#>  5 Brookfield Village …   0.663 Calif… Oakland South … (-122.1886 37.73742)
#>  6 West Oakland Branch…   0.663 Calif… Oakland Ralph … (-122.2854 37.81296)
#>  7 Elmhurst Branch Oak…   0.663 Calif… Oakland Webster (-122.1749 37.75154)
#>  8 Montclair Branch Oa…   0.663 Calif… Oakland Montcl… (-122.2141 37.83204)
#>  9 Main Branch Oakland…   0.663 Calif… Oakland Civic … (-122.2638 37.80101)
#> 10 Latin American Bran…   0.663 Calif… Oakland St. El… (-122.2225 37.78354)
#> # … with 15 more rows, and abbreviated variable names ¹​confidence, ²​locality,
#> #   ³​neighbourhood

Accessor methods

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

mz_bbox(ca_tiles)
#> # A tibble: 1 × 4
#>   min_lon min_lat max_lon max_lat
#> *   <dbl>   <dbl>   <dbl>   <dbl>
#> 1    -135    32.0   -112.    48.9