pygmt.datasets.load_tile_map

pygmt.datasets.load_tile_map(region, zoom='auto', source=None, lonlat=True, wait=0, max_retries=2)[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.

Parameters

  • region (list) – 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 (int or str) –

    Optional. 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 (xyzservices.TileProvider or str) –

    Optional. 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.Stamen.Terrain, i.e. Stamen Terrain 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) – Optional. If False, coordinates in region are assumed to be Spherical Mercator as opposed to longitude/latitude [Default is True].

  • wait (int) – Optional. If the tile API is rate-limited, the number of seconds to wait between a failed request and the next try [Default is 0].

  • max_retries (int) – Optional. Total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API [Default is 2].

Returns

raster (xarray.DataArray) – Georeferenced 3-D data array of RGB values.

Raises

ImportError – If contextily is not installed or can’t be imported. Follow install instructions for contextily, (e.g. via 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.Stamen.TerrainBackground,
...     lonlat=True,  # bounding box coordinates are longitude/latitude
... )
>>> raster.sizes
Frozen({'band': 3, 'y': 256, 'x': 512})
>>> raster.coords
Coordinates:
  * band         (band) uint8 0 1 2
  * y            (y) float64 -7.081e-10 -7.858e+04 ... -1.996e+07 ...
  * x            (x) float64 -2.004e+07 -1.996e+07 ... 1.996e+07 2.004e+07