08_interactive_maps_folium.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1s8GgozXFAPd"
      },
      "source": [
        "## Overview\n",
        "\n",
        "[Folium](https://python-visualization.github.io/folium/) is a Python library that allows you to create interactive maps based on the popular [Leaflet](https://leafletjs.com/) javascript library.\n",
        "\n",
        "In this section, we will learn how to create an interactive map showing driving directions between two locations."
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Setup\n"
      ],
      "metadata": {
        "id": "XemNQtbvFIEP"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "gq4OcXTNFAPf"
      },
      "outputs": [],
      "source": [
        "import os\n",
        "import folium"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "data_folder = 'data'\n",
        "output_folder = 'output'\n",
        "\n",
        "if not os.path.exists(data_folder):\n",
        "    os.mkdir(data_folder)\n",
        "if not os.path.exists(output_folder):\n",
        "    os.mkdir(output_folder)"
      ],
      "metadata": {
        "id": "Eq92xYk2X1Ou"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Gs9zrOlyFAPh"
      },
      "source": [
        "We will be using [OpenRouteService API](https://openrouteservice.org/) to calculate the directions. Please sign-up for a free account and create an API key. If you already have an account, the API key is obtained from the [OpenRouteService Dashboard](https://openrouteservice.org/dev/#/home). Enter your API key below."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "EWf1HUpEFAPh"
      },
      "outputs": [],
      "source": [
        "ORS_API_KEY = ''"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Folium Basics"
      ],
      "metadata": {
        "id": "QZzokKUYF_Pv"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "We will learn the basics of folium by creating an interactive map showing the driving directions between two chosen locations. Let's start by defining the coordinates of two cities."
      ],
      "metadata": {
        "id": "cx3LVJ6nqSYr"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "972KJRsuFAPf"
      },
      "outputs": [],
      "source": [
        "san_francisco = (37.7749, -122.4194)\n",
        "new_york = (40.661, -73.944)"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "To create a map, we initialize the `folium.Map()` class which creates a map object with the default basemap. To display the map a Jupyter notebook, we can simply enter the name of the map object."
      ],
      "metadata": {
        "id": "tIdqwhUpqfMw"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "E1jOi7IcFAPg"
      },
      "outputs": [],
      "source": [
        "m = folium.Map()\n",
        "m"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "The default map spans the full width of the Jupyter notebook - making it difficult to navigate. The `Map()` constructor supports `width` and `height` parameters that control the size of the leaflet map, but you still end up with a lot of extra empty space below the map. The preferred way to get a map of exact size is to create a *Figure* first and add the map object to it."
      ],
      "metadata": {
        "id": "hN5S_cWRq52_"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "iTy4kpnKFAPg"
      },
      "outputs": [],
      "source": [
        "from folium import Figure\n",
        "fig = Figure(width=800, height=400)\n",
        "m = folium.Map(location=[39.83, -98.58], zoom_start=4)\n",
        "fig.add_child(m)"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "The map object `m` can be manipulated by adding different elements to it. Contrary to how Matplotlib objects work, the map object does not get emptied when displayed. So you are able to visualize and incrementally add elements to it. Let's add some markers to the map using [`folium.map.Marker`](https://python-visualization.github.io/folium/modules.html#folium.map.Marker) class."
      ],
      "metadata": {
        "id": "trzZIzWBrV8V"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "UWmrZw7rFAPg"
      },
      "outputs": [],
      "source": [
        "folium.Marker(san_francisco, popup='San Francisco').add_to(m)\n",
        "folium.Marker(new_york, popup='New York').add_to(m)\n",
        "\n",
        "m"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "nJCTyP6GFAPg"
      },
      "source": [
        "The markers can be customized to have a different color or icons. You can check the [`folium.map.Icon`](https://python-visualization.github.io/folium/modules.html#folium.map.Icon) class for options for creating icons. This class supports a vast range of icons from the [fontawesome icons](https://fontawesome.com/search?m=free&c=maps) and [bootstrap icons](https://getbootstrap.com/docs/3.3/components/) libraries. You can choose the name of the icon from there to use it in your Folium map. The `prefix` parameter can be *fa* for FontAwesome icons or *glyphicon* for Bootstrap3."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "1Xz0NkLBFAPh"
      },
      "outputs": [],
      "source": [
        "from folium import Figure\n",
        "fig = Figure(width=800, height=400)\n",
        "m = folium.Map(location=[39.83, -98.58], zoom_start=4)\n",
        "folium.Marker(san_francisco, popup='San Francisco',\n",
        "              icon=folium.Icon(\n",
        "                  color='green', icon='crosshairs', prefix='fa')\n",
        "             ).add_to(m)\n",
        "folium.Marker(new_york, popup='New York',\n",
        "              icon=folium.Icon(color='red', icon='crosshairs', prefix='fa')\n",
        "             ).add_to(m)\n",
        "fig.add_child(m)\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ocFNnJOaFAPi"
      },
      "outputs": [],
      "source": [
        "import requests\n",
        "\n",
        "san_francisco = (37.7749, -122.4194)\n",
        "new_york = (40.661, -73.944)\n",
        "\n",
        "parameters = {\n",
        "    'api_key': ORS_API_KEY,\n",
        "    'start' : '{},{}'.format(san_francisco[1], san_francisco[0]),\n",
        "    'end' : '{},{}'.format(new_york[1], new_york[0])\n",
        "}\n",
        "\n",
        "response = requests.get(\n",
        "    'https://api.openrouteservice.org/v2/directions/driving-car', params=parameters)\n",
        "\n",
        "if response.status_code == 200:\n",
        "    print('Request successful.')\n",
        "    data = response.json()\n",
        "else:\n",
        "    print('Request failed.')\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "UPazUxJOFAPi"
      },
      "source": [
        "Extract the coordinates for the driving directions."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "PrJoJBPgFAPi"
      },
      "outputs": [],
      "source": [
        "route= data['features'][0]['geometry']['coordinates']"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "9JssQDdaFAPi"
      },
      "outputs": [],
      "source": [
        "route[:5]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "IvLxZZ2YFAPj"
      },
      "source": [
        "The coordinates returned by OpenRouteService API is in the order [X,Y] (i.e. [Longitude, Latitude]) whereas Folium requires the coordinates in [Y,X] (i.e. [Latitude, Longitude]) order. We can swap them before plotting."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "esapsVquFAPj"
      },
      "outputs": [],
      "source": [
        "route_xy = []\n",
        "for x, y in route:\n",
        "    route_xy.append((y,x))\n",
        "route_xy[:5]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "U7QFEQ4fFAPj"
      },
      "source": [
        "An easier way to accomplish the same is by using a Python [List Comprehension](https://www.w3schools.com/python/python_lists_comprehension.asp)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "KmcD3dgjFAPj"
      },
      "outputs": [],
      "source": [
        "route_xy = [(y, x) for x, y in route]\n",
        "route_xy[:5]"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "We extract the route summary returned by the API which contains the total driving distance in meters."
      ],
      "metadata": {
        "id": "cg_T5C4Q2qe-"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "E27-arRiFAPj"
      },
      "outputs": [],
      "source": [
        "summary = data['features'][0]['properties']['summary']\n",
        "distance = round(summary['distance']/1000)\n",
        "tooltip = 'Driving Distance: {} km'.format(distance)"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "We can use the [`folium.vector_layers.Polyline`](https://python-visualization.github.io/folium/modules.html#folium.vector_layers.PolyLine) class to add a line to the map. The class has a `smooth_factor` parameter which can be used to simplify the line displayed when zoomed-out. Setting a higher number results in better performance."
      ],
      "metadata": {
        "id": "9FcCbCmm2pqQ"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "j9YbI7Q3FAPj"
      },
      "outputs": [],
      "source": [
        "folium.PolyLine(route_xy, tooltip=tooltip, smooth_factor=1).add_to(m)\n",
        "m"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "> Folium also provides a [`GeoJson`](https://python-visualization.github.io/folium/latest/user_guide/geojson/geojson.html) method to load any data in the GeoJSON format directly. Instead of extracting the coordinates, and creating a Polyline, we can also directly use the GeoJSON response returned by the OpenRouteService API like this. This is the preferred method as it gives you additional features for styling and layer manipulation.\n",
        "\n",
        "```\n",
        "folium.GeoJson(data, tooltip=tooltip, smooth_factor=1)\n",
        "```"
      ],
      "metadata": {
        "id": "uI44PQed9mNB"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Folium maps can be saved to a HTML file by calling `save()` on the map object."
      ],
      "metadata": {
        "id": "jGjT5vUM32qO"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "olCiFZxmFAPj"
      },
      "outputs": [],
      "source": [
        "output_folder = 'output'\n",
        "if not os.path.exists(output_folder):\n",
        "    os.mkdir(output_folder)\n",
        "output_path = os.path.join(output_folder, 'directions.html')\n",
        "m.save(output_path)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SL4b2GeLFAPj"
      },
      "source": [
        "## Exercise\n",
        "\n",
        "1. Create an interactive map of driving directions between two of your chosen cities.\n",
        "2. Cutomize the marker icons to a *car* icon. Reference [`folium.map.Icon`](https://python-visualization.github.io/folium/modules.html#folium.map.Icon).\n",
        "3. Change the route line to *red* color with a line width of 1 pixels. Reference [`folium.vector_layers.Polyline`](https://python-visualization.github.io/folium/modules.html#folium.vector_layers.PolyLine) and [`leaflet.Path`](https://leafletjs.com/reference.html#path)\n",
        "\n",
        "\n",
        "<img src='https://courses.spatialthoughts.com/images/python_dataviz/folium_route.png' width=600/>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Use the code block below as the starting point and replace the variables below with those of your chosen locations and insert your own API key."
      ],
      "metadata": {
        "id": "w_onmU3lHZpi"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "8GZjtGsYFAPj"
      },
      "outputs": [],
      "source": [
        "import folium\n",
        "import requests\n",
        "\n",
        "###############################\n",
        "###  Replace Variables Below\n",
        "###############################\n",
        "origin = (37.7749, -122.4194)\n",
        "origin_name = 'San Francisco'\n",
        "destination = (40.661, -73.944)\n",
        "destination_name = 'New York'\n",
        "map_center = (39.83, -98.58)\n",
        "ORS_API_KEY = ''\n",
        "###############################\n",
        "parameters = {\n",
        "    'api_key': ORS_API_KEY,\n",
        "    'start' : '{},{}'.format(origin[1], origin[0]),\n",
        "    'end' : '{},{}'.format(destination[1], destination[0])\n",
        "}\n",
        "\n",
        "response = requests.get(\n",
        "    'https://api.openrouteservice.org/v2/directions/driving-car', params=parameters)\n",
        "\n",
        "if response.status_code == 200:\n",
        "    print('Request successful.')\n",
        "    data = response.json()\n",
        "else:\n",
        "    print('Request failed.')\n",
        "\n",
        "route= data['features'][0]['geometry']['coordinates']\n",
        "summary = data['features'][0]['properties']['summary']\n",
        "\n",
        "route_xy = [(y, x) for x, y in route]\n",
        "distance = round(summary['distance']/1000)\n",
        "tooltip = 'Driving Distance: {} km'.format(distance)\n",
        "\n",
        "from folium import Figure\n",
        "fig = Figure(width=800, height=400)\n",
        "\n",
        "m = folium.Map(location=map_center, zoom_start=4)\n",
        "folium.Marker(origin, popup=origin_name,\n",
        "              icon=folium.Icon(\n",
        "                  color='green', icon='crosshairs', prefix='fa')\n",
        "             ).add_to(m)\n",
        "folium.Marker(destination, popup=destination_name,\n",
        "              icon=folium.Icon(color='red', icon='crosshairs', prefix='fa')\n",
        "             ).add_to(m)\n",
        "folium.PolyLine(route_xy, tooltip=tooltip).add_to(m)\n",
        "fig.add_child(m)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "JeSKkXRIFAPk"
      },
      "source": [
        "----"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3 (ipykernel)",
      "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.10.5"
    },
    "colab": {
      "provenance": []
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}