Introduction to rmapzen
In rmapzen: Client for 'Mapzen' and Related Map APIs

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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:

Search: Structured and unstructured search and geocoding, reverse geocoding, and autocomplete.
Vector Tiles: Basemap vector data.
Isochrone: Calculation of areas reachable from a specified locations.

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:

geocode.earth, for search services. Use the function mz_set_search_host_geocode.earth
Nextzen, for vector tiles. Use the function mz_set_tile_host_nextzen.
NYC GeoSearch, for search services using New York City's Property Address Directory. Use mz_set_search_host_nyc_geosearch.

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

Search

All of the services in Mapzen search have been implemented. Search functions:

mz_search
mz_reverse_geocode
mz_autocomplete
mz_place
mz_structured_search (what's this?)

Each of those functions returns a mapzen_geo_list. The sample dataset oakland_public contains the results of mz_search("Oakland public library branch") on January 8, 2017:

library(rmapzen)
oakland_public

mz_bbox(oakland_public)
as.data.frame(oakland_public)

Search can, optionally, be constrained to a particular country, data layer, boundary rectangle, or boundary circle. Furthermore, search can prioritize results near a given "focus" point. See ?mz_search.

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

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 objects for further processing, using the generic function as_sf

# points of interest
as_sf(ca_tiles$pois)

`sf` conversion

Any object returned by a Mapzen service can be converted to the appropriate sf object using the generic 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)

Accessor methods

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

mz_coordinates (only available for search results): extracts lat/lon coordinates from search results, and returns them as a data.frame.
mz_bbox: returns the bounding box of an object as a data.frame with columns min_lon, min_lat, max_lon, and max_lat.