{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Quickstart\n",
"==========\n",
"\n",
"\n",
"Getting Started\n",
"---------------\n",
"\n",
"To create a base map, simply pass your starting coordinates to Folium:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"# This is to `import` the repository's version of folium ; not the installed one.\n",
"import sys, os\n",
"sys.path.insert(0, '..')\n",
"\n",
"import folium\n",
"map_osm = folium.Map(location=[45.5236, -122.6750])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To dispaly it in a Jupyter notebook, simply ask for the object representation:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_osm"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To save it in a file:"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"map_osm.save('/tmp/map.html')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium defaults to OpenStreetMap tiles, but Stamen Terrain, Stamen Toner,\n",
"Mapbox Bright, and Mapbox Control room tiles are built in:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"folium.Map(location=[45.5236, -122.6750],\n",
" tiles='Stamen Toner',\n",
" zoom_start=13)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium also supports Cloudmade and Mapbox custom tilesets- simply pass your key to the API_key keyword:\n",
"\n",
"```python\n",
"folium.Map(location=[45.5236, -122.6750],\n",
" tiles='Mapbox',\n",
" API_key='your.API.key')\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Lastly, Folium supports passing any Leaflet.js compatible custom tileset:\n",
"\n",
"```python\n",
"folium.Map(location=[45.372, -121.6972],\n",
" zoom_start=12,\n",
" tiles='http://{s}.tiles.yourtiles.com/{z}/{x}/{y}.png',\n",
" attr='My Data Attribution')\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Markers\n",
"-------\n",
"\n",
"Folium supports the plotting of numerous marker types, starting with a simple Leaflet\n",
"style location marker with popup text:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_1 = folium.Map(location=[45.372, -121.6972],\n",
" zoom_start=12,\n",
" tiles='Stamen Terrain')\n",
"folium.Marker([45.3288, -121.6625], popup='Mt. Hood Meadows').add_to(map_1)\n",
"folium.Marker([45.3311, -121.7113], popup='Timberline Lodge').add_to(map_1)\n",
"map_1"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium supports colors and marker icon types (from bootstrap)"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_1 = folium.Map(location=[45.372, -121.6972],\n",
" zoom_start=12,\n",
" tiles='Stamen Terrain')\n",
"folium.Marker([45.3288, -121.6625],\n",
" popup='Mt. Hood Meadows',\n",
" icon=folium.Icon(icon='cloud')\n",
" ).add_to(map_1)\n",
"folium.Marker([45.3311, -121.7113],\n",
" popup='Timberline Lodge',\n",
" icon=folium.Icon(color='green')\n",
" ).add_to(map_1)\n",
"folium.Marker([45.3300, -121.6823],\n",
" popup='Some Other Location',\n",
" icon=folium.Icon(color='red',icon='info-sign')\n",
" ).add_to(map_1)\n",
"map_1"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium also supports circle-style markers, with custom size and color:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_2 = folium.Map(location=[45.5236, -122.6750],\n",
" tiles='Stamen Toner',\n",
" zoom_start=13)\n",
"folium.Marker([45.5244, -122.6699],\n",
" popup='The Waterfront'\n",
" ).add_to(map_2)\n",
"folium.CircleMarker([45.5215, -122.6261],\n",
" radius=500,\n",
" popup='Laurelhurst Park',\n",
" color='#3186cc',\n",
" fill_color='#3186cc',\n",
" ).add_to(map_2)\n",
"map_2"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium has a convenience function to enable lat/lng popovers:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_3 = folium.Map(\n",
" location=[46.1991, -122.1889],\n",
" tiles='Stamen Terrain',\n",
" zoom_start=13)\n",
"map_3.add_child(folium.LatLngPopup())\n",
"map_3"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Click-for-marker functionality will allow for on-the-fly placement of markers:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_4 = folium.Map(location=[46.8527, -121.7649],\n",
" tiles='Stamen Terrain',\n",
" zoom_start=13)\n",
"folium.Marker([46.8354, -121.7325], popup='Camp Muir').add_to(map_4)\n",
"map_4.add_child(folium.ClickForMarker(popup=\"Waypoint\"))\n",
"map_4"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium also supports the Polygon marker set from the [Leaflet-DVF](https://github.com/humangeo/leaflet-dvf):"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map_5 = folium.Map(location=[45.5236, -122.6750],\n",
" zoom_start=13)\n",
"\n",
"folium.RegularPolygonMarker(\n",
" [45.5012, -122.6655],\n",
" popup='Ross Island Bridge',\n",
" fill_color='#132b5e',\n",
" number_of_sides=3,\n",
" radius=10\n",
" ).add_to(map_5)\n",
"folium.RegularPolygonMarker(\n",
" [45.5132, -122.6708],\n",
" popup='Hawthorne Bridge',\n",
" fill_color='#45647d',\n",
" number_of_sides=4,\n",
" radius=10\n",
" ).add_to(map_5)\n",
"folium.RegularPolygonMarker(\n",
" [45.5275, -122.6692],\n",
" popup='Steel Bridge',\n",
" fill_color='#769d96',\n",
" number_of_sides=6,\n",
" radius=10\n",
" ).add_to(map_5)\n",
"folium.RegularPolygonMarker(\n",
" [45.5318, -122.6745],\n",
" popup='Broadway Bridge',\n",
" fill_color='#769d96',\n",
" number_of_sides=8,\n",
" radius=10\n",
" ).add_to(map_5)\n",
"map_5"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Vincent/Vega Markers\n",
"\n",
"Folium enables passing [vincent](https://github.com/wrobstory/vincent) visualizations to any marker type, with the visualization as the popover:\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import json\n",
"\n",
"buoy_map = folium.Map(\n",
" [46.3014, -123.7390],\n",
" zoom_start=7,\n",
" tiles='Stamen Terrain'\n",
" )\n",
"\n",
"folium.RegularPolygonMarker(\n",
" [47.3489, -124.708],\n",
" fill_color='#43d9de',\n",
" radius=12,\n",
" popup=folium.Popup(max_width=450).add_child(\n",
" folium.Vega(json.load(open('vis1.json')), width=450, height=250))\n",
" ).add_to(buoy_map)\n",
"\n",
"folium.RegularPolygonMarker(\n",
" [44.639, -124.5339],\n",
" fill_color='#43d9de',\n",
" radius=12,\n",
" popup=folium.Popup(max_width=450).add_child(\n",
" folium.Vega(json.load(open('vis2.json')), width=450, height=250))\n",
" ).add_to(buoy_map)\n",
"\n",
"folium.RegularPolygonMarker(\n",
" [46.216, -124.1280],\n",
" fill_color='#43d9de',\n",
" radius=12,\n",
" popup=folium.Popup(max_width=450).add_child(\n",
" folium.Vega(json.load(open('vis3.json')), width=450, height=250))\n",
" ).add_to(buoy_map)\n",
"\n",
"buoy_map"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"For more information about popups, please visit [Popups.ipynb](http://nbviewer.jupyter.org/github/python-visualization/folium/blob/v0.2.0/examples/Popups.ipynb)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## GeoJSON/TopoJSON Overlays\n",
"\n",
"Both GeoJSON and TopoJSON layers can be passed to the map as an overlay, and multiple layers can be visualized on the same map:"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ice_map = folium.Map(location=[-59.1759, -11.6016],\n",
" tiles='Mapbox Bright', zoom_start=2)\n",
"\n",
"folium.GeoJson(open('antarctic_ice_edge.json'),\n",
" name='geojson'\n",
" ).add_to(ice_map)\n",
"\n",
"folium.TopoJson(open('antarctic_ice_shelf_topo.json'),\n",
" 'objects.antarctic_ice_shelf',\n",
" name='topojson',\n",
" ).add_to(ice_map)\n",
"\n",
"folium.LayerControl().add_to(ice_map)\n",
"ice_map"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Choropleth maps\n",
"\n",
"Folium allows for the binding of data between Pandas DataFrames/Series and Geo/TopoJSON geometries. [Color Brewer](http://colorbrewer2.org/) sequential color schemes are built-in to the library, and can be passed to quickly visualize different combinations:"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"../folium/folium.py:504: UserWarning: This method is deprecated. Please use Map.choropleth instead.\n",
" warnings.warn('This method is deprecated. '\n",
"../folium/folium.py:506: FutureWarning: 'threshold_scale' default behavior has changed. Now you get a linear scale between the 'min' and the 'max' of your data. To get former behavior, use folium.utilities.split_six.\n",
" return self.choropleth(*args, **kwargs)\n"
]
},
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import folium\n",
"import pandas as pd\n",
"\n",
"state_geo = r'us-states.json'\n",
"state_unemployment = r'US_Unemployment_Oct2012.csv'\n",
"\n",
"state_data = pd.read_csv(state_unemployment)\n",
"\n",
"#Let Folium determine the scale\n",
"map = folium.Map(location=[48, -102], zoom_start=3)\n",
"map.geo_json(geo_path=state_geo, data=state_data,\n",
" columns=['State', 'Unemployment'],\n",
" key_on='feature.id',\n",
" fill_color='YlGn', fill_opacity=0.7, line_opacity=0.2,\n",
" legend_name='Unemployment Rate (%)')\n",
"map"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Folium creates the legend on the upper right based on a D3 threshold scale, and makes the best-guess at values via quantiles. Passing your own threshold values is simple:\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"map = folium.Map(location=[48, -102], zoom_start=3)\n",
"map.geo_json(geo_path=state_geo, data=state_data,\n",
" columns=['State', 'Unemployment'],\n",
" threshold_scale=[5, 6, 7, 8, 9, 10],\n",
" key_on='feature.id',\n",
" fill_color='BuPu', fill_opacity=0.7, line_opacity=0.5,\n",
" legend_name='Unemployment Rate (%)',\n",
" reset=True)\n",
"map"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"By binding data via the Pandas DataFrame, different datasets can be quickly visualized. In the following example, the df DataFrame contains six columns with different economic data, a few of which we will visualize:"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/home/filipe/.virtualenvs/iris/lib/python2.7/site-packages/ipykernel/__main__.py:11: FutureWarning: 'threshold_scale' default behavior has changed. Now you get a linear scale between the 'min' and the 'max' of your data. To get former behavior, use folium.utilities.split_six.\n"
]
},
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import pandas as pd\n",
"unemployment = pd.read_csv('./US_Unemployment_Oct2012.csv')\n",
"\n",
"m = folium.Map([43,-100], zoom_start=4)\n",
"\n",
"m.choropleth(\n",
" geo_str=open('us-states.json').read(),\n",
" data=unemployment,\n",
" columns=['State', 'Unemployment'],\n",
" key_on='feature.id',\n",
" fill_color='YlGn',\n",
" )\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"For more choropleth example, please visit [GeoJSON and choropleth.ipynb](http://nbviewer.jupyter.org/github/python-visualization/folium/blob/v0.2.0/examples/GeoJSON and choropleth.ipynb)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 2",
"language": "python",
"name": "python2"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 2
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython2",
"version": "2.7.8"
}
},
"nbformat": 4,
"nbformat_minor": 0
}