pygmt.datasets.load_tile_map

pygmt.datasets.load_tile_map(region, zoom='auto', source=None, lonlat=True, crs='EPSG:3857', wait=0, max_retries=2, zoom_adjust=None)[source]

Load a georeferenced raster tile map from XYZ tile providers.

The tiles that compose the map are merged and georeferenced into an xarray.DataArray image with 3 bands (RGB). Note that the returned image is in a Spherical Mercator (EPSG:3857) coordinate reference system (CRS) by default, but can be customized using the crs parameter.

Parameters:

region (Sequence[float]) – The bounding box of the map in the form of a list [xmin, xmax, ymin, ymax]. These coordinates should be in longitude/latitude if lonlat=True or Spherical Mercator (EPSG:3857) if lonlat=False.
zoom (Union[int, Literal['auto']], default: 'auto') –
Level of detail. Higher levels (e.g. 22) mean a zoom level closer to the Earth’s surface, with more tiles covering a smaller geographical area and thus more detail. Lower levels (e.g. 0) mean a zoom level further from the Earth’s surface, with less tiles covering a larger geographical area and thus less detail. Default is "auto" to automatically determine the zoom level based on the bounding box region extent.

Note

The maximum possible zoom level may be smaller than 22, and depends on what is supported by the chosen web tile provider source.
source (TileProvider | str | None, default: None) –
The tile source: web tile provider or path to a local file. Provide either:
- A web tile provider in the form of a xyzservices.TileProvider object. See Contextily providers for a list of tile providers. Default is xyzservices.providers.OpenStreetMap.HOT, i.e. OpenStreetMap Humanitarian web tiles.
- A web tile provider in the form of a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. E.g. https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png.
- A local file path. The file is read with rasterio and all bands are loaded into the basemap. See Working with local files.
Important

Tiles are assumed to be in the Spherical Mercator projection (EPSG:3857).
lonlat (bool, default: True) – If False, coordinates in region are assumed to be Spherical Mercator as opposed to longitude/latitude.
crs (str | CRS, default: 'EPSG:3857') – Coordinate reference system (CRS) of the returned xarray.DataArray image. Default is "EPSG:3857" (i.e., Spherical Mercator). The CRS can be in either string or rasterio.crs.CRS format.
wait (int, default: 0) – If the tile API is rate-limited, the number of seconds to wait between a failed request and the next try.
max_retries (int, default: 2) – Total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API.
zoom_adjust (int | None, default: None) –
The amount to adjust a chosen zoom level if it is chosen automatically. Values outside of -1 to 1 are not recommended as they can lead to slow execution.

Note

The zoom_adjust parameter requires contextily>=1.5.0.

Return type:

DataArray

Returns:

raster – Georeferenced 3-D data array of RGB values.

Raises:

ImportError – If contextily is not installed or can’t be imported. Follow the install instructions for contextily, (e.g. via python -m pip install contextily) before using this function.

Examples

>>> import contextily
>>> from pygmt.datasets import load_tile_map
>>> raster = load_tile_map(
...     region=[-180.0, 180.0, -90.0, 0.0],  # West, East, South, North
...     zoom=1,  # less detailed zoom level
...     source=contextily.providers.OpenTopoMap,
...     lonlat=True,  # bounding box coordinates are longitude/latitude
... )
>>> raster.sizes
Frozen({'band': 3, 'y': 256, 'x': 512})
>>> raster.coords  
Coordinates:
  * band         (band) uint8... 1 2 3
  * y            (y) float64... -7.081e-10 -7.858e+04 ... -1.996e+07 -2.004e+07
  * x            (x) float64... -2.004e+07 -1.996e+07 ... 1.996e+07 2.004e+07
    spatial_ref  int... 0
>>> # CRS is set only if rioxarray is available
>>> if hasattr(raster, "rio"):
...     raster.rio.crs.to_string()
'EPSG:3857'