Skip to contents

Get static map tiles based on a spatial object. Maps can be fetched from various open map servers.

This function is a implementation of the javascript plugin leaflet-providersESP v1.3.3.


  type = "IDErioja",
  zoom = NULL,
  zoommin = 0,
  crop = TRUE,
  res = 512,
  bbox_expand = 0.05,
  transparent = TRUE,
  mask = FALSE,
  update_cache = FALSE,
  cache_dir = NULL,
  verbose = FALSE,
  options = NULL



An sf or sfc object.


This parameter could be either:


Zoom level. If NULL, it is determined automatically. If set, it overrides zoommin. Only valid for WMTS tiles. On a single point it applies a buffer to the point and on zoom = NULL the function set a zoom level of 18. See Details.


Delta on default zoom. The default value is designed to download fewer tiles than you probably want. Use 1 or 2 to increase the resolution.


TRUE if results should be cropped to the specified x extent, FALSE otherwise. If x is an sf object with one POINT, crop is set to FALSE.


Resolution (in pixels) of the final tile. Only valid for WMS.


A numeric value that indicates the expansion percentage of the bounding box of x.


Logical. Provides transparent background, if supported. Depends on the selected provider on type.


TRUE if the result should be masked to x.


A logical whether to update cache. Default is FALSE. When set to TRUE it would force a fresh download of the source file.


A path to a cache directory. See About caching.


Logical, displays information. Useful for debugging, default is FALSE.


A named list containing additional options to pass to the query.


A SpatRaster is returned, with 3 (RGB) or 4 (RGBA) layers, depending on the provider. See terra::rast(). .


Zoom levels are described on the OpenStreetMap wiki:

zoomarea to represent
0whole world
3large country
10metropolitan area
13village or suburb
18some buildings, trees

For a complete list of providers see esp_tiles_providers.

Most WMS/WMTS providers provide tiles on "EPSG:3857". In case that the tile looks deformed, try projecting first x:

x <- sf::st_transform(x, 3857)

About caching

You can set your cache_dir with esp_set_cache_dir().

Sometimes cached files may be corrupt. On that case, try re-downloading the data setting update_cache = TRUE.

If you experience any problem on download, try to download the corresponding .geojson file by any other method and save it on your cache_dir. Use the option verbose = TRUE for debugging the API query.

See also


# \dontrun{
# This script downloads tiles to your local machine
# Run only if you are online

segovia <- esp_get_prov_siane("segovia", epsg = 3857)
tile <- esp_getTiles(segovia, "IGNBase.Todo")

#> Attaching package: ‘tidyterra’
#> The following object is masked from ‘package:stats’:
#>     filter

ggplot(segovia) +
  geom_spatraster_rgb(data = tile, maxcell = Inf) +
  geom_sf(fill = NA)

# Another provider

tile2 <- esp_getTiles(segovia, type = "MDT")

ggplot(segovia) +
  geom_spatraster_rgb(data = tile2, maxcell = Inf) +
  geom_sf(fill = NA)

# A custom WMS provided

custom_wms <- esp_make_provider(
  id = "an_id_for_caching",
  q = "",
  service = "WMS",
  version = "1.3.0",
  format = "image/png",
  layers = "geolog_cyl_litologia"

custom_wms_tile <- esp_getTiles(segovia, custom_wms)

autoplot(custom_wms_tile, maxcell = Inf) +
  geom_sf(data = segovia, fill = NA, color = "red")

# A custom WMTS provider

custom_wmts <- esp_make_provider(
  id = "cyl_wmts",
  q = "",
  service = "WMTS",
  layer = "OI.OrthoimageCoverage"

custom_wmts_tile <- esp_getTiles(segovia, custom_wmts)

autoplot(custom_wmts_tile, maxcell = Inf) +
  geom_sf(data = segovia, fill = NA, color = "white", linewidth = 2)

# Example from
cartodb_voyager <- list(
  id = "CartoDB_Voyager",
  q = "{z}/{x}/{y}.png"
cartodb <- esp_getTiles(segovia, cartodb_voyager, zoommin = 1)

autoplot(cartodb, maxcell = Inf) +
  geom_sf(data = segovia, fill = NA, color = "black", linewidth = 1)

# }