{"id":10294,"library":"tilemapbase","title":"TileMapBase","description":"TileMapBase is a Python library that enables the use of OpenStreetMap and other WMTS tiles as basemaps within Matplotlib figures. It simplifies fetching, caching, and rendering geographical tiles, allowing users to overlay their data on real-world maps. Currently at version 0.4.7, it is actively maintained with periodic updates.","status":"active","version":"0.4.7","language":"en","source_language":"en","source_url":"https://github.com/MatthewDaws/TileMapBase","tags":["mapping","openstreetmap","matplotlib","tiles","geospatial"],"install":[{"cmd":"pip install tilemapbase","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for plotting and rendering maps.","package":"matplotlib","optional":false},{"reason":"Used for image processing and handling of tile data.","package":"Pillow","optional":false},{"reason":"For making HTTP requests to fetch map tiles from servers.","package":"requests","optional":false}],"imports":[{"note":"Crucial for global configuration, cache setup, and user agent.","symbol":"init","correct":"import tilemapbase\ntilemapbase.init(...)"},{"note":"Manages the Matplotlib axes projection and extent for the map.","symbol":"PlottingContext","correct":"from tilemapbase.plotting import PlottingContext"},{"note":"Function to add map tiles to a Matplotlib axes.","symbol":"add_tile_wmts","correct":"from tilemapbase.plotting import add_tile_wmts"},{"note":"Moved to top-level `tilemapbase` module in version 0.4.0+. Old import path will raise AttributeError.","wrong":"from tilemapbase.transform import map_to_pixels","symbol":"map_to_pixels","correct":"import tilemapbase\ntilemapbase.map_to_pixels(...)"},{"note":"Matplotlib transform for plotting data in WGS84 (lon/lat) coordinates on a projected map.","symbol":"crs_geographic","correct":"import tilemapbase\nax.plot(..., transform=tilemapbase.crs_geographic)"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nimport tilemapbase\n\n# Crucial initialization step for tilemapbase. Set a user_agent to avoid 403 errors.\n# python_accelerated=True can speed up rendering if numba is installed.\ntilemapbase.init(python_accelerated=True, user_agent=\"my-tilemapbase-app\")\n\n# Define the map extent [lon_min, lon_max, lat_min, lat_max]\nextent = [-0.20, 0.05, 51.45, 51.55] # Example: Central London\n\nfig, ax = plt.subplots(figsize=(10, 10), dpi=100)\nax.set_xlabel(\"Longitude\")\nax.set_ylabel(\"Latitude\")\nax.set_title(\"London with TileMapBase\")\n\n# Create a PlottingContext. This sets up the matplotlib axes for the map projection.\n# 'merc' is the standard projection for web maps.\nplot_context = tilemapbase.plotting.PlottingContext(\n    extent,\n    ax=ax,\n    proj=\"merc\"\n)\n\n# Add OpenStreetMap tiles to the axes\ntilemapbase.plotting.add_tile_wmts(\n    ax, url=tilemapbase.get_providers_as_dict()[\"OpenStreetMap\"], zoom=13\n)\n\n# Set axes limits based on the PlottingContext's projected extent\nax.set_xlim(plot_context.x_min, plot_context.x_max)\nax.set_ylim(plot_context.y_min, plot_context.y_max)\nax.set_aspect(plot_context.get_aspect())\n\n# Example: Overlay a point (London Eye) in geographic coordinates\nlondon_eye_lon, london_eye_lat = -0.1106, 51.5033\nax.plot(\n    london_eye_lon, london_eye_lat,\n    'o', color='red', markersize=8,\n    transform=tilemapbase.crs_geographic, # Crucial: plot in geographic coordinates\n    label=\"London Eye\"\n)\nax.legend()\n\nplt.show()","lang":"python","description":"This quickstart demonstrates how to initialize TileMapBase, define a geographical extent, create a Matplotlib figure and axes, add OpenStreetMap tiles using PlottingContext, and overlay a data point (London Eye) correctly using the `tilemapbase.crs_geographic` transform."},"warnings":[{"fix":"Always call `tilemapbase.init()` at the start of your script and provide a unique `user_agent` string, e.g., `tilemapbase.init(user_agent=\"my-app-name/1.0\")`.","message":"Failing to call `tilemapbase.init()` or not providing a `user_agent` string can lead to HTTP 403 (Forbidden) errors from tile servers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update your imports: change `from tilemapbase.transform import ...` to `import tilemapbase` and then use `tilemapbase.map_to_pixels(...)` or `tilemapbase.pixels_to_map(...)`.","message":"The `map_to_pixels` and `pixels_to_map` functions were moved from `tilemapbase.transform` directly to the `tilemapbase` top-level module in version 0.4.0.","severity":"breaking","affected_versions":"0.4.0+"},{"fix":"If your data is in WGS84 (latitude/longitude), use `transform=tilemapbase.crs_geographic` with Matplotlib plotting functions (e.g., `ax.plot(lon, lat, transform=tilemapbase.crs_geographic)`).","message":"When overlaying your own data (e.g., points, lines) on a TileMapBase map, you must correctly handle coordinate systems. Matplotlib's default coordinates won't match the projected map tiles.","severity":"gotcha","affected_versions":"All versions"},{"fix":"TileMapBase uses `cachecontrol` for caching, which helps. Ensure your `user_agent` is identifiable and respect providers' usage policies. For heavy usage, consider self-hosting tiles or using a commercial provider with an API key.","message":"Aggressive tile fetching or ignoring tile server terms of service can lead to IP bans or temporary blocks from tile providers.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Call `tilemapbase.init()` with a `user_agent` parameter at the start of your script, e.g., `tilemapbase.init(user_agent=\"MyPythonApp/1.0\")`.","cause":"Most tile servers require a User-Agent HTTP header to identify the client, or they block requests to prevent abuse.","error":"requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: ..."},{"fix":"Remove the `from tilemapbase.transform import ...` statement. The functions are now directly available under the `tilemapbase` module: use `tilemapbase.map_to_pixels(...)` or `tilemapbase.pixels_to_map(...)` after `import tilemapbase`.","cause":"This error typically occurs in `tilemapbase` versions 0.4.0 and later when trying to import `map_to_pixels` or `pixels_to_map` from the deprecated `tilemapbase.transform` module.","error":"AttributeError: module 'tilemapbase' has no attribute 'transform'"},{"fix":"When plotting your data (e.g., `ax.plot`, `ax.scatter`), specify the transform to tell Matplotlib your data's coordinate system: `ax.plot(lon, lat, transform=tilemapbase.crs_geographic)`.","cause":"The Matplotlib axes created by `PlottingContext` are in a projected coordinate system (e.g., Mercator), but your data is likely in geographic (latitude/longitude) coordinates without proper transformation.","error":"My plotted data appears in the wrong place or is heavily distorted on the map."},{"fix":"Ensure the user running the script has write permissions to the cache directory. If specifying a custom cache path in `tilemapbase.init(cache_dir=...)`, make sure the directory exists and is writable, or `tilemapbase` will attempt to create it (which might fail due to permissions).","cause":"This can occur if the default tile cache directory is inaccessible or if a custom cache path is specified incorrectly.","error":"FileNotFoundError: [Errno 2] No such file or directory: '.../tile_cache'"}]}