elevatr (version 0.1.1)

get_elev_raster: Get Raster Elevation

Description

Several web services provide access to raster elevation. Currently, this function provides access to the Mapzen Terrain Service The function accepts a data.frame of x (long) and y (lat), an sp, or raster object as input. A raster object is returned.

Usage

get_elev_raster(locations, z, prj = NULL, src = c("mapzen", "aws"), api_key = get_api_key(src), expand = NULL, ...)

Arguments

locations

Either a data.frame of x (long) and y (lat), an sp, or raster object as input.

z

The zoom level to return. The zoom ranges from 1 to 14. Resolution of the resultant raster is determined by the zoom and latitude. For details on zoom and resolution see the documentation from Mapzen at https://mapzen.com/documentation/terrain-tiles/data-sources/#what-is-the-ground-resolution

prj

A PROJ.4 string defining the projection of the locations argument. If a sp or raster object is provided, the PROJ.4 string will be taken from that. This argument is required for a data.frame of locations."

src

A character indicating which API to use, currently either "mapzen" (default), or "aws" is used. Both use the same source tiles. The Amazon Web Services tiles are best if rate limits are causing failure of the Mapzen tiles or if you are accessing the data via and AWS instance.

api_key

A valid API key.

expand

A numeric value of a distance, in map units, used to expand the bounding box that is used to fetch the terrain tiles. This can be used for features that fall close to the edge of a tile and additional area around the feature is desired. Default is NULL.

...

Extra arguments to pass to httr::GET via a named vector, config. See get_mapzen_terrain and get_aws_terrain for more details.

Value

Function returns a SpatialPointsDataFrame in the projection specified by the prj argument.

Details

Currently, the get_elev_raster utilizes two separate APIs, the Mapzen Terrain Tile Service (https://mapzen.com/documentation/terrain-tiles/) or the Amazon Web Services (https://aws.amazon.com/public-datasets/terrain/). Both services utilize the same underlying data and provide global coverage, but they have different use cases. The Mapzen service is cached and thus should provide speedier downloads. It will work without an API key but an API key is suggested. Both services are provided via x, y, and z tiles (see http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames for details.) The x and y are determined from the bounding box of the object submitted for locations argument, and the z argument must be specified by the user.

Examples

## Not run: 
# loc_df <- data.frame(x = runif(6,min=sp::bbox(lake)[1,1], 
#                                max=sp::bbox(lake)[1,2]),
#                      y = runif(6,min=sp::bbox(lake)[2,1], 
#                                max=sp::bbox(lake)[2,2]))
# x <- get_elev_raster(locations = loc_df, prj = sp::proj4string(lake), z=10, 
#                      api_key = NULL)
# 
# data(lake)
# x <- get_elev_raster(lake, z = 3, src = "mapzen")
# x <- get_elev_raster(lake, z = 12, src = "aws")
# ## End(Not run)