{"id":1794,"library":"xyzservices","title":"XYZ Services Tiles Providers","description":"xyzservices provides a comprehensive collection of XYZ tile providers for mapping applications, offering easy access to various base maps and overlays. It helps users integrate tile services into geospatial libraries like Folium, Leaflet, and Contextily. The current version is 2026.3.0, and it maintains a rapid release cadence, typically monthly or bi-monthly, to reflect changes in upstream tile providers.","status":"active","version":"2026.3.0","language":"en","source_language":"en","source_url":"https://github.com/geopandas/xyzservices","tags":["GIS","mapping","geospatial","tiles","openstreetmap","providers"],"install":[{"cmd":"pip install xyzservices","lang":"bash","label":"Install xyzservices"}],"dependencies":[],"imports":[{"symbol":"providers","correct":"import xyzservices.providers as xyz"},{"note":"TileProvider is directly exposed at the top level since 2023.x versions; avoid internal module paths.","wrong":"from xyzservices.lib import TileProvider","symbol":"TileProvider","correct":"from xyzservices import TileProvider"}],"quickstart":{"code":"import xyzservices.providers as xyz\n\n# Access a common, free-to-use provider\nprovider = xyz.CartoDB.Positron\n\nprint(f\"Provider Name: {provider.name}\")\nprint(f\"URL Template: {provider.url}\")\nprint(f\"Attribution: {provider.attribution}\")\nprint(f\"Minimum Zoom: {provider.min_zoom}, Maximum Zoom: {provider.max_zoom}\")\n\n# Example of a provider that often requires an API key\n# API_KEY = os.environ.get('MAPTILER_API_KEY', '')\n# if API_KEY:\n#     maptiler_provider = xyz.MapTiler.Basic.format(apiKey=API_KEY)\n#     print(f\"\\nMapTiler Basic URL (with key): {maptiler_provider.url}\")\n# else:\n#     print(\"\\nNote: MAPTILER_API_KEY environment variable not set. MapTiler providers often require an API key.\")","lang":"python","description":"This quickstart demonstrates how to import the providers, access a specific tile provider (CartoDB Positron), and retrieve its basic properties like URL and attribution. Some providers may require an API key, which can be formatted into the URL template."},"warnings":[{"fix":"Migrate to `Stadia.Stamen*` variants, e.g., `xyz.Stadia.StamenToner` instead of `xyz.Stamen.Toner`.","message":"Stamen tile providers have been removed due to upstream deprecation. Direct usage of `xyz.Stamen.*` will fail.","severity":"breaking","affected_versions":">=2023.10.1"},{"fix":"Update `HEREv2` usage to `xyz.HERE` and ensure you are using the v3 API schema. Refer to HERE documentation for specific parameter changes.","message":"HERE API v2 has been removed, and the `HEREv3` provider has been renamed to `HERE`. Users relying on older HERE services will experience broken functionality.","severity":"breaking","affected_versions":">=2025.10.0"},{"fix":"Regularly check the `xyzservices` documentation or GitHub releases for updates on provider status. Consider using more stable, well-maintained providers for production applications. The `is_broken` attribute can be checked on providers.","message":"Many providers, particularly those from smaller or experimental services, can become broken or change URLs without notice. This can lead to `KeyError` if a provider is removed, or broken maps if the URL changes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you have obtained a valid API key for the respective service. Pass the key using the `.format(apiKey=YOUR_KEY)` method on the provider object before use.","message":"Providers requiring API keys (e.g., MapTiler, ThunderForest, HERE) will fail if the key is missing or incorrectly formatted. The `.format()` method is used to inject keys into the URL.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}