{"id":5886,"library":"contextily","title":"Contextily","description":"Contextily is a Python library (v1.7.0) for adding context geo-tiles as basemaps to Matplotlib figures or saving them as geospatial raster files. It is actively developed, with minor releases every few months, and is tightly integrated with GeoPandas and the `xyzservices` package for tile providers.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/geopandas/contextily","tags":["geospatial","mapping","visualization","geopandas","tiles","basemap"],"install":[{"cmd":"pip install contextily","lang":"bash","label":"PyPI (recommended)"},{"cmd":"conda install contextily --channel conda-forge","lang":"bash","label":"Conda (for geospatial stack)"}],"dependencies":[{"reason":"Crucial for integrating basemaps with geospatial vector data plotting.","package":"geopandas"},{"reason":"Used for generating plots and providing the `AxesSubplot` object for basemap integration.","package":"matplotlib"},{"reason":"Provides the backend for managing and accessing various web tile providers.","package":"xyzservices"},{"reason":"Used for reading local raster files and for warping/reprojection operations.","package":"rasterio"}],"imports":[{"symbol":"add_basemap","correct":"import contextily as cx\ncx.add_basemap(ax, ...)"},{"symbol":"providers","correct":"import contextily as cx\ncx.providers.OpenStreetMap.Mapnik"}],"quickstart":{"code":"import geopandas\nimport contextily as cx\nimport matplotlib.pyplot as plt\n\n# Load a sample GeoDataFrame\ndf = geopandas.read_file(geopandas.datasets.get_path(\"nybb\"))\n\n# Ensure the data is in Web Mercator (EPSG:3857) or set the crs parameter in add_basemap\ndf_wm = df.to_crs(epsg=3857)\n\n# Plot the GeoDataFrame\nfig, ax = plt.subplots(figsize=(10, 10))\ndf_wm.plot(ax=ax, alpha=0.5, edgecolor=\"k\", facecolor=\"cyan\")\n\n# Add a basemap\ncx.add_basemap(ax, crs=df_wm.crs)\n\n# Optional: Customize the title and display\nax.set_title(\"NYC Boroughs with Contextual Basemap\")\nplt.tight_layout()\nplt.show()","lang":"python","description":"This quickstart demonstrates how to use `contextily` with `geopandas` to add a web tile basemap to a geospatial plot. It loads the NYC boroughs dataset, reprojects it to Web Mercator (EPSG:3857) which is standard for web tiles, plots the data, and then overlays a basemap using `cx.add_basemap()`."},"warnings":[{"fix":"Use `contextily.add_basemap()` instead, which offers more flexibility and is the current recommended approach.","message":"The `plot_map` function was deprecated in previous versions and has been entirely removed in `contextily` v1.7.0.","severity":"breaking","affected_versions":">=1.7.0"},{"fix":"If you need a specific tile provider, explicitly specify it using the `source` parameter in `add_basemap`, e.g., `source=cx.providers.CartoDB.Voyager`. For Stamen, you might need an API key and to specify the full URL.","message":"The default tile provider changed from Stamen to OpenStreetMap Humanitarian in v1.4.0. This change was due to Stamen moving under Stadia and requiring an API key. Users expecting Stamen tiles will now get OpenStreetMap Humanitarian by default.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Upgrade your Python environment to version 3.10 or higher.","message":"Contextily now requires Python 3.10 or newer. Older Python versions are no longer supported.","severity":"breaking","affected_versions":">=1.7.0"},{"fix":"Before `cx.add_basemap(ax, ...)`, ensure your GeoDataFrame is reprojected (`gdf.to_crs(epsg=3857).plot(ax=ax)`) or explicitly pass `crs=gdf.crs` to `add_basemap`.","message":"Web map tiles are typically in Web Mercator (EPSG:3857). If your data is in a different Coordinate Reference System (CRS), you must either reproject your data to EPSG:3857 before plotting or pass your data's CRS to `cx.add_basemap` using the `crs` parameter for on-the-fly warping. Not doing so can lead to misaligned basemaps.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}