### Install xyzservices

Source: https://xyzservices.readthedocs.io/en/stable/index.html

Installation commands for conda and pip environments.

```bash
conda install xyzservices -c conda-forge
```

```bash
pip install xyzservices
```

--------------------------------

### Install xyzservices with Pip

Source: https://xyzservices.readthedocs.io/en/stable/_sources/index.md.txt

Install the xyzservices package using the pip package manager.

```shell
pip install xyzservices
```

--------------------------------

### Exploring provider objects

Source: https://xyzservices.readthedocs.io/en/stable/_sources/introduction.ipynb.txt

Examples of accessing the provider registry and inspecting specific provider details.

```python
xyz
```

```python
xyz.OpenStreetMap
```

```python
type(xyz.OpenStreetMap.Mapnik)
```

```python
xyz.OpenStreetMap.Mapnik
```

--------------------------------

### Install xyzservices with Conda

Source: https://xyzservices.readthedocs.io/en/stable/_sources/index.md.txt

Install the xyzservices package using the conda package manager from the conda-forge channel.

```shell
conda install xyzservices -c conda-forge
```

--------------------------------

### GeoportailFrance.Installations_Pv_Sol Tile Provider

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Configuration for the Geoportail France Installations Pv Sol tile provider. Requires an API key.

```python
GeoportailFrance.Installations_Pv_Sol = xyzservices.TileProvider(
    name="GeoportailFrance.Installations_Pv_Sol",
    url="https://data.geopf.fr/wmts?SERVICE=WMTS&VERSION=1.0.0&REQUEST=GetTile&STYLE={style}&TILEMATRIXSET={TileMatrixSet}&FORMAT={format}&LAYER={variant}&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}",
    html_attribution="Geoportail France",
    attribution="Geoportail France",
    bounds=[[41.3252, -5.15047], [51.0991, 9.57054]],
    min_zoom=6,
    max_zoom=16,
    format="image/png",
    style="INSTALLATIONS.PV.SOL",
    variant="INSTALLATIONS.PV.SOL",
    TileMatrixSet="PM_6_16",
    apikey="your_api_key_here"
)
```

--------------------------------

### Providers JSON Structure

Source: https://xyzservices.readthedocs.io/en/stable/_sources/api.rst.txt

Example schema for the providers.json file, illustrating both single provider definitions and grouped provider bunches.

```json
{
   "single_provider_name": {
      "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
      "max_zoom": 19,
      "attribution": "(C) OpenStreetMap contributors",
      "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
      "name": "OpenStreetMap.Mapnik"
   },
   "provider_bunch_name": {
      "first_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap contributors",
            "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
            "name": "OpenStreetMap.Mapnik"
      },
      "second_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?access-token={accessToken}",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap contributors",
            "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
            "name": "OpenStreetMap.Mapnik",
            "accessToken": "<insert your access token here>"
      }
   }
}
```

--------------------------------

### GeoportailFrance.Installations_Pv_Sol

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Provides access to Geoportail France's solar photovoltaic installations data tiles. Requires an API key.

```APIDOC
## GeoportailFrance.Installations_Pv_Sol

### Description
Provides access to Geoportail France's solar photovoltaic installations data tiles.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts?SERVICE=WMTS&VERSION=1.0.0&REQUEST=GetTile&STYLE={style}&TILEMATRIXSET={TileMatrixSet}&FORMAT={format}&LAYER={variant}&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}

### Parameters
#### Query Parameters
- **SERVICE** (string) - Required - WMTS
- **VERSION** (string) - Required - 1.0.0
- **REQUEST** (string) - Required - GetTile
- **STYLE** (string) - Required - INSTALLATIONS.PV.SOL
- **TILEMATRIXSET** (string) - Required - PM_6_16
- **FORMAT** (string) - Required - image/png
- **LAYER** (string) - Required - INSTALLATIONS.PV.SOL
- **TILEMATRIX** (string) - Required - {z}
- **TILEROW** (string) - Required - {y}
- **TILECOL** (string) - Required - {x}
- **apikey** (string) - Required - your_api_key_here

### Bounds
[[41.3252, -5.15047], [51.0991, 9.57054]]

### Zoom Levels
- Min Zoom: 6
- Max Zoom: 16

### Attribution
Geoportail France
```

--------------------------------

### Add OpenWeatherMap Basemap with API Key using Contextily

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

This example shows how to add an OpenWeatherMap basemap to a matplotlib axes using the contextily library, providing the necessary API key.

```python
contextily.add_basemap(ax, source=xyz.OpenWeatherMap.Clouds(apiKey="my-private-api-key"))

```

--------------------------------

### Create TileProvider from QMS

Source: https://xyzservices.readthedocs.io/en/stable/api.html

Use the `TileProvider.from_qms()` class method to create a TileProvider object from the Quick Map Services open catalog by specifying the service name.

```python
>>> from xyzservices.lib import TileProvider
>>> provider = TileProvider.from_qms("OpenTopoMap")
```

--------------------------------

### Create Custom TileProvider

Source: https://xyzservices.readthedocs.io/en/stable/api.html

Instantiate a TileProvider object by passing attributes as a dictionary or directly. Ensure 'name', 'url', and 'attribution' are always specified. Use '<insert your access token here>' for token placeholders.

```python
>>> public_provider = TileProvider(
...     name="My public tiles",
...     url="https://myserver.com/tiles/{z}/{x}/{y}.png",
...     attribution="(C) xyzservices",
... )
```

```python
>>> private_provider = TileProvider(
...    {
...        "url": "https://myserver.com/tiles/{z}/{x}/{y}.png?apikey={accessToken}",
...        "attribution": "(C) xyzservices",
...        "accessToken": "<insert your access token here>",
...        "name": "my_private_provider",
...    }
... )
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile from the Geoportail France WMTS service.

```APIDOC
## GET https://data.geopf.fr/wmts

### Description
Retrieves a specific map tile based on the provided layer variant, style, and coordinate parameters.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts?SERVICE=WMTS&VERSION=1.0.0&REQUEST=GetTile&STYLE={style}&TILEMATRIXSET={TileMatrixSet}&FORMAT={format}&LAYER={variant}&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}

### Parameters
#### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style identifier (e.g., 'CORINE Land Cover')
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier (e.g., 'PM_0_12')
- **FORMAT** (string) - Required - The image format (e.g., 'image/png')
- **LAYER** (string) - Required - The layer variant identifier
- **TILEMATRIX** (string) - Required - The zoom level (z)
- **TILEROW** (string) - Required - The row coordinate (y)
- **TILECOL** (string) - Required - The column coordinate (x)

### Response
#### Success Response (200)
- **Content-Type** (image/png) - The requested map tile image.
```

--------------------------------

### GET HERE Map Tile Provider

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves base map tiles from HERE services.

```APIDOC
## GET https://maps.hereapi.com/v3/base/mc/{z}/{x}/{y}/{format}

### Description
Fetches base map tiles from HERE with specific styles and configurations.

### Method
GET

### Endpoint
https://maps.hereapi.com/v3/base/mc/{z}/{x}/{y}/{format}?style={variant}&size={size}&apiKey={apiKey}&lg={language}

### Parameters
#### Path Parameters
- **z** (integer) - Required - Zoom level.
- **x** (integer) - Required - X coordinate.
- **y** (integer) - Required - Y coordinate.
- **format** (string) - Required - Image format (e.g., png8).

#### Query Parameters
- **style** (string) - Required - The map variant style (e.g., explore.day, lite.day, logistics.day, topo.day).
- **size** (integer) - Required - Tile size (e.g., 256).
- **apiKey** (string) - Required - The API key for HERE authentication.
- **lg** (string) - Optional - Language code (e.g., eng).
```

--------------------------------

### Compress Provider Sources Command

Source: https://xyzservices.readthedocs.io/en/stable/contributing.html

After updating provider sources, compress them by executing `make compress` from the repository root. Navigate to the `xyzservices` directory first.

```bash
cd xyzservices
make compress
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieve CORINE Land Cover tiles using the WMTS service.

```APIDOC
## GET /wmts

### Description
This endpoint allows you to retrieve CORINE Land Cover tiles from the Geoportail France WMTS service. You can specify various parameters to customize the tile request.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Parameters
#### Query Parameters
- **SERVICE** (string) - Required - The WMTS service name.
- **VERSION** (string) - Required - The WMTS version.
- **REQUEST** (string) - Required - The WMTS request type (e.g., GetTile).
- **STYLE** (string) - Required - The style for the layer (e.g., "CORINE Land Cover").
- **TILEMATRIXSET** (string) - Required - The TileMatrixSet identifier (e.g., "PM_0_12").
- **FORMAT** (string) - Required - The image format (e.g., "image/png").
- **LAYER** (string) - Required - The layer variant (e.g., "LANDCOVER.GRID.CLC06_FR").
- **TILEMATRIX** (string) - Required - The zoom level (z).
- **TILEROW** (string) - Required - The tile row (y).
- **TILECOL** (string) - Required - The tile column (x).
- **apikey** (string) - Required - Your API key.

### Request Example
```
https://data.geopf.fr/wmts?SERVICE=WMTS&VERSION=1.0.0&REQUEST=GetTile&STYLE=CORINE Land Cover&TILEMATRIXSET=PM_0_12&FORMAT=image/png&LAYER=LANDCOVER.GRID.CLC06_FR&TILEMATRIX=8&TILEROW=123&TILECOL=456&apikey=your_api_key_here
```

### Response
#### Success Response (200)
- **Image** (image/png) - The requested map tile.

#### Response Example
(Binary image data)
```

--------------------------------

### Load a provider from QMS

Source: https://xyzservices.readthedocs.io/en/stable/_sources/introduction.ipynb.txt

Fetches a tile provider configuration from the Quick Map Services database. The provider name must match the entry in the QMS database exactly.

```python
from xyzservices import TileProvider

qms_provider = TileProvider.from_qms("OpenTopoMap")
qms_provider
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a specific map tile from the Geoportail France WMTS service.

```APIDOC
## GET /wmts

### Description
Retrieves a map tile for a specific geographical layer, zoom level, and coordinate set.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style of the map (e.g., 'normal')
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier (e.g., 'PM_6_16')
- **FORMAT** (string) - Required - The image format (e.g., 'image/png')
- **LAYER** (string) - Required - The variant/layer identifier
- **TILEMATRIX** (integer) - Required - The zoom level (z)
- **TILEROW** (integer) - Required - The row coordinate (y)
- **TILECOL** (integer) - Required - The column coordinate (x)

### Response
#### Success Response (200)
- **image/png** (binary) - The requested map tile image.
```

--------------------------------

### Accessing xyzservices provider objects

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Use this command to initiate exploration of the available provider objects.

```python
xyz
```

--------------------------------

### GET /tiles/{variant}/{z}/{x}/{y}.{ext}

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves satellite map tiles.

```APIDOC
## GET /tiles/{variant}/{z}/{x}/{y}.{ext}

### Description
Retrieves a satellite map tile.

### Method
GET

### Endpoint
https://api.maptiler.com/tiles/{variant}/{z}/{x}/{y}.{ext}?key={key}

### Parameters
#### Path Parameters
- **variant** (string) - Required - The map style variant (e.g., satellite-v2)
- **z** (integer) - Required - Zoom level
- **x** (integer) - Required - X coordinate
- **y** (integer) - Required - Y coordinate
- **ext** (string) - Required - File extension (e.g., jpg)

#### Query Parameters
- **key** (string) - Required - API access key
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile for a specific geographic layer from the Geoportail France service.

```APIDOC
## GET /wmts

### Description
Retrieves a map tile from the Geoportail France WMTS service based on the provided layer variant and coordinates.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Parameters
#### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style of the layer (e.g., 'normal', 'SCOT_TRAME_VERTE_BLEUE')
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier (e.g., 'PM_10_16')
- **FORMAT** (string) - Required - The image format (e.g., 'image/png', 'image/jpeg')
- **LAYER** (string) - Required - The variant/layer name
- **TILEMATRIX** (integer) - Required - The zoom level (z)
- **TILEROW** (integer) - Required - The row coordinate (y)
- **TILECOL** (integer) - Required - The column coordinate (x)

### Response
#### Success Response (200)
- **Content-Type** (image) - Returns the requested map tile image.
```

--------------------------------

### TileProvider Methods

Source: https://xyzservices.readthedocs.io/en/stable/api.html

Methods available for TileProvider objects, including building URLs, creating from QMS, and checking token requirements.

```APIDOC
## TileProvider Methods

### `build_url`

Build the URL of tiles from the `TileProvider` object. Can return URL with placeholders or the final tile URL.

#### Parameters
- **x** (int, optional) - Tile number.
- **y** (int, optional) - Tile number.
- **z** (int, optional) - Tile number.
- **scale_factor** (str, optional) - Scale factor (e.g., "@2x"). Use "{r}" to keep a placeholder.
- **fill_subdomain** (bool, optional, default True) - If True, fills subdomain placeholder. If False, leaves `{s}`.
- **kwargs** - Other potential attributes updating the `TileProvider`.

#### Returns
- **url** (str) - Formatted URL.

#### Examples
```python
>>> import xyzservices.providers as xyz
>>> xyz.CartoDB.DarkMatter.build_url()
'https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png'
>>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5)
'https://a.basemaps.cartocdn.com/dark_all/5/9/11.png'
>>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5, scale_factor="@2x")
'https://a.basemaps.cartocdn.com/dark_all/5/9/11@2x.png'
>>> xyz.MapBox.build_url(accessToken="my_token")
'https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/{z}/{x}/{y}?access_token=my_token'
```

### `from_qms`

Creates a `TileProvider` object based on the definition from the Quick Map Services open catalog.

#### Parameters
- **name** (str) - Service name.

#### Returns
- `TileProvider` object.

#### Example
```python
>>> from xyzservices.lib import TileProvider
>>> provider = TileProvider.from_qms("OpenTopoMap")
```

### `requires_token`

Returns `True` if the TileProvider requires an access token to fetch tiles. This is determined by the presence of placeholder strings like `"<insert your access token here>"` in the provider's attributes.

#### Returns
- **bool** - True if a token is required, False otherwise.

#### Examples
```python
>>> import xyzservices.providers as xyz
>>> xyz.MapBox.requires_token()
True
>>> xyz.CartoDB.Positron.requires_token()
False
```

#### Overriding Token Attributes
Token attributes can be overridden directly.
```python
>>> xyz.OpenWeatherMap.Clouds["apiKey"] = "my-private-api-key"
```
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile for a specific layer from the Geoportail France WMTS service.

```APIDOC
## GET https://data.geopf.fr/wmts

### Description
Retrieves a specific map tile based on the provided layer variant, zoom level, and tile coordinates.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style of the layer (e.g., 'normal')
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier
- **FORMAT** (string) - Required - The image format (e.g., 'image/png', 'image/jpeg')
- **LAYER** (string) - Required - The variant identifier of the layer
- **TILEMATRIX** (integer) - Required - The zoom level (z)
- **TILEROW** (integer) - Required - The row coordinate (y)
- **TILECOL** (integer) - Required - The column coordinate (x)
- **apikey** (string) - Required - Your Geoportail API key

### Response
#### Success Response (200)
- **Content-Type** (image/png or image/jpeg) - The requested map tile image.
```

--------------------------------

### Configure HERE and HEREv3 providers

Source: https://xyzservices.readthedocs.io/en/stable/registration.html

Use API keys for HEREv3 or legacy app credentials for HERE providers.

```python
# Overriding the attribute will alter the existing object
xyz.HEREv3.terrainDay["apiKey"] = "my-private-api-key"

# Calling the object will return a copy
xyz.HEREv3.terrainDay(apiKey="my-private-api-key")
```

```python
xyz.HERE.terrainDay(app_id="my-private-app-id", app_code="my-app-code")
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile for a specific layer, zoom level, and coordinate set.

```APIDOC
## GET /wmts

### Description
Fetches a map tile from the Geoportail France WMTS service based on the specified layer variant and tile coordinates.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Parameters
#### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style of the layer (e.g., 'normal', 'nolegend')
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier
- **FORMAT** (string) - Required - The image format (e.g., 'image/png', 'image/jpeg')
- **LAYER** (string) - Required - The layer variant identifier
- **TILEMATRIX** (integer) - Required - The zoom level (z)
- **TILEROW** (integer) - Required - The tile row (y)
- **TILECOL** (integer) - Required - The tile column (x)
- **apikey** (string) - Required - Your API key for authentication

### Response
#### Success Response (200)
- **image** (binary) - The requested map tile image.
```

--------------------------------

### Specifying Options for a Provider

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Demonstrates how to specify additional options for a TileProvider, such as an API key, by calling the provider object or overriding its attributes.

```APIDOC
## Specifying Options for a Provider

Some providers require additional information, such as an API access key. This can be specified by calling the provider object. Any keyword specified will override the default value in the provider object.

### OpenWeatherMap.Clouds Example

- **url**: http://{s}.tile.openweathermap.org/map/{variant}/{z}/{x}/{y}.png?appid={apiKey}
- **max_zoom**: 19
- **html_attribution**: Map data © OpenWeatherMap
- **attribution**: Map data (C) OpenWeatherMap
- **apiKey**: (Required, empty by default)
- **opacity**: 0.5
- **variant**: clouds

### Checking if a token is required

```python
xyz.OpenWeatherMap.Clouds.requires_token()
```

### Overriding Provider Attributes

```python
# Overriding the attribute will alter the existing object
xyz.OpenWeatherMap.Clouds["apiKey"] = "my-private-api-key"
```

### Calling the Provider Object (Returns a Copy)

```python
# Calling the object will return a copy with the specified apiKey
new_provider = xyz.OpenWeatherMap.Clouds(apiKey="my-private-api-key")

# The new_provider object will have the apiKey set:
# new_provider.apiKey == "my-private-api-key"
```

### Using a Provider with Options in another Library (e.g., contextily)

```python
# Assuming 'ax' is a matplotlib axes object
# import contextily
# contextily.add_basemap(ax, source=xyz.OpenWeatherMap.Clouds(apiKey="my-private-api-key"))
```

### Broken TileProvider Status

If a `TileProvider` is broken, it will have an additional attribute `status` with the value `"broken"`.
```

--------------------------------

### Initialize OpenWeatherMap Provider

Source: https://xyzservices.readthedocs.io/en/stable/api.html

Instantiate a provider by calling the object with an API key.

```python
>>> xyz.OpenWeatherMap.Clouds(apiKey="my-private-api-key")
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile for a specific layer using the WMTS GetTile request.

```APIDOC
## GET https://data.geopf.fr/wmts

### Description
Fetches a specific map tile based on the provided layer, style, and coordinates.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style identifier (e.g., ENR.AERO.CIVIL)
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier
- **FORMAT** (string) - Required - The image format (e.g., image/png)
- **LAYER** (string) - Required - The layer variant identifier
- **TILEMATRIX** (integer) - Required - The zoom level (z)
- **TILEROW** (integer) - Required - The row coordinate (y)
- **TILECOL** (integer) - Required - The column coordinate (x)
- **apikey** (string) - Required - Your API key for authentication
```

--------------------------------

### Configure Ordnance Survey provider

Source: https://xyzservices.readthedocs.io/en/stable/registration.html

Pass the project key to the Ordnance Survey provider.

```python
xyz.OrdnanceSurvey.Light(key="<insert api_key here>")
```

--------------------------------

### GET OpenWeatherMap Tile Provider

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves map tiles for various weather conditions from OpenWeatherMap.

```APIDOC
## GET http://{s}.tile.openweathermap.org/map/{variant}/{z}/{x}/{y}.png

### Description
Fetches weather map tiles based on the specified variant (e.g., precipitation, rain, wind, temperature).

### Method
GET

### Endpoint
http://{s}.tile.openweathermap.org/map/{variant}/{z}/{x}/{y}.png?appid={apiKey}

### Parameters
#### Path Parameters
- **variant** (string) - Required - The weather layer type (e.g., precipitation, rain, wind, temp, snow, pressure).
- **z** (integer) - Required - Zoom level.
- **x** (integer) - Required - X coordinate.
- **y** (integer) - Required - Y coordinate.

#### Query Parameters
- **appid** (string) - Required - The API key for OpenWeatherMap authentication.
```

--------------------------------

### Build URL with Predefined Providers

Source: https://xyzservices.readthedocs.io/en/stable/api.html

Import and use predefined TileProviders like `CartoDB.DarkMatter` to build URLs. The `build_url` method can accept tile coordinates (x, y, z) and a `scale_factor` for different resolutions.

```python
>>> import xyzservices.providers as xyz
```

```python
>>> xyz.CartoDB.DarkMatter.build_url()
'https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png'
```

```python
>>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5)
'https://a.basemaps.cartocdn.com/dark_all/5/9/11.png'
```

```python
>>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5, scale_factor="@2x")
'https://a.basemaps.cartocdn.com/dark_all/5/9/11@2x.png'
```

```python
>>> xyz.MapBox.build_url(accessToken="my_token")
'https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/{z}/{x}/{y}?access_token=my_token'
```

--------------------------------

### GET /wmts (Tile Retrieval)

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a specific map tile from the Geoportail France WMTS service.

```APIDOC
## GET /wmts

### Description
Retrieves a map tile based on the specified layer variant, zoom level, and tile coordinates.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Parameters
#### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style of the layer (e.g., 'normal')
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier
- **FORMAT** (string) - Required - The image format (e.g., 'image/jpeg', 'image/png')
- **LAYER** (string) - Required - The layer variant identifier
- **TILEMATRIX** (string) - Required - The zoom level (z)
- **TILEROW** (string) - Required - The row coordinate (y)
- **TILECOL** (string) - Required - The column coordinate (x)
- **apikey** (string) - Required - Your API key for authentication
```

--------------------------------

### Configure Mapbox provider

Source: https://xyzservices.readthedocs.io/en/stable/registration.html

Initialize the Mapbox provider using a map ID and access token.

```python
xyz.MapBox(id="<insert map_ID here>", accessToken="my-private-ACCESS_TOKEN")
```

--------------------------------

### GET MapBox Map Tiles

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves map tiles from MapBox using a specific style ID.

```APIDOC
## GET https://api.mapbox.com/styles/v1/{id}/tiles/{z}/{x}/{y}{r}

### Description
Fetches map tiles from MapBox services.

### Method
GET

### Endpoint
https://api.mapbox.com/styles/v1/{id}/tiles/{z}/{x}/{y}{r}?access_token={accessToken}

### Parameters
#### Path Parameters
- **id** (string) - Required - Map style ID
- **z** (integer) - Required - Zoom level
- **x** (integer) - Required - X coordinate
- **y** (integer) - Required - Y coordinate

#### Query Parameters
- **access_token** (string) - Required - API access token
```

--------------------------------

### Create and Access a Bunch

Source: https://xyzservices.readthedocs.io/en/stable/api.html

Store TileProvider objects in a Bunch to enable attribute-based access.

```python
>>> black_and_white = TileProvider(
...     name="My black and white tiles",
...     url="https://myserver.com/bw/{z}/{x}/{y}",
...     attribution="(C) xyzservices",
... )
>>> colorful = TileProvider(
...     name="My colorful tiles",
...     url="https://myserver.com/color/{z}/{x}/{y}",
...     attribution="(C) xyzservices",
... )
>>> MyTiles = Bunch(BlackAndWhite=black_and_white, Colorful=colorful)
>>> MyTiles
{'BlackAndWhite': {'name': 'My black and white tiles', 'url': 'https://myserver.com/bw/{z}/{x}/{y}', 'attribution': '(C) xyzservices'}, 'Colorful': {'name': 'My colorful tiles', 'url': 'https://myserver.com/color/{z}/{x}/{y}', 'attribution': '(C) xyzservices'}}
>>> MyTiles.BlackAndWhite.url
'https://myserver.com/bw/{z}/{x}/{y}'
```

--------------------------------

### GET Jawg Map Tiles

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves map tiles from Jawg Maps using a specified variant.

```APIDOC
## GET https://tile.jawg.io/{variant}/{z}/{x}/{y}{r}.png

### Description
Fetches map tiles from Jawg services.

### Method
GET

### Endpoint
https://tile.jawg.io/{variant}/{z}/{x}/{y}{r}.png?access-token={accessToken}

### Parameters
#### Path Parameters
- **variant** (string) - Required - The map style variant (e.g., jawg-dark, jawg-light, jawg-matrix)
- **z** (integer) - Required - Zoom level
- **x** (integer) - Required - X coordinate
- **y** (integer) - Required - Y coordinate

#### Query Parameters
- **access-token** (string) - Required - API access token
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile for a specific layer, style, and zoom level using the WMTS standard.

```APIDOC
## GET /wmts

### Description
Fetches a map tile from the Geoportail France WMTS service based on the provided layer, style, and coordinates.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style identifier for the layer
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier (e.g., PM_6_18)
- **FORMAT** (string) - Required - The image format (e.g., image/png)
- **LAYER** (string) - Required - The layer variant identifier
- **TILEMATRIX** (string) - Required - The zoom level (z)
- **TILEROW** (string) - Required - The row coordinate (y)
- **TILECOL** (string) - Required - The column coordinate (x)

### Response
#### Success Response (200)
- **Content-Type** (image/png) - The requested map tile image.
```

--------------------------------

### Configure Jawg Maps provider

Source: https://xyzservices.readthedocs.io/en/stable/registration.html

Initialize the Jawg provider with an access token and optional map variant.

```python
xyz.Jawg.Streets(
    accessToken="<insert access token here>",
    variant="<insert map id here or blank for default variant>"
)
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile from the Geoportail France WMTS service based on the specified layer and coordinates.

```APIDOC
## GET /wmts

### Description
Retrieves a specific map tile for a given layer, style, and zoom level.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Query Parameters
- **SERVICE** (string) - Required - Must be 'WMTS'
- **VERSION** (string) - Required - Must be '1.0.0'
- **REQUEST** (string) - Required - Must be 'GetTile'
- **STYLE** (string) - Required - The style of the layer
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier
- **FORMAT** (string) - Required - The image format (e.g., image/png)
- **LAYER** (string) - Required - The variant/layer name
- **TILEMATRIX** (integer) - Required - The zoom level (z)
- **TILEROW** (integer) - Required - The row coordinate (y)
- **TILECOL** (integer) - Required - The column coordinate (x)
- **apikey** (string) - Required - Your API key for authentication
```

--------------------------------

### GET /wmts

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves a map tile from the Geoportail France WMTS service based on the specified layer and coordinates.

```APIDOC
## GET /wmts

### Description
Retrieves a specific map tile for a given layer, style, and zoom level.

### Method
GET

### Endpoint
https://data.geopf.fr/wmts

### Query Parameters
- **SERVICE** (string) - Required - The service type (WMTS).
- **VERSION** (string) - Required - The service version (1.0.0).
- **REQUEST** (string) - Required - The request type (GetTile).
- **STYLE** (string) - Required - The style of the layer.
- **TILEMATRIXSET** (string) - Required - The tile matrix set identifier.
- **FORMAT** (string) - Required - The image format (e.g., image/png).
- **LAYER** (string) - Required - The layer variant identifier.
- **TILEMATRIX** (string) - Required - The zoom level (z).
- **TILEROW** (string) - Required - The row coordinate (y).
- **TILECOL** (string) - Required - The column coordinate (x).
- **apikey** (string) - Required - The user API key.
```

--------------------------------

### Add Single TileProvider JSON Schema

Source: https://xyzservices.readthedocs.io/en/stable/contributing.html

Use this schema to add a single TileProvider to the `xyzservices-providers.json` file. Ensure `name`, `url`, and `attribution` are always specified.

```json
{
   "single_provider_name": {
      "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
      "max_zoom": 19,
      "attribution": "(C) OpenStreetMap contributors",
      "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors",
      "name": "OpenStreetMap.Mapnik"
   },
}
```

--------------------------------

### Add Bunch of TileProviders JSON Schema

Source: https://xyzservices.readthedocs.io/en/stable/contributing.html

Group related TileProviders, like different versions from a single source, within a 'Bunch' using this schema. Specify `name`, `url`, and `attribution` for each provider. Use `"<insert your access token here>"` for access token placeholders.

```json
{
  "provider_bunch_name": {
      "first_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap contributors",
            "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors",
            "name": "OpenStreetMap.Mapnik"
      },
      "second_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?access-token={accessToken}",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap contributors",
            "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors",
            "name": "OpenStreetMap.Mapnik",
            "accessToken": "<insert your access token here>"
      }
   },
}
```

--------------------------------

### GET MapTiler Map Tiles

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Retrieves map tiles from MapTiler using a specified variant and file extension.

```APIDOC
## GET https://api.maptiler.com/maps/{variant}/{z}/{x}/{y}{r}.{ext}

### Description
Fetches map tiles from MapTiler services.

### Method
GET

### Endpoint
https://api.maptiler.com/maps/{variant}/{z}/{x}/{y}{r}.{ext}?key={key}

### Parameters
#### Path Parameters
- **variant** (string) - Required - The map style variant
- **z** (integer) - Required - Zoom level
- **x** (integer) - Required - X coordinate
- **y** (integer) - Required - Y coordinate
- **ext** (string) - Required - File extension (e.g., png, jpg)

#### Query Parameters
- **key** (string) - Required - API key
```

--------------------------------

### Configure Thunderforest provider

Source: https://xyzservices.readthedocs.io/en/stable/registration.html

Pass the API key to the Thunderforest provider.

```python
xyz.Thunderforest.Landscape(apikey="<insert api_key here>")
```

--------------------------------

### Configure HERE and HEREv3 API keys

Source: https://xyzservices.readthedocs.io/en/stable/_sources/registration.md.txt

Use the apiKey attribute or call the object to return a copy with the key. Legacy projects can use app_id and app_code.

```python
xyz.HEREv3.terrainDay["apiKey"] = "my-private-api-key"

# Calling the object will return a copy
xyz.HEREv3.terrainDay(apiKey="my-private-api-key")
```

```python
xyz.HERE.terrainDay(app_id="my-private-app-id", app_code="my-app-code")
```

--------------------------------

### Get Type of OpenStreetMap Mapnik TileProvider

Source: https://xyzservices.readthedocs.io/en/stable/introduction.html

Use this to check the type of a TileProvider object. It confirms that OpenStreetMap.Mapnik is an instance of xyzservices.lib.TileProvider.

```python
type(xyz.OpenStreetMap.Mapnik)

```