From dcff7194e8e056c04e1d119762c011f6152ef26d Mon Sep 17 00:00:00 2001
From: Greg Lucas <greg.m.lucas@gmail.com>
Date: Wed, 11 Oct 2023 19:38:39 -0600
Subject: [PATCH] ENH: Add Stadia Maps image tile server class

The Stamen tiles are now being served by Stadia Maps. Stadia Maps
requires an API key, and has different naming convention for their
tiles, so create a new class to interact with the new server.
---
 docs/source/reference/io.rst |  1 +
 lib/cartopy/io/img_tiles.py  | 54 ++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/docs/source/reference/io.rst b/docs/source/reference/io.rst
index 1eebec5d7..72b69b756 100644
--- a/docs/source/reference/io.rst
+++ b/docs/source/reference/io.rst
@@ -63,6 +63,7 @@ automatically load the proper tile and resolution depending on the desired domai
     MapboxTiles
     OrdnanceSurvey
     QuadtreeTiles
+    StadiaMapsTiles
     Stamen
 
 Open Geospatial Consortium (OGC)
diff --git a/lib/cartopy/io/img_tiles.py b/lib/cartopy/io/img_tiles.py
index 76b939d65..7b46cc8a9 100644
--- a/lib/cartopy/io/img_tiles.py
+++ b/lib/cartopy/io/img_tiles.py
@@ -320,6 +320,57 @@ def _image_url(self, tile):
         return f'https://a.tile.openstreetmap.org/{z}/{x}/{y}.png'
 
 
+class StadiaMapsTiles(GoogleWTS):
+    """
+    Retrieves tiles from stadiamaps.com.
+
+    For a full reference on the styles available please see
+    https://docs.stadiamaps.com/themes/. A few of the specific styles
+    that are made available are ``alidade_smooth``, ``stamen_terrain`` and
+    ``osm_bright``.
+
+    Using the Stadia Maps API requires including an attribution. Please see
+    https://docs.stadiamaps.com/attribution/ for details.
+
+    For most styles that means including the following attribution:
+
+    `© Stadia Maps <https://www.stadiamaps.com/>`_
+    `© OpenMapTiles <https://openmaptiles.org/>`_
+    `© OpenStreetMap contributors <https://www.openstreetmap.org/about/>`_
+
+    with Stamen styles *additionally* requiring the following attribution:
+
+    `© Stamen Design <https://stamen.com/>`_
+
+    Parameters
+    ----------
+    apikey : str, required
+        The authentication key provided by Stadia Maps to query their APIs
+    style : str, optional
+        Name of the desired style. Defaults to ``alidade_smooth``.
+        See https://docs.stadiamaps.com/themes/ for a full list of styles.
+    cache : bool or str, optional
+        If True, the default cache directory is used. If False, no cache is
+        used. If a string, the string is used as the path to the cache.
+    """
+
+    def __init__(self, apikey, style='alidade_smooth', cache=False):
+        super().__init__(cache=cache)
+        self.apikey = apikey
+        if style in ("alidade_satellite", "stamen_watercolor"):
+            # Known styles that have the jpg extension
+            self.extension = "jpg"
+        else:
+            self.extension = "png"
+        self.style = style
+
+    def _image_url(self, tile):
+        x, y, z = tile
+        return ("http://tiles.stadiamaps.com/tiles/"
+                f"{self.style}/{z}/{x}/{y}.{self.extension}"
+                f"?api_key={self.apikey}")
+
+
 class Stamen(GoogleWTS):
     """
     Retrieves tiles from maps.stamen.com. Styles include
@@ -351,6 +402,9 @@ class Stamen(GoogleWTS):
 
     def __init__(self, style='toner',
                  desired_tile_form=None, cache=False):
+        warnings.warn("The Stamen styles are no longer served by Stamen and "
+                      "are now served by Stadia Maps. Please use the "
+                      "StadiaMapsTiles class instead.")
 
         # preset layer configuration
         layer_config = {