0
# Core Mapping
1

2
Fundamental mapping functionality providing the essential Map class, basic markers, popups, tooltips, tile layers, and layer management controls. These components form the foundation of folium's mapping capabilities.
3

4
## Capabilities
5

6
### Map Creation
7

8
The primary Map class serves as the root container for all map elements, managing the canvas, coordinate system, and base tile layers.
9

10
```python { .api }
11
class Map:
12
    """
13
    Create a Map with Folium and Leaflet.js.
14
    
15
    Parameters:
16
    - location: tuple or list, initial map center coordinates [lat, lon]
17
    - width: str or int, map width (default '100%')
18
    - height: str or int, map height (default '100%')  
19
    - left: str, left margin (default '0%')
20
    - top: str, top margin (default '0%')
21
    - position: str, CSS positioning (default 'relative')
22
    - tiles: str or TileLayer, base tile layer (default 'OpenStreetMap')
23
    - attr: str, attribution text for custom tiles
24
    - min_zoom: int, minimum zoom level (default 0)
25
    - max_zoom: int, maximum zoom level (default 18)
26
    - zoom_start: int, initial zoom level (default 10)
27
    - min_lat: float, minimum latitude bounds (default -90)
28
    - max_lat: float, maximum latitude bounds (default 90) 
29
    - min_lon: float, minimum longitude bounds (default -180)
30
    - max_lon: float, maximum longitude bounds (default 180)
31
    - max_bounds: bool, restrict map bounds (default False)
32
    - crs: str, coordinate reference system (default 'EPSG3857')
33
    - control_scale: bool, show scale control (default False)
34
    - prefer_canvas: bool, use canvas renderer (default False)
35
    - no_touch: bool, disable touch interactions (default False)
36
    - disable_3d: bool, disable 3D CSS transforms (default False)
37
    - png_enabled: bool, enable PNG export (default False)
38
    - zoom_control: bool, show zoom control (default True)
39
    
40
    Returns:
41
    Map instance
42
    """
43
    def __init__(
44
        self,
45
        location=None,
46
        width='100%',
47
        height='100%', 
48
        left='0%',
49
        top='0%',
50
        position='relative',
51
        tiles='OpenStreetMap',
52
        attr=None,
53
        min_zoom=0,
54
        max_zoom=18,
55
        zoom_start=10,
56
        min_lat=-90,
57
        max_lat=90,
58
        min_lon=-180,
59
        max_lon=180,
60
        max_bounds=False,
61
        crs='EPSG3857',
62
        control_scale=False,
63
        prefer_canvas=False,
64
        no_touch=False,
65
        disable_3d=False,
66
        png_enabled=False,
67
        zoom_control=True,
68
        **kwargs
69
    ): ...
70
    
71
    def add_child(self, child): ...
72
    def add_to(self, parent): ...
73
    def save(self, outfile): ...
74
    def show_in_browser(self): ...
75
    def get_bounds(self): ...
76
    def fit_bounds(self, bounds, padding_top_left=None, padding_bottom_right=None, padding=None, max_zoom=None): ...
77
```
78

79
### Markers
80

81
Point markers with customizable icons, popups, and interactive behavior.
82

83
```python { .api }
84
class Marker:
85
    """
86
    Create a marker on the map.
87
    
88
    Parameters:
89
    - location: tuple or list, marker coordinates [lat, lon]
90
    - tooltip: str or Tooltip, hover text
91
    - popup: str or Popup, click popup content
92
    - icon: Icon, marker icon (default uses standard icon)
93
    - draggable: bool, allow marker dragging (default False)
94
    
95
    Returns:
96
    Marker instance
97
    """
98
    def __init__(
99
        self,
100
        location=None,
101
        tooltip=None,
102
        popup=None, 
103
        icon=None,
104
        draggable=False,
105
        **kwargs
106
    ): ...
107
    
108
    def add_to(self, parent): ...
109
```
110

111
### Icons
112

113
Customizable marker icons with different styles and appearances.
114

115
```python { .api }
116
class Icon:
117
    """
118
    Create a standard marker icon.
119
    
120
    Parameters:
121
    - color: str, icon color ('red', 'blue', 'green', 'purple', 'orange', 'darkred', 'lightred', 'beige', 'darkblue', 'darkgreen', 'cadetblue', 'darkpurple', 'white', 'pink', 'lightblue', 'lightgreen', 'gray', 'black', 'lightgray')
122
    - icon_color: str, icon symbol color (default 'white')
123
    - icon: str, icon symbol name (FontAwesome or Glyphicon)
124
    - angle: int, icon rotation angle (default 0)
125
    - prefix: str, icon prefix ('fa' for FontAwesome, 'glyphicon' for Glyphicon)
126
    
127
    Returns:
128
    Icon instance
129
    """
130
    def __init__(
131
        self,
132
        color='blue',
133
        icon_color='white',
134
        icon='info-sign',
135
        angle=0,
136
        prefix='glyphicon'
137
    ): ...
138

139
class CustomIcon:
140
    """
141
    Create a custom image-based icon.
142
    
143
    Parameters:
144
    - icon_image: str, URL or path to icon image
145
    - icon_size: tuple, icon dimensions [width, height]
146
    - icon_anchor: tuple, anchor point [x, y]
147
    - popup_anchor: tuple, popup anchor relative to icon [x, y]
148
    - shadow_image: str, shadow image URL (optional)
149
    - shadow_size: tuple, shadow dimensions (optional)
150
    - shadow_anchor: tuple, shadow anchor point (optional)
151
    
152
    Returns:
153
    CustomIcon instance
154
    """
155
    def __init__(
156
        self,
157
        icon_image,
158
        icon_size=None,
159
        icon_anchor=None,
160
        popup_anchor=None,
161
        shadow_image=None,
162
        shadow_size=None,
163
        shadow_anchor=None
164
    ): ...
165

166
class DivIcon:
167
    """
168
    Create an HTML/CSS-based icon using div elements.
169
    
170
    Parameters:
171
    - html: str, HTML content for the icon
172
    - icon_size: tuple, icon dimensions [width, height]
173
    - icon_anchor: tuple, anchor point [x, y]
174
    - popup_anchor: tuple, popup anchor relative to icon [x, y]
175
    - class_name: str, CSS class name
176
    
177
    Returns:
178
    DivIcon instance
179
    """
180
    def __init__(
181
        self,
182
        html=None,
183
        icon_size=None,
184
        icon_anchor=None,
185
        popup_anchor=None,
186
        class_name='divicon'
187
    ): ...
188
```
189

190
### Popups and Tooltips
191

192
Interactive information display components for map elements.
193

194
```python { .api }
195
class Popup:
196
    """
197
    Create a popup window for map elements.
198
    
199
    Parameters:
200
    - html: str, HTML content for popup
201
    - parse_html: bool, parse HTML tags (default False)
202
    - max_width: int, maximum popup width in pixels (default 300)
203
    - show: bool, show popup immediately (default False)
204
    - sticky: bool, keep popup open on mouse out (default False)
205
    - lazy: bool, lazy loading (default False)
206
    
207
    Returns:
208
    Popup instance
209
    """
210
    def __init__(
211
        self,
212
        html=None,
213
        parse_html=False,
214
        max_width=300,
215
        show=False,
216
        sticky=False,
217
        lazy=False,
218
        **kwargs
219
    ): ...
220

221
class Tooltip:
222
    """
223
    Create a tooltip for map elements.
224
    
225
    Parameters:
226
    - text: str, tooltip text content
227
    - style: str, CSS styles for tooltip
228
    - permanent: bool, always show tooltip (default False)
229
    - direction: str, tooltip direction ('right', 'left', 'top', 'bottom', 'center', 'auto')
230
    - sticky: bool, follow mouse cursor (default True)
231
    - opacity: float, tooltip opacity (default 0.9)
232
    
233
    Returns:
234
    Tooltip instance
235
    """
236
    def __init__(
237
        self,
238
        text='',
239
        style=None,
240
        permanent=False,
241
        direction='right',
242
        sticky=True,
243
        opacity=0.9,
244
        **kwargs
245
    ): ...
246
```
247

248
### Tile Layers
249

250
Raster tile layers providing base maps and overlays from various providers.
251

252
```python { .api }
253
class TileLayer:
254
    """
255
    Create a tile layer for the map.
256
    
257
    Parameters:
258
    - tiles: str, tile provider name or URL template
259
    - min_zoom: int, minimum zoom level (default 0)
260
    - max_zoom: int, maximum zoom level (default 18)
261
    - max_native_zoom: int, maximum native zoom of tiles
262
    - attr: str, attribution text
263
    - name: str, layer name for layer control
264
    - overlay: bool, treat as overlay layer (default False)  
265
    - control: bool, show in layer control (default True)
266
    - show: bool, show layer initially (default True)
267
    - no_wrap: bool, disable tile wrapping (default False)
268
    - opacity: float, layer opacity (default 1.0)
269
    - z_index: int, layer z-index
270
    - unload_invisible_tiles: bool, unload off-screen tiles (default False)
271
    - update_when_idle: bool, update when map is idle (default False)
272
    - detect_retina: bool, use retina/high-DPI tiles (default False)
273
    
274
    Returns:
275
    TileLayer instance
276
    """
277
    def __init__(
278
        self,
279
        tiles='OpenStreetMap',
280
        min_zoom=0,
281
        max_zoom=18,
282
        max_native_zoom=None,
283
        attr=None,
284
        name=None,
285
        overlay=False,
286
        control=True,
287
        show=True,
288
        no_wrap=False,
289
        opacity=1.0,
290
        z_index=None,
291
        unload_invisible_tiles=False,
292
        update_when_idle=False,
293
        detect_retina=False,
294
        **kwargs
295
    ): ...
296

297
class WmsTileLayer:
298
    """
299
    Create a Web Map Service (WMS) tile layer.
300
    
301
    Parameters:
302
    - url: str, WMS service URL
303
    - layers: str, WMS layer names (comma-separated)
304
    - styles: str, WMS style names (comma-separated)
305
    - format: str, image format (default 'image/jpeg')
306
    - transparent: bool, transparent background (default False)
307
    - version: str, WMS version (default '1.1.1')
308
    - crs: str, coordinate reference system
309
    - uppercase: bool, uppercase parameter names (default False)
310
    - name: str, layer name for layer control
311
    - overlay: bool, treat as overlay layer (default False)
312
    - control: bool, show in layer control (default True)
313
    - show: bool, show layer initially (default True)
314
    
315
    Returns:
316
    WmsTileLayer instance
317
    """
318
    def __init__(
319
        self,
320
        url,
321
        layers='',
322
        styles='',
323
        format='image/jpeg',
324
        transparent=False,
325
        version='1.1.1',
326
        crs=None,
327
        uppercase=False,
328
        name=None,
329
        overlay=False,
330
        control=True,
331
        show=True,
332
        **kwargs
333
    ): ...
334
```
335

336
### Layer Management
337

338
Components for organizing and controlling map layers.
339

340
```python { .api }
341
class LayerControl:
342
    """
343
    Create a layer control for toggling layer visibility.
344
    
345
    Parameters:
346
    - position: str, control position ('topright', 'topleft', 'bottomright', 'bottomleft')
347
    - collapsed: bool, collapse control initially (default True)
348
    - autoZIndex: bool, auto-assign z-index (default True)
349
    - hideSingleBase: bool, hide control with single base layer (default False)
350
    - sortLayers: bool, sort layers alphabetically (default False)
351
    - sortFunction: callable, custom sort function
352
    
353
    Returns:
354
    LayerControl instance
355
    """
356
    def __init__(
357
        self,
358
        position='topright',
359
        collapsed=True,
360
        autoZIndex=True,
361
        hideSingleBase=False,
362
        sortLayers=False,
363
        sortFunction=None
364
    ): ...
365

366
class FeatureGroup:
367
    """
368
    Container for grouping related map elements.
369
    
370
    Parameters:
371
    - name: str, group name for layer control
372
    - overlay: bool, treat as overlay in layer control (default True)
373
    - control: bool, show in layer control (default True)
374
    - show: bool, show group initially (default True)
375
    
376
    Returns:
377
    FeatureGroup instance
378
    """
379
    def __init__(
380
        self,
381
        name=None,
382
        overlay=True,
383
        control=True,
384
        show=True,
385
        **kwargs
386
    ): ...
387
    
388
    def add_child(self, child): ...
389
    def add_to(self, parent): ...
390
```
391

392
### Map Bounds Control
393

394
Utilities for controlling map viewport and bounds.
395

396
```python { .api }
397
class FitBounds:
398
    """
399
    Fit map view to specified bounds.
400
    
401
    Parameters:
402
    - bounds: list, bounding box [[south, west], [north, east]]
403
    - padding_top_left: tuple, top-left padding [x, y]
404
    - padding_bottom_right: tuple, bottom-right padding [x, y]
405
    - padding: tuple, uniform padding [x, y]
406
    - max_zoom: int, maximum zoom level for fitting
407
    
408
    Returns:
409
    FitBounds instance
410
    """
411
    def __init__(
412
        self,
413
        bounds,
414
        padding_top_left=None,
415
        padding_bottom_right=None,
416
        padding=None,
417
        max_zoom=None
418
    ): ...
419

420
class FitOverlays:
421
    """
422
    Fit map view to contain all overlay layers.
423
    
424
    Parameters:
425
    - padding_top_left: tuple, top-left padding [x, y]
426
    - padding_bottom_right: tuple, bottom-right padding [x, y]
427
    - padding: tuple, uniform padding [x, y]
428
    - max_zoom: int, maximum zoom level for fitting
429
    
430
    Returns:
431
    FitOverlays instance
432
    """
433
    def __init__(
434
        self,
435
        padding_top_left=None,
436
        padding_bottom_right=None,
437
        padding=None,
438
        max_zoom=None
439
    ): ...
440
```
441

442
## Usage Examples
443

444
### Basic Map with Markers
445

446
```python
447
import folium
448

449
# Create map centered on San Francisco
450
m = folium.Map(
451
    location=[37.7749, -122.4194],
452
    zoom_start=12,
453
    tiles='CartoDB Positron'
454
)
455

456
# Add markers with different icons
457
folium.Marker(
458
    [37.7849, -122.4094],
459
    popup='Golden Gate Park',
460
    tooltip='Hover for info',
461
    icon=folium.Icon(color='green', icon='tree-deciduous', prefix='fa')
462
).add_to(m)
463

464
folium.Marker(
465
    [37.7649, -122.4294],
466
    popup='Mission District', 
467
    icon=folium.Icon(color='red', icon='heart')
468
).add_to(m)
469

470
# Custom icon marker
471
folium.Marker(
472
    [37.7949, -122.3994],
473
    popup='Custom Icon',
474
    icon=folium.CustomIcon(
475
        icon_image='https://example.com/icon.png',
476
        icon_size=(30, 30)
477
    )
478
).add_to(m)
479

480
m.save('sf_map.html')
481
```
482

483
### Layer Control and Feature Groups
484

485
```python
486
import folium
487

488
m = folium.Map(location=[40.7128, -74.0060], zoom_start=11)
489

490
# Create feature groups
491
parks = folium.FeatureGroup(name='Parks')
492
restaurants = folium.FeatureGroup(name='Restaurants')
493

494
# Add markers to groups
495
folium.Marker(
496
    [40.7829, -73.9654],
497
    popup='Central Park',
498
    icon=folium.Icon(color='green')
499
).add_to(parks)
500

501
folium.Marker(
502
    [40.7505, -73.9934],
503
    popup='Famous Restaurant',
504
    icon=folium.Icon(color='red')
505
).add_to(restaurants)
506

507
# Add groups to map
508
parks.add_to(m)
509
restaurants.add_to(m)
510

511
# Add layer control
512
folium.LayerControl().add_to(m)
513

514
m.save('nyc_layers.html')
515
```