Reference Guide¶

Plotting basemaps¶

contextily.add_basemap(ax, zoom='auto', source=None, interpolation='bilinear', attribution=None, attribution_size=8, reset_extent=True, crs=None, resampling=Resampling.bilinear, **extra_imshow_args)¶

Add a (web/local) basemap to ax.

Parameters

axAxesSubplot: Matplotlib axes object on which to add the basemap. The extent of the axes is assumed to be in Spherical Mercator (EPSG:3857), unless the crs keyword is specified.
zoomint or ‘auto’: [Optional. Default=’auto’] Level of detail for the basemap. If ‘auto’, it is calculated automatically. Ignored if source is a local file.
sourcexyzservices.TileProvider object or str: [Optional. Default: Stamen Terrain web tiles] The tile source: web tile provider or path to local file. The web tile provider can be in the form of a xyzservices.TileProvider object or a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. For local file paths, the file is read with rasterio and all bands are loaded into the basemap. IMPORTANT: tiles are assumed to be in the Spherical Mercator projection (EPSG:3857), unless the crs keyword is specified.
interpolationstr: [Optional. Default=’bilinear’] Interpolation algorithm to be passed to imshow. See matplotlib.pyplot.imshow for further details.
attributionstr: [Optional. Defaults to attribution specified by the source] Text to be added at the bottom of the axis. This defaults to the attribution of the provider specified in source if available. Specify False to not automatically add an attribution, or a string to pass a custom attribution.
attribution_sizeint: [Optional. Defaults to ATTRIBUTION_SIZE]. Font size to render attribution text with.
reset_extentbool: [Optional. Default=True] If True, the extent of the basemap added is reset to the original extent (xlim, ylim) of ax
crsNone or str or CRS: [Optional. Default=None] coordinate reference system (CRS), expressed in any format permitted by rasterio, to use for the resulting basemap. If None (default), no warping is performed and the original Spherical Mercator (EPSG:3857) is used.
resampling<enum ‘Resampling’>: [Optional. Default=Resampling.bilinear] Resampling method for executing warping, expressed as a rasterio.enums.Resampling method
**extra_imshow_args :: Other parameters to be passed to imshow.

Examples

>>> import geopandas
>>> import contextily as ctx
>>> db = geopandas.read_file(ps.examples.get_path('virginia.shp'))

Ensure the data is in Spherical Mercator:

>>> db = db.to_crs(epsg=3857)

Add a web basemap:

>>> ax = db.plot(alpha=0.5, color='k', figsize=(6, 6))
>>> ctx.add_basemap(ax, source=url)
>>> plt.show()

Or download a basemap to a local file and then plot it:

>>> source = 'virginia.tiff'
>>> _ = ctx.bounds2raster(*db.total_bounds, zoom=6, source=source)
>>> ax = db.plot(alpha=0.5, color='k', figsize=(6, 6))
>>> ctx.add_basemap(ax, source=source)
>>> plt.show()

contextily.add_attribution(ax, text, font_size=8, **kwargs)¶

Utility to add attribution text.

Parameters

axAxesSubplot: Matplotlib axes object on which to add the attribution text.
textstr: Text to be added at the bottom of the axis.
font_sizeint: [Optional. Defaults to 8] Font size in which to render the attribution text.
**kwargsAdditional keywords to pass to the matplotlib text method.

Returns

matplotlib.text.Text: Matplotlib Text object added to the plot.

Working with tiles¶

contextily.bounds2raster(w, s, e, n, path, zoom='auto', source=None, ll=False, wait=0, max_retries=2)¶

Take bounding box and zoom, and write tiles into a raster file in the Spherical Mercator CRS (EPSG:3857)

Parameters

wfloat: West edge
sfloat: South edge
efloat: East edge
nfloat: North edge
zoomint: Level of detail
pathstr: Path to raster file to be written
sourcexyzservices.TileProvider object or str: [Optional. Default: Stamen Terrain web tiles] The tile source: web tile provider or path to local file. The web tile provider can be in the form of a xyzservices.TileProvider object or a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. For local file paths, the file is read with rasterio and all bands are loaded into the basemap. IMPORTANT: tiles are assumed to be in the Spherical Mercator projection (EPSG:3857), unless the crs keyword is specified.
llBoolean: [Optional. Default: False] If True, w, s, e, n are assumed to be lon/lat as opposed to Spherical Mercator.
waitint: [Optional. 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: [Optional. Default: 2] total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API.

Returns

imgndarray: Image as a 3D array of RGB values
extenttuple: Bounding box [minX, maxX, minY, maxY] of the returned image

contextily.bounds2img(w, s, e, n, zoom='auto', source=None, ll=False, wait=0, max_retries=2)¶

Take bounding box and zoom and return an image with all the tiles that compose the map and its Spherical Mercator extent.

Parameters

wfloat: West edge
sfloat: South edge
efloat: East edge
nfloat: North edge
zoomint: Level of detail
sourcexyzservices.TileProvider object or str: [Optional. Default: Stamen Terrain web tiles] The tile source: web tile provider or path to local file. The web tile provider can be in the form of a xyzservices.TileProvider object or a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. For local file paths, the file is read with rasterio and all bands are loaded into the basemap. IMPORTANT: tiles are assumed to be in the Spherical Mercator projection (EPSG:3857), unless the crs keyword is specified.
llBoolean: [Optional. Default: False] If True, w, s, e, n are assumed to be lon/lat as opposed to Spherical Mercator.
waitint: [Optional. 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: [Optional. Default: 2] total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API.

Returns

imgndarray: Image as a 3D array of RGB values
extenttuple: Bounding box [minX, maxX, minY, maxY] of the returned image

contextily.warp_tiles(img, extent, t_crs='EPSG:4326', resampling=Resampling.bilinear)¶

Reproject (warp) a Web Mercator basemap into any CRS on-the-fly

NOTE: this method works well with contextily’s bounds2img approach to: raster dimensions (h, w, b)

Parameters

imgndarray: Image as a 3D array (h, w, b) of RGB values (e.g. as returned from contextily.bounds2img)
extenttuple: Bounding box [minX, maxX, minY, maxY] of the returned image, expressed in Web Mercator (EPSG:3857)
t_crsstr/CRS: [Optional. Default=’EPSG:4326’] Target CRS, expressed in any format permitted by rasterio. Defaults to WGS84 (lon/lat)
resampling<enum ‘Resampling’>: [Optional. Default=Resampling.bilinear] Resampling method for executing warping, expressed as a rasterio.enums.Resampling method

Returns

imgndarray: Image as a 3D array (h, w, b) of RGB values (e.g. as returned from contextily.bounds2img)
exttuple: Bounding box [minX, maxX, minY, maxY] of the returned (warped) image

contextily.warp_img_transform(img, transform, s_crs, t_crs, resampling=Resampling.bilinear)¶

Reproject (warp) an img with a given transform and s_crs into a different t_crs

NOTE: this method works well with rasterio’s .read() approach to raster’s dimensions (b, h, w)

Parameters

imgndarray: Image as a 3D array (b, h, w) of RGB values (e.g. as returned from rasterio’s .read() method)
transformaffine.Affine: Transform of the input image as expressed by rasterio and the affine package
s_crsstr/CRS: Source CRS in which img is passed, expressed in any format permitted by rasterio.
t_crsstr/CRS: Target CRS, expressed in any format permitted by rasterio.
resampling<enum ‘Resampling’>: [Optional. Default=Resampling.bilinear] Resampling method for executing warping, expressed as a rasterio.enums.Resampling method

Returns

w_imgndarray: Warped image as a 3D array (b, h, w) of RGB values (e.g. as returned from rasterio’s .read() method)
w_transformaffine.Affine: Transform of the input image as expressed by rasterio and the affine package

contextily.howmany(w, s, e, n, zoom, verbose=True, ll=False)¶

Number of tiles required for a given bounding box and a zoom level

Parameters

wfloat: West edge
sfloat: South edge
efloat: East edge
nfloat: North edge
zoomint: Level of detail
verboseBoolean: [Optional. Default=True] If True, print short message with number of tiles and zoom.
llBoolean: [Optional. Default: False] If True, w, s, e, n are assumed to be lon/lat as opposed to Spherical Mercator.

Geocoding and plotting places¶

class contextily.Place(search, zoom=None, path=None, zoom_adjust=None, source=None, geocoder=<geopy.geocoders.nominatim.Nominatim object>)¶

Geocode a place by name and get its map.

This allows you to search for a name (e.g., city, street, country) and grab map and location data from the internet.

Parameters

searchstring: The location to be searched.
zoomint or None: [Optional. Default: None] The level of detail to include in the map. Higher levels mean more tiles and thus longer download time. If None, the zoom level will be automatically determined.
pathstr or None: [Optional. Default: None] Path to a raster file that will be created after getting the place map. If None, no raster file will be downloaded.
zoom_adjustint or None: [Optional. Default: None] The amount to adjust a chosen zoom level if it is chosen automatically.
sourcexyzservices.providers object or str: [Optional. Default: Stamen Terrain web tiles] The tile source: web tile provider or path to local file. The web tile provider can be in the form of a xyzservices.TileProvider object or a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. For local file paths, the file is read with rasterio and all bands are loaded into the basemap. IMPORTANT: tiles are assumed to be in the Spherical Mercator projection (EPSG:3857), unless the crs keyword is specified.
geocodergeopy.geocoders: [Optional. Default: geopy.geocoders.Nominatim()] Geocoder method to process search

Attributes

geocodegeopy object: The result of calling geopy.geocoders.Nominatim with search as input.
sfloat: The southern bbox edge.
nfloat: The northern bbox edge.
efloat: The eastern bbox edge.
wfloat: The western bbox edge.
imndarray: The image corresponding to the map of search.
bboxlist: The bounding box of the returned image, expressed in lon/lat, with the following order: [minX, minY, maxX, maxY]
bbox_maptuple: The bounding box of the returned image, expressed in Web Mercator, with the following order: [minX, minY, maxX, maxY]

Methods

plot([ax, zoom, interpolation, attribution])

Plot a Place object

Place.plot(ax=None, zoom='auto', interpolation='bilinear', attribution=None)¶

Plot a Place object …

Parameters

axAxesSubplot: Matplotlib axis with x_lim and y_lim set in Web Mercator (EPSG=3857). If not provided, a new 12x12 figure will be set and the name of the place will be added as title
zoomint/’auto’: [Optional. Default=’auto’] Level of detail for the basemap. If ‘auto’, if calculates it automatically. Ignored if source is a local file.
interpolationstr: [Optional. Default=’bilinear’] Interpolation algorithm to be passed to imshow. See matplotlib.pyplot.imshow for further details.
attributionstr: [Optional. Defaults to attribution specified by the source of the map tiles] Text to be added at the bottom of the axis. This defaults to the attribution of the provider specified in source if available. Specify False to not automatically add an attribution, or a string to pass a custom attribution.

Returns

axAxesSubplot: Matplotlib axis with x_lim and y_lim set in Web Mercator (EPSG=3857) containing the basemap

Examples

>>> lvl = ctx.Place('Liverpool')
>>> lvl.plot()

contextily.plot_map(place, bbox=None, title=None, ax=None, axis_off=True, latlon=True, attribution=None)¶

Plot a map of the given place.

Parameters

placeinstance of Place or ndarray: The map to plot. If an ndarray, this must be an image corresponding to a map. If an instance of Place, the extent of the image and name will be inferred from the bounding box.
axinstance of matplotlib Axes object or None: The axis on which to plot. If None, one will be created.
axis_offbool: Whether to turn off the axis border and ticks before plotting.
attributionstr: [Optional. Default to standard ATTRIBUTION] Text to be added at the bottom of the axis.

Returns

axinstance of matplotlib Axes object or None: The axis on the map is plotted.

OSMNX & Cenpy