getting_started.md

Getting started

Installation

Folium can be installed using

$ pip install folium

If you are using the Conda package manager, the equivalent is

$ conda install folium -c conda-forge

Dependencies

Folium has the following dependencies, all of which are installed automatically with the above installation commands:

• branca

• Jinja2

• Numpy

• Requests

Additional packages may be necessary for some functionality. It will say so in the documentation where that's the case.

Creating a map

Here's a basic example of creating a map:

import folium

m = folium.Map(location=(45.5236, -122.6750))

If you are in a Jupyter Notebook, you can display it by asking for the object representation:

m

Or you can save it as an HTML file:

m.save("index.html")

Choosing a tileset

The default tiles are set to OpenStreetMap, but a selection of tilesets are also built in.

folium.Map((45.5236, -122.6750), tiles="cartodb positron")

You can also pass any tileset as a url template. Choose one from https://leaflet-extras.github.io/leaflet-providers/preview/ and pass the url and attribution. For example:

folium.Map(tiles='https://{s}.tiles.example.com/{z}/{x}/{y}.png', attr='My Data Attribution')

Folium also accepts objects from the xyzservices package.

Adding markers

There are various marker types, here we start with a simple Marker. You can add a popup and tooltip. You can also pick colors and icons.

m = folium.Map([45.35, -121.6972], zoom_start=12)

folium.Marker(
    location=[45.3288, -121.6625],
    tooltip="Click me!",
    popup="Mt. Hood Meadows",
    icon=folium.Icon(icon="cloud"),
).add_to(m)

folium.Marker(
    location=[45.3311, -121.7113],
    tooltip="Click me!",
    popup="Timberline Lodge",
    icon=folium.Icon(color="green"),
).add_to(m)

m

Vectors such as lines

Folium has various vector elements. One example is PolyLine, which can show linear elements on a map. This object can help put emphasis on a trail, a road, or a coastline.

m = folium.Map(location=[-71.38, -73.9], zoom_start=11)

trail_coordinates = [
    (-71.351871840295871, -73.655963711222626),
    (-71.374144382613707, -73.719861619751498),
    (-71.391042575973145, -73.784922248007007),
    (-71.400964450973134, -73.851042243124397),
    (-71.402411391077322, -74.050048183880477),
]

folium.PolyLine(trail_coordinates, tooltip="Coast").add_to(m)

m

Grouping and controlling

You can group multiple elements such as markers together in a FeatureGroup. You can select which you want to show by adding a LayerControl to the map.

m = folium.Map((0, 0), zoom_start=7)

group_1 = folium.FeatureGroup("first group").add_to(m)
folium.Marker((0, 0), icon=folium.Icon("red")).add_to(group_1)
folium.Marker((1, 0), icon=folium.Icon("red")).add_to(group_1)

group_2 = folium.FeatureGroup("second group").add_to(m)
folium.Marker((0, 1), icon=folium.Icon("green")).add_to(group_2)

folium.LayerControl().add_to(m)

m

GeoJSON/TopoJSON overlays

Folium supports both GeoJSON and TopoJSON data in various formats, such as urls, file paths and dictionaries.

import requests

m = folium.Map(tiles="cartodbpositron")

geojson_data = requests.get(
    "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/world_countries.json"
).json()

folium.GeoJson(geojson_data, name="hello world").add_to(m)

folium.LayerControl().add_to(m)

m

Choropleth maps

Choropleth can be created by binding the data between Pandas DataFrames/Series and Geo/TopoJSON geometries.

import pandas

state_geo = requests.get(
    "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
).json()
state_data = pandas.read_csv(
    "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_unemployment_oct_2012.csv"
)

m = folium.Map(location=[48, -102], zoom_start=3)

folium.Choropleth(
    geo_data=state_geo,
    name="choropleth",
    data=state_data,
    columns=["State", "Unemployment"],
    key_on="feature.id",
    fill_color="YlGn",
    fill_opacity=0.7,
    line_opacity=0.2,
    legend_name="Unemployment Rate (%)",
).add_to(m)

folium.LayerControl().add_to(m)

m