0
# Folium
1

2
A comprehensive Python library for creating interactive web maps with Leaflet.js. Folium enables data scientists and developers to visualize geospatial data through Python's data manipulation capabilities while leveraging the powerful mapping features of the Leaflet.js JavaScript library. It offers a complete set of mapping components including markers, polygons, circles, popups, tooltips, choropleth maps, and various tile layers, with support for GeoJSON data integration, custom styling, and interactive features.
3

4
## Package Information
5

6
- **Package Name**: folium
7
- **Language**: Python
8
- **Installation**: `pip install folium`
9

10
## Core Imports
11

12
```python
13
import folium
14
```
15

16
Common patterns for specific functionality:
17

18
```python
19
from folium import Map, Marker, Popup, Icon
20
from folium import GeoJson, Choropleth, FeatureGroup
21
from folium.vector_layers import PolyLine, Polygon, Circle
22
from folium.plugins import MarkerCluster, HeatMap
23
```
24

25
## Basic Usage
26

27
```python
28
import folium
29
import numpy as np
30

31
# Create a basic map
32
map = folium.Map(
33
    location=[45.5236, -122.6750],  # Portland, OR
34
    zoom_start=13,
35
    tiles='OpenStreetMap'
36
)
37

38
# Add a simple marker
39
folium.Marker(
40
    [45.5244, -122.6699],
41
    popup='Downtown Portland',
42
    tooltip='Click me!',
43
    icon=folium.Icon(color='red', icon='info-sign')
44
).add_to(map)
45

46
# Add a circle
47
folium.Circle(
48
    location=[45.5236, -122.6750],
49
    radius=300,
50
    popup='300m radius',
51
    color='blue',
52
    fill=True,
53
    fillColor='lightblue'
54
).add_to(map)
55

56
# Display map (in Jupyter) or save
57
map.save('my_map.html')
58
```
59

60
## Architecture
61

62
Folium is built around a hierarchical component system:
63

64
- **Map**: The root container managing canvas, layers, and overall layout
65
- **Layers**: Raster (tiles) and vector (shapes) data layers  
66
- **Features**: Interactive elements like markers, popups, and data visualizations
67
- **Controls**: UI elements for layer management and user interaction
68
- **Plugins**: Extended functionality through 40 specialized plugins
69

70
This design allows every visual element to be customized and provides seamless integration with Python data science libraries including NumPy, pandas, GeoPandas, and Jupyter notebooks.
71

72
## Capabilities
73

74
### Core Mapping
75

76
The fundamental Map class and essential mapping components including tile layers, basic markers, popups, and layer management controls.
77

78
```python { .api }
79
class Map:
80
    def __init__(
81
        self,
82
        location=None,
83
        width='100%',
84
        height='100%',
85
        left='0%',
86
        top='0%',
87
        position='relative',
88
        tiles='OpenStreetMap',
89
        attr=None,
90
        min_zoom=0,
91
        max_zoom=18,
92
        zoom_start=10,
93
        min_lat=-90,
94
        max_lat=90,
95
        min_lon=-180,
96
        max_lon=180,
97
        max_bounds=False,
98
        crs='EPSG3857',
99
        control_scale=False,
100
        prefer_canvas=False,
101
        no_touch=False,
102
        disable_3d=False,
103
        png_enabled=False,
104
        zoom_control=True,
105
        **kwargs
106
    ): ...
107

108
class Marker:
109
    def __init__(
110
        self,
111
        location=None,
112
        tooltip=None,
113
        popup=None,
114
        icon=None,
115
        draggable=False,
116
        **kwargs
117
    ): ...
118

119
class TileLayer:
120
    def __init__(
121
        self,
122
        tiles='OpenStreetMap',
123
        min_zoom=0,
124
        max_zoom=18,
125
        max_native_zoom=None,
126
        attr=None,
127
        name=None,
128
        overlay=False,
129
        control=True,
130
        show=True,
131
        **kwargs
132
    ): ...
133
```
134

135
[Core Mapping](./core-mapping.md)
136

137
### Data Visualization
138

139
Advanced data visualization capabilities including GeoJSON rendering, choropleth maps, and integration with Vega/Vega-Lite for embedded charts.
140

141
```python { .api }
142
class GeoJson:
143
    def __init__(
144
        self,
145
        data,
146
        style_function=None,
147
        highlight_function=None,
148
        name=None,
149
        overlay=True,
150
        control=True,
151
        show=True,
152
        smooth_factor=1.0,
153
        tooltip=None,
154
        popup=None,
155
        marker=None,
156
        **kwargs
157
    ): ...
158

159
class Choropleth:
160
    def __init__(
161
        self,
162
        geo_data,
163
        data=None,
164
        columns=None,
165
        key_on=None,
166
        bins=6,
167
        fill_color='blue',
168
        nan_fill_color='black',
169
        fill_opacity=0.7,
170
        nan_fill_opacity=0.4,
171
        line_color='black',
172
        line_weight=1,
173
        line_opacity=1,
174
        name=None,
175
        legend_name='',
176
        overlay=True,
177
        control=True,
178
        show=True,
179
        topojson=None,
180
        smooth_factor=1.0,
181
        highlight=False,
182
        **kwargs
183
    ): ...
184
```
185

186
[Data Visualization](./data-visualization.md)
187

188
### Vector Layers
189

190
Geometric shapes and paths including polylines, polygons, circles, and rectangles with customizable styling and interactive features.
191

192
```python { .api }
193
class PolyLine:
194
    def __init__(
195
        self,
196
        locations,
197
        popup=None,
198
        tooltip=None,
199
        smooth_factor=1.0,
200
        no_clip=False,
201
        **kwargs
202
    ): ...
203

204
class Polygon:
205
    def __init__(
206
        self,
207
        locations,
208
        popup=None,
209
        tooltip=None,
210
        **kwargs
211
    ): ...
212

213
class Circle:
214
    def __init__(
215
        self,
216
        location=None,
217
        radius=10,
218
        popup=None,
219
        tooltip=None,
220
        **kwargs
221
    ): ...
222
```
223

224
[Vector Layers](./vector-layers.md)
225

226
### Interactive Features
227

228
User interaction components including click handlers, custom controls, and specialized marker types for enhanced map interactivity.
229

230
```python { .api }
231
class ClickForMarker:
232
    def __init__(self, popup=None): ...
233

234
class ClickForLatLng:
235
    def __init__(self, format_str=None, alert=False): ...
236

237
class Control:
238
    def __init__(self, position='topright'): ...
239
```
240

241
[Interactive Features](./interactive-features.md)
242

243
### Plugins
244

245
Extensive plugin ecosystem providing specialized functionality including clustering, heatmaps, drawing tools, temporal visualizations, and advanced controls.
246

247
```python { .api }
248
class MarkerCluster:
249
    def __init__(
250
        self,
251
        locations=None,
252
        popups=None,
253
        tooltips=None,
254
        icons=None,
255
        name=None,
256
        overlay=True,
257
        control=True,
258
        show=True,
259
        icon_create_function=None,
260
        options=None
261
    ): ...
262

263
class HeatMap:
264
    def __init__(
265
        self,
266
        data,
267
        name=None,
268
        min_opacity=0.4,
269
        max_zoom=18,
270
        max_val=1.0,
271
        radius=25,
272
        blur=15,
273
        gradient=None,
274
        overlay=True,
275
        control=True,
276
        show=True
277
    ): ...
278

279
class Draw:
280
    def __init__(
281
        self,
282
        export=False,
283
        filename='data.geojson',
284
        position='topleft',
285
        draw_options=None,
286
        edit_options=None
287
    ): ...
288
```
289

290
[Plugins](./plugins.md)
291

292
### Utilities and Styling
293

294
Helper functions, color maps, and JavaScript integration utilities for advanced customization and programmatic map control.
295

296
```python { .api }
297
class JsCode:
298
    def __init__(self, js_code): ...
299

300
class ColorMap:
301
    def __init__(self, colors, index=None, vmin=0, vmax=1, caption=''): ...
302

303
class LinearColormap:
304
    def __init__(
305
        self,
306
        colors,
307
        index=None,
308
        vmin=0,
309
        vmax=1,
310
        caption=''
311
    ): ...
312
```
313

314
[Utilities and Styling](./utilities-styling.md)
315

316
## Types
317

318
```python { .api }
319
# Location types
320
Location = Union[Tuple[float, float], List[float]]
321
Locations = Union[List[Location], Tuple[Location, ...]]
322

323
# Bounds type  
324
Bounds = Union[List[List[float]], Tuple[Tuple[float, float], Tuple[float, float]]]
325

326
# Style function type
327
StyleFunction = Callable[[Dict], Dict[str, Any]]
328

329
# GeoJSON-like data
330
GeoJsonData = Union[Dict, str, FeatureCollection]
331
```