{"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":"python","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":[{"wrong":"import tilemapbase","symbol":"tilemapbase","correct":"import tilemapbase"}],"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,"search_vec":"'0.4.7':44 'activ':47 'allow':30 'basemap':18 'cach':25 'current':41 'data':35 'enabl':8 'fetch':24 'figur':21 'geograph':28 'geospati':56 'librari':6 'maintain':48 'map':40,52 'matplotlib':20,54 'openstreetmap':12,53 'overlay':33 'period':50 'python':5 'real':38 'real-world':37 'render':27 'simplifi':23 'tile':16,29,55 'tilemapbas':1,2 'updat':51 'use':10 'user':31 'version':43 'within':19 'wmts':15 'world':39","created_at":"2026-04-17T01:23:22.813893+00:00","updated_at":"2026-04-17T01:23:22.813893+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.7","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/MatthewDaws/TileMapBase","docs":null,"changelog":null,"pypi":"https://pypi.org/project/tilemapbase/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","observability","web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}