rmapzen: A client application for the 'Mapzen' API.

Description

The rmapzen package provides interfaces to the Search <https://github.com/pelias/documentation/>, Isochrone <https://valhalla.readthedocs.io/en/latest/>, and Vector Tile <https://tilezen.readthedocs.io/en/latest/> services from 'Mapzen', via the following functions:

Search

All functionality described in <https://github.com/pelias/documentation/> are supported:

• mz_search

• mz_reverse_geocode

• mz_autocomplete

• mz_place

• mz_structured_search

Additionally, mz_geocode is useful for a common application of search, that of just obtaining latitude and longitude for a given address or place.

Isochrone

Isochrones are the areas reachable from a given location within a specified period of time. Mapzen's Isochrone service can calculate isochrones for driving, walking, cycling, or multimodal forms of transport:

• mz_isochrone

• mz_costing: for constructing "costing models" that describe method of transport along with speed and other options relevant to the calculation of the isochrone

• mz_costing_options: for selecting specific options when constructing a costing model

Vector Tiles

• mz_vector_tiles: Request one or more adjacent tiles. Multiple map tiles will be stitched together before being returned as a single object.

• mz_tile_coordinates: When using mz_vector_tiles, you must specify the geographic area for which you want tile data. One way to do so is using the x, y, z tile naming system (see <https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames>).

• mz_rect: Alternatively, you can specify the lower left and top-right points of a bounding box, which will automatically be converted to tile-coordinates when you use mz_vector_tiles

• mz_bbox: This is a generic function which will return the bounding box of any Mapzen object. In this way, you can request vector tiles for a region defined as the bounding box of an existing object.

Data types and conversion

Objects returned by rmapzen can be converted to simple features (sf) via the generic function as_sf. Search and Isochrone objects can additionally be converted to ordinary data.frames via as.data.frame.

Author(s)

Maintainer: Tarak Shah tarak.shah@gmail.com

Other contributors:

• Daniel Possenriede [contributor]

See Also

• <https://tarakc02.github.io/rmapzen/> contains detailed examples

• <https://www.mapzen.com/documentation/> 'Mapzen' documentation

Coerce a Mapzen response to a simple features object

Description

Coerces responses to class sf. See vignette("sf1", package = "sf") for more information about Simple Features for R.

Usage

as_sf(geo, ...)

## S3 method for class 'geo_list'
as_sf(geo, ...)

## S3 method for class 'mapzen_vector_layer'
as_sf(geo, ...)

Arguments

Vector tiles the contain California

Description

Vector tiles the contain California

Usage

ca_tiles

Format

An object of class mapzen_vector_tiles (inherits from list) of length 9.

Source

Mapzen, OpenStreetMap contributors, Who's On First, Natural Earth, and openstreetmapdata.com

Costing model constructors and helpers

Description

Mapzen's Isochrone service (mz_isochrone) as well as other mobility services (currently not implemented in this package, read more at https://valhalla.readthedocs.io/en/latest/) require users to specify a "costing model." See https://valhalla.readthedocs.io/en/latest/ for details. These can be difficult to construct correctly, so the objects mz_costing and mz_costing_options exist to make that process less error-prone and more convenient.

Usage

mz_costing

mz_costing_options

Format

An object of class list of length 4.

An object of class list of length 4.

See Also

mz_isochrone

Examples

## creates a pedestrian costing model with walking speed of 2 km/hr
## that also avoids alleys.
## non-multimodal costing models will accept 0 or more options from the
## appropriate list.
mz_costing$pedestrian(
    mz_costing_options$pedestrian$walking_speed(2.0),
    mz_costing_options$pedestrian$alley_factor(0)
)

## creates a multimodal costing model that favors buses over rails, and
## has a slower than default walking speed
## (note multimodal has named arguments requiring list inputs)
mz_costing$multimodal(
    transit = list(
        mz_costing_options$transit$use_bus(1.0),
        mz_costing_options$transit$use_rail(5)
    ),
    pedestrian = list(
        mz_costing_options$pedestrian$walking_speed(4.1)
    )
)

Reference lists

Description

Lists of sources, layers, and countries, as they are expected to appear in the mz_search functions. These data objects are provided as a convenience, to be able to quickly and easily look up acceptable values for the optional arguments of search functions. Object names match the argument names for which they are appropriate. So mz_sources provide acceptable arguments for the source argument in mz_search, mz_layers for the layer argument, and mz_countries for the boundary.country argument. Mapzen's documentation (https://github.com/pelias/documentation/) explains more about each of these arguments.

Usage

mz_sources

mz_layers

mz_countries

Format

An object of class list of length 8.

An object of class list of length 13.

An object of class list of length 747.

Examples

## Not run: 
# look for YMCAs in Jamaica:
# Note that boundary.country is supplied via ISO3166 code,
# but mz_countries will look up the code
mz_search("YMCA",
          boundary.country = mz_countries$Jamaica,
          layers = c(mz_layers$venue, mz_layers$address))

## End(Not run)

Pedestrian isochrones from the Berkeley Marina for 10 and 15 minutes

Description

Isochrone results from Mapzen as of January 8, 2017. The location for the isochrones is the Berkeley Marina, lat 37.86613, lon -122.3151

Usage

marina_walks

Format

An object of class mapzen_isochrone_list (inherits from geo_list) of length 3.

Source

Mapzen, OpenStreetMap, British Oceanographic Data Centre, NASA, USGS, and Transitland.

Pedestrian isochrones from the Berkeley Marina for 10 and 15 minutes, as polygons

Description

Polygon Isochrone results (using polygons = TRUE) from Mapzen as of January 10, 2017. The location for the isochrones is the Berkeley Marina, lat 37.86613, lon -122.3151, and the contours are 10 and 15 minutes for a pedestrian costing model.

Usage

marina_walks_polygons

Format

An object of class mapzen_isochrone_list (inherits from geo_list) of length 3.

Source

Mapzen, OpenStreetMap, British Oceanographic Data Centre, NASA, USGS, and Transitland.

Mapzen search API

Description

Functions to access the various endpoints from the Mapzen Search API. For more details, see https://github.com/pelias/documentation/. If your data is already split up by street, city, state, zip, etc., then you might find mz_structured_search to be more precise. All arguments besides text (point in the case of mz_reverse_geocode) are optional. If you have parsed addresses (e.g. for geocoding), use mz_structured_search

Usage

mz_autocomplete(
  text,
  boundary.country = NULL,
  boundary.rect = NULL,
  focus.point = NULL,
  sources = NULL,
  layers = NULL,
  api_key = NULL
)

mz_reverse_geocode(
  point,
  size = NULL,
  layers = NULL,
  sources = NULL,
  boundary.country = NULL,
  api_key = NULL
)

mz_search(
  text,
  size = 10,
  boundary.country = NULL,
  boundary.rect = NULL,
  boundary.circle = NULL,
  focus.point = NULL,
  sources = NULL,
  layers = NULL,
  api_key = NULL
)

Arguments

See Also

mz_place, mz_structured_search, mz_countries, mz_sources, mz_layers

Examples

## Not run: 
# hard rock cafes in sweden:
mz_search("Hard Rock Cafe", boundary.country = "SE")

# autocompletions when the user types in "Union Square"
# prioritizing San Francisco results first:
mz_autocomplete("Union Square",
                focus.point = mz_geocode("San Francisco, CA"))

## End(Not run)

Get the bounding box

Description

Returns the bottom left and top right corners of the box that contains a mapzen object (mz_geo_list, mz_isochrone_list, or mapzen_vector_tiles). In the case of mz_rect, creates such a box from the specified coordinates. The returned value can be used directly as the boundary.rect parameter for search functions, as well as converted to x, y, zoom coordinates to use with mz_vector_tiles.

Usage

mz_bbox(geo)

## S3 method for class 'mapzen_geo_list'
mz_bbox(geo)

## S3 method for class 'mapzen_isochrone_list'
mz_bbox(geo)

mz_rect(min_lon, min_lat, max_lon, max_lat)

Arguments

Value

A single-row tibble with columns min_lon, min_lat, max_lon, max_lat.

Examples

mz_rect(min_lon = -122.2856, min_lat = 37.73742, max_lon = -122.1749, max_lat = 37.84632)
mz_bbox(oakland_public)

Check usage statistics

Description

Prints out remaining queries for various time periods. rmapzen manages rate limiting for the per-second limits, but does not keep track of the daily limits.

Usage

mz_check_usage()

Details

This function is populated from the headers of responses to various API requests. If no queries have been made, or if the only queries so far have hit cache servers, then no information will be available.

Create an mz_contours object

Description

Contours are given as inputs to mz_isochrone. This function makes it convenient to construct them.

Usage

mz_contours(times, colors = NULL)

Arguments

Extract a data frame of coordinates from a mapzen_geo_list

Description

Extract a data frame of coordinates from a mapzen_geo_list

Usage

mz_coordinates(geo)

## S3 method for class 'mapzen_geo_list'
mz_coordinates(geo)

Arguments

Value

A tibble, with columns lon and lat.

Examples

mz_coordinates(oakland_public)

Create mz_date_time objects

Description

Mobility services (such as mz_isochrone) take, optionally, a date_time argument that specifies the date and time along with type (departure/arrival). This function constructs the appropriate objects to use as date_time arguments.

Usage

mz_date_time(date_time, type = "departure")

Arguments

Geocode an address or other location

Description

This is a convenience function that calls mz_search to retrieve latitude and longitude.

Usage

mz_geocode(location, ...)

Arguments

Value

A tibble, with the parsed address used to retrieve the geocode, lat/lon, and the confidence (between 0 and 1)

See Also

mz_search, mz_reverse_geocode

Examples

## Not run: 
mz_geocode("1600 Pennsylvania Ave., Washington DC")

# can also be a landmark
mz_geocode("Statue of Liberty, New York")

## End(Not run)

Geocode a structured address

Description

mz_geocode allows you to search using an unstructured string of text, but if your address data has more structure (eg separate columns for address, city, state, zip), then using the structured search service may provide more precision. For more information, see https://github.com/pelias/documentation/. Note that all of the arguments are optional, but at least one of them must be non-NULL. Furthermore, postalcode can not be used by itself.

Usage

mz_geocode_structured(
  address = NULL,
  neighbourhood = NULL,
  borough = NULL,
  locality = NULL,
  county = NULL,
  region = NULL,
  postalcode = NULL,
  country = NULL,
  ...
)

Arguments

Value

A tibble, with the parsed address used to retrieve the geocode, lat/lon, and the confidence (between 0 and 1)

See Also

mz_geocode, mz_structured_search

Retrieve isochrones

Description

From https://valhalla.readthedocs.io/en/latest/: "An isochrone is a line that connects points of equal travel time about a given location, from the Greek roots of 'iso' for equal and 'chrone' for time. The Mapzen Isochrone service computes 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."

Usage

mz_isochrone(
  locations,
  costing_model,
  contours,
  date_time = NULL,
  polygons = NULL,
  denoise = NULL,
  generalize = NULL,
  id = "my-iso",
  api_key = NULL
)

Arguments

Value

A mapzen_isochrone_list, which can be converted to sf using as_sf.

See Also

mz_costing

Examples

## Not run: 
mz_isochrone(
    mz_location(lat = 37.87416, lon = -122.2544),
    costing_model = mz_costing$auto(),
    contours = mz_contours(c(10, 20, 30))
)

# departure point can be specified as a geocode result
mz_isochrone(
    mz_geocode("UC Berkeley"),
    costing_model = mz_costing$pedestrian(),
    contours = mz_contours(c(10, 20, 30))
)

## End(Not run)

Create/extract lat/lon location information

Description

mz_location constructs a new mz_location object, which can be used with functions such as mz_isochrone or mz_reverse_geocode. as.mz_location coerces eligible objects to mz_locations.

Usage

mz_location(lat, lon)

as.mz_location(x, ...)

## Default S3 method:
as.mz_location(x, ...)

## S3 method for class 'mz_geocode_result'
as.mz_location(x, ...)

Arguments

See Also

mz_isochrone For using the Mapzen isochrone service mz_contours, mz_costing, and mz_costing_options for other argument constructors

Get details on a place

Description

Search functions (e.g. mz_search) return identification numbers, or gids. Use mz_place to retrieve more details about the place. See https://github.com/pelias/documentation/ for details. This function is generic, and can take a character vector of IDs, or a mapzen_geo_list as returned by mz_search and friends.

Usage

mz_place(ids, ..., api_key = NULL)

## S3 method for class 'character'
mz_place(ids, ..., api_key = NULL)

## S3 method for class 'mapzen_geo_list'
mz_place(ids, ..., gid = "gid", api_key = NULL)

Arguments

Configure provider information

Description

rmapzen works with most implementations of PELIAS. This function defines the base URL for a particular API provider, and can be used to provider the provider argument to mz_set_host.

Usage

mz_provider(hostname, path = NULL, key = NULL, scheme = "https")

Arguments

See Also

mz_set_host

Set up a host provider for a PELIAS service

Description

rmapzen works with most implementations of PELIAS. Use this function to set up the basic information required to connect to a particular provider. Provider-specific setup functions include information to set up known providers.

Usage

mz_set_host(which, provider)

mz_get_host(which)

mz_set_search_host_geocode.earth(key = Sys.getenv("GEOCODE.EARTH_KEY"))

mz_set_search_host_nyc_geosearch()

mz_set_tile_host_nextzen(key = Sys.getenv("NEXTZEN_KEY"))

Arguments

See Also

mz_provider

Structured search

Description

mz_search allows you to search using an unstructured string of text, but if your address data has more structure (eg separate columns for address, city, state, zip), then using the structured search service may provide more precision. For more information, see https://github.com/pelias/documentation. Note that all of the arguments are optional, but at least one of them must be non-NULL. Furthermore, postalcode can not be used by itself.

Usage

mz_structured_search(
  address = NULL,
  neighbourhood = NULL,
  borough = NULL,
  locality = NULL,
  county = NULL,
  region = NULL,
  postalcode = NULL,
  country = NULL,
  api_key = NULL,
  ...
)

Arguments

See Also

mz_search

Specify tile coordinates

Description

mz_vector_tiles requires tile coordinates or some other specification of the region that is to be drawn. mz_vector_tiles will automatically convert its inputs to vector tiles, so you generally won't need to use this function directly.

Usage

mz_tile_coordinates(x, y, z)

as.mz_tile_coordinates(obj, ...)

## S3 method for class 'mz_tile_coordinates'
as.mz_tile_coordinates(obj, ...)

## S3 method for class 'mz_bbox'
as.mz_tile_coordinates(obj, ..., z = NULL, height = NULL, width = NULL)

## S3 method for class 'mz_location'
as.mz_tile_coordinates(obj, ..., z = 15L)

## S3 method for class 'mz_geocode_result'
as.mz_tile_coordinates(obj, ..., z = 15L)

Arguments

See Also

mz_vector_tiles, mz_bbox

Examples

mz_tile_coordinates(19293, 24641, 16)

## can specify multiple contiguous tiles:
mz_tile_coordinates(19293:19294, 24641:24642, 16)

## a rectangular bounding box can be converted to tile coordinates:
as.mz_tile_coordinates(mz_rect(min_lon = -122.2856,
                               min_lat = 37.73742,
                               max_lon = -122.1749,
                               max_lat = 37.84632))

## zoom level is calculated based on desired pixel dimensions of the map:
as.mz_tile_coordinates(mz_rect(min_lon = -122.2856,
                               min_lat = 37.73742,
                               max_lon = -122.1749,
                               max_lat = 37.84632), height = 750, width = 1000)

## a bounding box can also be calculated:
as.mz_tile_coordinates(mz_bbox(oakland_public))

Request vector tile data

Description

From https://tilezen.readthedocs.io/en/latest/: "Vector tiles are square-shaped collections of geographic data that contain the map feature geometry, such as lines and points."

Usage

mz_vector_tiles(tile_coordinates, ..., Origin = NULL)

Arguments

Details

Multiple tiles are stitched together and returned as one object. Individual layers can be converted to sf or sp, making it possible to draw each layer with custom styles.

Value

A list of tile layers (such as "water", "buildings", "roads", etc.). Each layer is an object of class mapzen_vector_layer, which can be converted to sf using as_sf

See Also

mz_tile_coordinates

Examples

## Not run: 
# vector tile at x = 19293, y = 24641, and zoom level 16
mz_vector_tiles(mz_tile_coordinates(19293, 24641, 16))

# multiple contiguous tiles will be stitched together
# this returns the result of stitching together 4 tiles
mz_vector_tiles(mz_tile_coordinates(19293:19294, 24641:24642, 16))

# can also use a bounding box:
mz_vector_tiles(mz_rect(min_lon = -122.2856,
                        min_lat = 37.73742,
                        max_lon = -122.1749,
                        max_lat = 37.84632))

# mz_bbox returns a bounding box for any Mapzen object
mz_vector_tiles(mz_bbox(oakland_public))

# bounding boxes are automatically converted to tile coordinates,
# with the zoom level based on the desired size in pixels of the final map
mz_vector_tiles(mz_bbox(oakland_public), height = 750, width = 1000)

## End(Not run)

25 search results for "Oakland Public library branch"

Description

Contains the search results from Mapzen's search service for the query "Oakland public library branch" as of January 8, 2017.

Usage

oakland_public

Format

A mapzen_geo_list with 25 locations

Source

Mapzen, OpenStreetMap, OpenAddresses, GeoNames, WhosOnFirst, see https://www.mapzen.com/rights/