# xyzservices - Source of XYZ tiles providers
`xyzservices` is a lightweight library providing a repository of available XYZ services
offering raster basemap tiles. The repository is provided via Python API and as a
compressed JSON file.
XYZ tiles can be used as background for your maps to provide necessary spatial context.
`xyzservices` offer specifications of many tile services and provide an easy-to-use
tools to plug them into your work, no matter if interactive or static.
[](https://github.com/geopandas/xyzservices/actions/workflows/tests.yaml) [](https://codecov.io/gh/geopandas/xyzservices) [](https://pypi.python.org/pypi/xyzservices)
## Quick Start
Using `xyzservices` is simple and in most cases does not involve more than a line of
code.
### Installation
You can install `xyzservices` from `conda` or `pip`:
```shell
conda install xyzservices -c conda-forge
```
```shell
pip install xyzservices
```
The package does not depend on any other apart from those built-in in Python.
### Providers API
The key part of `xyzservices` are providers:
```py
>>> import xyzservices.providers as xyz
```
`xyzservices.providers` or just `xyz` for short is a `Bunch` of providers, an enhanced
`dict`. If you are in Jupyter-like environment, `xyz` will offer collapsible inventory
of available XYZ tile sources. You can also explore it as a standard `dict` using
`xyz.keys()`. Once you have picked your provider, you get its details as a
`TileProvider` object with all the details you may need:
```py
>>> xyz.CartoDB.Positron.url
'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png'
>>> xyz.CartoDB.Positron.attribution
'(C) OpenStreetMap contributors (C) CARTO'
```
You can also check if the `TileProvider` needs API token and pass it to the object if
needed.
```py
>>> xyz.MapBox.requires_token()
True
>>> xyz.MapBox["accessToken"] = "my_personal_token"
>>> xyz.MapBox.requires_token()
False
```
### Providers JSON
After the installation, you will find the JSON used as a database of providers in
`share/xyzservices/providers.json` if you want to use it outside of a Python ecosystem.
## Contributors
`xyzservices` is developed by a community of enthusiastic volunteers and lives under
[`geopandas`](https://github.com/geopandas) GitHub organization. You can see a full list
of contributors [here](https://github.com/geopandas/xyzservices/graphs/contributors).
The main group of providers is retrieved from the [`leaflet-providers`
project](https://github.com/leaflet-extras/leaflet-providers) that contains both openly
accessible providers as well as those requiring registration. All of them are considered
[free](https://github.com/leaflet-extras/leaflet-providers/blob/master/README.md#what-do-we-mean-by-free).
If you would like to contribute to the project, have a look at the list of
[open issues](https://github.com/geopandas/contextily/issues), particularly those labeled as
[good first issue](https://github.com/geopandas/xyzservices/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
## License
BSD 3-Clause License
Resources coming from the [`leaflet-providers`
project](https://github.com/leaflet-extras/leaflet-providers) are licensed under BSD
2-Clause License (© 2013 Leaflet Providers)
Raw data
{
"_id": null,
"home_page": "https://github.com/geopandas/xyzservices",
"name": "xyzservices",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Dani Arribas-Bel, Martin Fleischmann",
"author_email": "daniel.arribas.bel@gmail.com, martin@martinfleischmann.net",
"download_url": "https://files.pythonhosted.org/packages/a0/16/ae87cbd2d6bfc40a419077521c35aadf5121725b7bee3d7c51b56f50958b/xyzservices-2024.9.0.tar.gz",
"platform": null,
"description": "# xyzservices - Source of XYZ tiles providers\n\n`xyzservices` is a lightweight library providing a repository of available XYZ services\noffering raster basemap tiles. The repository is provided via Python API and as a\ncompressed JSON file.\n\nXYZ tiles can be used as background for your maps to provide necessary spatial context.\n`xyzservices` offer specifications of many tile services and provide an easy-to-use\ntools to plug them into your work, no matter if interactive or static.\n\n[](https://github.com/geopandas/xyzservices/actions/workflows/tests.yaml) [](https://codecov.io/gh/geopandas/xyzservices) [](https://pypi.python.org/pypi/xyzservices)\n\n## Quick Start\n\nUsing `xyzservices` is simple and in most cases does not involve more than a line of\ncode.\n\n### Installation\n\nYou can install `xyzservices` from `conda` or `pip`:\n\n```shell\nconda install xyzservices -c conda-forge\n```\n\n```shell\npip install xyzservices\n```\n\nThe package does not depend on any other apart from those built-in in Python.\n\n### Providers API\n\nThe key part of `xyzservices` are providers:\n\n```py\n>>> import xyzservices.providers as xyz\n```\n\n`xyzservices.providers` or just `xyz` for short is a `Bunch` of providers, an enhanced\n`dict`. If you are in Jupyter-like environment, `xyz` will offer collapsible inventory\nof available XYZ tile sources. You can also explore it as a standard `dict` using\n`xyz.keys()`. Once you have picked your provider, you get its details as a\n`TileProvider` object with all the details you may need:\n\n```py\n>>> xyz.CartoDB.Positron.url\n'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png'\n\n>>> xyz.CartoDB.Positron.attribution\n'(C) OpenStreetMap contributors (C) CARTO'\n```\n\nYou can also check if the `TileProvider` needs API token and pass it to the object if\nneeded.\n\n```py\n>>> xyz.MapBox.requires_token()\nTrue\n\n>>> xyz.MapBox[\"accessToken\"] = \"my_personal_token\"\n>>> xyz.MapBox.requires_token()\nFalse\n```\n\n### Providers JSON\n\nAfter the installation, you will find the JSON used as a database of providers in\n`share/xyzservices/providers.json` if you want to use it outside of a Python ecosystem.\n\n## Contributors\n\n`xyzservices` is developed by a community of enthusiastic volunteers and lives under\n[`geopandas`](https://github.com/geopandas) GitHub organization. You can see a full list\nof contributors [here](https://github.com/geopandas/xyzservices/graphs/contributors).\n\nThe main group of providers is retrieved from the [`leaflet-providers`\nproject](https://github.com/leaflet-extras/leaflet-providers) that contains both openly\naccessible providers as well as those requiring registration. All of them are considered\n[free](https://github.com/leaflet-extras/leaflet-providers/blob/master/README.md#what-do-we-mean-by-free).\n\nIf you would like to contribute to the project, have a look at the list of\n[open issues](https://github.com/geopandas/contextily/issues), particularly those labeled as\n[good first issue](https://github.com/geopandas/xyzservices/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).\n\n## License\n\nBSD 3-Clause License\n\nResources coming from the [`leaflet-providers`\nproject](https://github.com/leaflet-extras/leaflet-providers) are licensed under BSD\n2-Clause License (\u00a9 2013 Leaflet Providers)\n",
"bugtrack_url": null,
"license": "3-Clause BSD",
"summary": "Source of XYZ tiles providers",
"version": "2024.9.0",
"project_urls": {
"Homepage": "https://github.com/geopandas/xyzservices"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4cd3e07ce413d16ef64e885bea37551eac4c5ca3ddd440933f9c94594273d0d9",
"md5": "ce3448c40a1f736f81e30cac88d7632c",
"sha256": "776ae82b78d6e5ca63dd6a94abb054df8130887a4a308473b54a6bd364de8644"
},
"downloads": -1,
"filename": "xyzservices-2024.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce3448c40a1f736f81e30cac88d7632c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 85130,
"upload_time": "2024-09-03T09:19:12",
"upload_time_iso_8601": "2024-09-03T09:19:12.166072Z",
"url": "https://files.pythonhosted.org/packages/4c/d3/e07ce413d16ef64e885bea37551eac4c5ca3ddd440933f9c94594273d0d9/xyzservices-2024.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a016ae87cbd2d6bfc40a419077521c35aadf5121725b7bee3d7c51b56f50958b",
"md5": "0b5770fd3880f03d4432f8c198c941f3",
"sha256": "68fb8353c9dbba4f1ff6c0f2e5e4e596bb9e1db7f94f4f7dfbcb26e25aa66fde"
},
"downloads": -1,
"filename": "xyzservices-2024.9.0.tar.gz",
"has_sig": false,
"md5_digest": "0b5770fd3880f03d4432f8c198c941f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1131900,
"upload_time": "2024-09-03T09:19:13",
"upload_time_iso_8601": "2024-09-03T09:19:13.504897Z",
"url": "https://files.pythonhosted.org/packages/a0/16/ae87cbd2d6bfc40a419077521c35aadf5121725b7bee3d7c51b56f50958b/xyzservices-2024.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-03 09:19:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geopandas",
"github_project": "xyzservices",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xyzservices"
}
JSON
