{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "# Adding a background map to plots\n",
    "\n",
    "This example shows how you can add a background basemap to plots created\n",
    "with the geopandas ``.plot()`` method. This makes use of the\n",
    "[contextily](https://github.com/geopandas/contextily) package to retrieve\n",
    "web map tiles from several sources (OpenStreetMap, Stamen).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's use the NYC borough boundary data that is available in geopandas\n",
    "datasets. Plotting this gives the following result:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = geopandas.read_file(geopandas.datasets.get_path('nybb'))\n",
    "ax = df.plot(figsize=(10, 10), alpha=0.5, edgecolor='k')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Convert the data to Web Mercator\n",
    "================================\n",
    "\n",
    "Web map tiles are typically provided in\n",
    "[Web Mercator](https://en.wikipedia.org/wiki/Web_Mercator>)\n",
    "([EPSG 3857](https://epsg.io/3857)), so we need to make sure to convert\n",
    "our data first to the same CRS to combine our polygons and background tiles\n",
    "in the same map:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = df.to_crs(epsg=3857)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import contextily as ctx"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add background tiles to plot\n",
    "============================\n",
    "\n",
    "We can use `add_basemap` function of contextily to easily add a background\n",
    "map to our plot. :\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [],
   "source": [
    "ax = df.plot(figsize=(10, 10), alpha=0.5, edgecolor='k')\n",
    "ctx.add_basemap(ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can control the detail of the map tiles using the optional `zoom` keyword\n",
    "(be careful to not specify a too high `zoom` level,\n",
    "as this can result in a large download).:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = df.plot(figsize=(10, 10), alpha=0.5, edgecolor='k')\n",
    "ctx.add_basemap(ax, zoom=12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, contextily uses the Stamen Terrain style. We can specify a\n",
    "different style using ``ctx.providers``:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = df.plot(figsize=(10, 10), alpha=0.5, edgecolor='k')\n",
    "ctx.add_basemap(ax, url=ctx.providers.Stamen.TonerLite)\n",
    "ax.set_axis_off()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}