Skip to contents

Map layer: basemap / overlay tiles

Source: R/tm_layers_aux.R
tm_basemap.Rd

Map layer that draws tiles from a tile server. tm_basemap() draws the tile layer as basemap, i.e. as bottom layer. In contrast, tm_tiles() draws the tile layer as overlay layer, where the stacking order corresponds with the order in which this layer is called, just like other map layers.

Usage

tm_basemap(
  server = NA,
  alpha = NULL,
  zoom = NULL,
  api = NULL,
  max.native.zoom = 17,
  sub = "abc",
  zindex = 0,
  group = NA,
  group.control = "radio"
)

tm_tiles(
  server = NA,
  alpha = NULL,
  zoom = NULL,
  max.native.zoom = 17,
  sub = "abc",
  zindex = NA,
  group = NA,
  group.control = "check"
)

Arguments

server

Name of the provider or an URL. Or a vector of multiple values. The list of available providers can be obtained with providers (tip: in RStudio, type leaflet::providers$ to see the options). See https://leaflet-extras.github.io/leaflet-providers/preview/ for a preview of those. When a URL is provided, it should be in template format, e.g. "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png". Use NULL in tm_basemap() to disable basemaps. It can be a named vector. In that case these names will be used a group names, as alternative to the argument group.

alpha

Transparency level

zoom

Zoom level (only used in plot mode)

api

API key. Required for CartoDB basemaps (plot and view mode), Stadia/Thunderforest maps (plot mode), and Esri/MapTiler basemaps in "maplibre"/"mapbox" mode (alternatively set the env var ARCGIS_API_KEY / MAPTILER_API_KEY). See details

max.native.zoom

Maximum native zoom level (only used in view mode). The minimum and maximum zoom levels are determined in tm_view().

sub

subdomain of the tile server. Only used when server is a url template. The default is "abc" which works for most tile servers.

zindex

Controls the stacking order of map layers. Should be set to a value above 400. By default, layers are stacked in call order, starting at 401. See details.

group

Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see group.control)

group.control

In view mode, the group control determines how layer groups can be switched on and off. Options: "radio" for radio buttons (meaning only one group can be shown), "check" for check boxes (so multiple groups can be shown), and "none" for no control (the group cannot be (de)selected).

Details

API keys. CARTO, Stadia and Thunderforest require an API key for their maps. This can be set via the argument api, e.g. tm_basemap("CartoDB.Positron", api = "YOUR_KEY"). For Stadia and Thunderforest (plot mode only), the key can alternatively be stored in the environment variables "STADIA_MAPS" and "THUNDERFOREST_MAPS" with Sys.setenv(). Without a key, CARTO basemaps still work, but are shown with an "API KEY REQUIRED" watermark.

Advanced: for other, custom tile services that require an API key (i.e. not one of the providers above), server can instead be a URL template containing the placeholder "{apikey}", which is substituted with api, e.g. tm_basemap("https://example.com/tiles/{z}/{x}/{y}.png?key={apikey}", api = "YOUR_KEY").

In view mode, each layer is rendered in a Leaflet pane named "tmap{zindex}" (e.g., "tmap401", "tmap402"), with base tile layers placed in the standard "tile" pane.

See also

Basemaps, Modes

Examples

if (FALSE) { # \dontrun{
if (requireNamespace("maptiles")) {
  # view mode
  current_mode = tmap_mode("view")
  tm_basemap("Stadia.StamenWatercolor") +
    tm_shape(World) +
    tm_polygons(
      "HPI",
      fill.scale = tm_scale(values = "reds"),
      fill_alpha.scale = 0.5)

  tm_shape(World, crs = "+proj=eqearth") +
    tm_polygons(
      "HPI",
      fill.scale = tm_scale(values = "reds"),
      fill_alpha.scale = 0.5) +
  tm_basemap(NULL)

  # plot mode:
  tmap_mode("plot")
  tm_basemap() +
    tm_shape(World) +
    tm_polygons("HPI")

  tm_basemap("OpenTopoMap") +
    tm_shape(World) +
    tm_polygons(fill = NA, col = "black")

  tm_basemap("CartoDB.PositronNoLabels") +
  tm_shape(NLD_prov, crs = 4236) +
    tm_borders() +
    tm_facets_wrap("name") +
    tm_tiles("CartoDB.PositronOnlyLabels")

  # restore mode
  tmap_mode(current_mode)
}
} # }