### Install xyzservices using Pip

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Install the xyzservices package using pip.

```shell
pip install xyzservices
```

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

### Install xyzservices using Conda

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Install the xyzservices package from the conda-forge channel.

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

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

### Select and Visualize Providers with Folium

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Select specific XYZ tile providers by name and visualize them on a Folium map. This requires the `folium` library to be installed. The code adds each selected tile layer and a layer control to the map.

```python
selection = ['OpenStreetMap.Mapnik', 
             'OpenTopoMap', 
             'Stamen.Toner', 
             'Stamen.TonerLite', 
             'Stamen.Terrain', 
             'Stamen.TerrainBackground', 
             'Stamen.Watercolor', 
             'NASAGIBS.ViirsEarthAtNight2012', 
             'CartoDB.Positron', 
             'CartoDB.Voyager'
            ]
```

```python
m = folium.Map(location=[53.4108, -2.9358], zoom_start=8)

for tiles_name in selection:
    tiles = providers[tiles_name]
    folium.TileLayer(
        tiles=tiles.build_url(),
        attr=tiles.html_attribution,
        name=tiles.name,
    ).add_to(m)

folium.LayerControl().add_to(m)

m
```

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

### Providers JSON Structure Example

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/api.rst

This JSON structure illustrates how providers are organized, including single providers and provider bunches. It shows the required fields like URL, max_zoom, attribution, and optional fields like html_attribution and accessToken.

```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>"
      }
   }
}
```

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

### Providers JSON Structure

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/api.rst

Example structure of the providers JSON file used as a database of providers.

```APIDOC
## Providers JSON Structure

### Description
The `providers.json` file contains a database of tile providers. It can be structured to include single providers or bunches of providers.

### Example Structure

```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>"
      }
   }
}
```

### Fields
- **url** (string): The URL template for the tile provider.
- **max_zoom** (integer): The maximum zoom level supported.
- **attribution** (string): Text attribution for the provider.
- **html_attribution** (string): HTML formatted attribution.
- **name** (string): The name of the provider.
- **accessToken** (string, optional): Placeholder for access token if required.
```

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

### Define Tile Coverage Bounds

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/contributing.md

Example of specifying the geographic bounds for a tile provider using latitude and longitude coordinates. The format is [[lat_min, lon_min], [lat_max, lon_max]].

```json
{
  "bounds": [
      [
          45,
          5
      ],
      [
          48,
          11
      ]
  ],
}
```

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

### Check and Set TileProvider Token Requirement

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/index.md

Check if a TileProvider requires an access token and set it if necessary. For example, MapBox requires a token.

```python
>>> xyz.MapBox.requires_token()
True

>>> xyz.MapBox["accessToken"] = "my_personal_token"
>>> xyz.MapBox.requires_token()
False
```

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

### Stadia Maps AlidadeSmooth with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Configure Stadia Maps AlidadeSmooth layer with an API key. This example shows how to adapt a provider object to include the API key in the URL.

```python
provider = xyz.Stadia.AlidadeSmooth(api_key="<insert api_key here>")
provider["url"] = provider["url"] + "?api_key={api_key}"  # adding API key placeholder
```

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

### Check if TileProvider requires token

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Determine if a given XYZ tile provider requires an access token for usage. For example, MapBox.

```python
xyz.MapBox.requires_token()
```

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

### Update Leaflet Providers

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/contributing.md

Command to update leaflet providers from the repository root. Requires a functional installation of selenium with Firefox webdriver, git, and html2text.

```bash
cd xyzservices
make update-leaflet
```

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

### Load Provider from Quick Map Services

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Load a specific XYZ tile provider directly from the Quick Map Services database using its name. Ensure the name exactly matches the entry in the QMS database.

```python
from xyzservices import TileProvider

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

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

### Compress Provider Sources

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/contributing.md

Command to compress provider sources from the repository root. Requires navigating to the 'xyzservices' directory first.

```bash
cd xyzservices
make compress
```

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

### TileProvider Class Methods

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/api.rst

Documentation for the TileProvider class, including its methods.

```APIDOC
## TileProvider Class

### Description
Represents a tile provider with methods to build URLs and check for token requirements.

### Methods
- **build_url**: Builds the URL for the tile provider.
- **requires_token**: Checks if the provider requires a token.
- **from_qms**: Creates a TileProvider instance from a QMS definition.
```

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

### Create Empty Release Commit

Source: https://github.com/geopandas/xyzservices/wiki/Release-checklist

Use this command to create an empty commit for the release version. This is a preparatory step before tagging.

```bash
git commit --allow-empty -m "RLS: 2021.8.0"
```

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

### Inspect Provider Object Contents

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Examine the detailed configuration of a specific tile provider, including its URL, attribution, and maximum zoom level.

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

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

### Explore Available Providers

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

View all available provider objects by simply referencing the imported 'xyz' object. This is useful for interactive exploration in environments like Jupyter notebooks.

```python
xyz
```

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

### Import xyzservices providers

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Import the providers module from xyzservices, aliased as 'xyz' for convenience.

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

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

### Accessing Provider Options

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Accesses the Clouds provider from OpenWeatherMap. Use this to check available options or methods.

```python
xyz.OpenWeatherMap.Clouds
```

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

### Access Specific Provider Options

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Drill down into a specific provider, like OpenStreetMap, to see its available background styles or variants.

```python
xyz.OpenStreetMap
```

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

### Access TileProvider URL and Attribution

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/index.md

Retrieve the URL template and attribution string for a specific TileProvider like CartoDB.Positron.

```python
>>> xyz.CartoDB.Positron.url
'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png'

>>> xyz.CartoDB.Positron.attribution
'(C) OpenStreetMap contributors (C) CARTO'
```

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

### Building Single Tile URL with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Builds a URL for a single tile, specifying coordinates (x, y, z) and an API key. This is useful for fetching individual tiles when authentication is required.

```python
xyz.OpenWeatherMap.Clouds.build_url(x=12, y=21, z=15, apiKey="my-private-api-key")
```

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

### Add Single Tile Provider Schema

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/contributing.md

Schema for adding a single TileProvider to the provider_sources/xyzservices-providers.json file. Requires at least name, url, and attribution.

```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"
   },
}
```

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

### Ordnance Survey Light with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Access Ordnance Survey Light maps by providing your API key obtained from OS Data Hub after creating a project and assigning the OS Maps API product.

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

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

### Add Bunch of Tile Providers Schema

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/contributing.md

Schema for grouping related TileProviders within a 'Bunch' in the provider_sources/xyzservices-providers.json file. Each provider within the bunch follows the single provider schema.

```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>"
      }
   },
}
```

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

### HERE Legacy Terrain Day with App ID and Code

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

For legacy projects, use this to configure HERE terrain day layers with your application ID and application code.

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

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

### TomTom Map with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Use TomTom layers by providing your API key obtained after registering on the TomTom developer portal.

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

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

### Bunch Class Methods

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/api.rst

Documentation for the Bunch class, including its filtering and querying capabilities.

```APIDOC
## Bunch Class

### Description
Provides methods for filtering, flattening, and querying provider names.

### Methods
- **filter**: Filters providers based on specified criteria.
- **flatten**: Flattens the provider structure.
- **query_name**: Queries providers by name.
```

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

### Access TileProvider URL

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Retrieve the URL template for a specific XYZ tile provider, such as CartoDB Positron.

```python
xyz.CartoDB.Positron.url
```

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

### Count Built-in Providers

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Determine the total number of built-in XYZ tile providers available in the library.

```python
len(providers)
```

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

### Tag Release Commit

Source: https://github.com/geopandas/xyzservices/wiki/Release-checklist

Create an annotated tag for the release commit. Ensure the tag name matches the version number.

```bash
git tag -a 2021.8.0 -m "Version 2021.8."
```

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

### Specifying API Key for Provider

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Demonstrates two ways to specify an API key for the OpenWeatherMap Clouds provider: by overriding the attribute directly or by calling the object with the key as an argument. Overriding alters the existing object, while calling returns a copy.

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

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

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

### Building Tile URL for Folium Map

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Builds a tile URL for a Folium map using the CartoDB Positron provider. It includes options for scale factor and HTML attribution, suitable for interactive web maps.

```python
import folium

tiles = xyz.CartoDB.Positron

folium.Map(
    location=[53.4108, -2.9358],
    tiles=tiles.build_url(scale_factor="@2x"),
    attr=tiles.html_attribution,
)
```

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

### Access TileProvider Attribution

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Retrieve the attribution string for a specific XYZ tile provider, such as CartoDB Positron.

```python
xyz.CartoDB.Positron.attribution
```

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

### Checking Token Requirements

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Checks if the OpenWeatherMap Clouds provider requires a token for access. This is useful for understanding authentication needs.

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

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

### Adding Basemap with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Adds a basemap to an axis using a specific tile provider (OpenWeatherMap Clouds) with an API key. This is useful when the tile provider requires authentication.

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

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

### Flatten Built-in Providers

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Access all built-in XYZ tile providers as a flat dictionary. This is useful for inspecting or iterating through available services.

```python
providers = xyz.flatten()
```

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

### Set TileProvider access token

Source: https://github.com/geopandas/xyzservices/blob/main/README.md

Assign an access token to a TileProvider that requires one, such as MapBox. This modifies the provider object in place.

```python
xyz.MapBox["accessToken"] = "my_personal_token"
```

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

### HEREv3 Terrain Day with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Configure HEREv3 terrain day layer with a private API key. This method returns a copy of the provider object with the updated key.

```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")
```

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

### Geoportail France Plan with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Use this to access Geoportail France maps by providing your obtained API key. A default public key is used if none is provided, but it offers no guarantees.

```python
xyz.GeoportailFrance.plan(apikey="<insert api_key here>")
```

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

### Add Provider Bunch Schema

Source: https://github.com/geopandas/xyzservices/blob/main/CONTRIBUTING.md

Use this JSON schema to group related TileProviders within a 'Bunch'. This is useful for different versions from a single source. Ensure 'name', 'url', and 'attribution' are always specified for each provider.

```json
{
  ... 
  "provider_bunch_name": {
      "first_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap 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",
            "name": "OpenStreetMap.Mapnik",
            "accessToken": "<insert your access token here>"
      }
   },
   ... 
}
```

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

### Check Provider Object Type

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/introduction.ipynb

Determine the type of a specific provider option, such as 'Mapnik' from OpenStreetMap, to understand its behavior as a dictionary-like object.

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

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

### Thunderforest Landscape with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Access Thunderforest Landscape maps by providing your API key obtained after registration.

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

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

### Jawg Maps Streets with Access Token and Variant

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Access Jawg Maps Streets layer by providing your access token and optionally a map variant ID. Leave the variant blank to use the default.

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

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

### MapTiler Cloud Streets with API Key

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Configure MapTiler Cloud Streets layer by providing your API key obtained from your MapTiler Cloud account.

```python
xyz.MapTiler.Streets(key="<insert key here>")
```

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

### Push Release Commit

Source: https://github.com/geopandas/xyzservices/wiki/Release-checklist

Push the empty release commit to the upstream repository. This action triggers the GitHub workflow.

```bash
git push upstream main
```

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

### Push Release Tag

Source: https://github.com/geopandas/xyzservices/wiki/Release-checklist

Push the annotated tag to the upstream repository. This is crucial for the release process to complete.

```bash
git push upstream --tags
```

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

### Mapbox Map with ID and Access Token

Source: https://github.com/geopandas/xyzservices/blob/main/doc/source/registration.md

Use Mapbox maps by specifying the map ID (e.g., "mapbox/satellite-v9") and your private access token obtained from Mapbox projects.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.