0
# Basemap Management
1

2
Extensive basemap collection with 100+ predefined providers supporting XYZ tiles, WMS services, and custom tile sources with backend-specific optimizations and QuickMapServices integration.
3

4
## Capabilities
5

6
### Basemap Access and Management
7

8
Access and manage basemaps from various providers with automatic backend-specific formatting and optimization.
9

10
```python { .api }
11
def get_xyz_dict(free_only=True, france=False):
12
    """
13
    Get dictionary of available XYZ basemap providers.
14
    
15
    Args:
16
        free_only (bool): Return only free basemap providers
17
        france (bool): Include France-specific providers
18
    
19
    Returns:
20
        dict: Dictionary of basemap providers with metadata
21
    """
22

23
def xyz_to_leaflet():
24
    """
25
    Convert XYZ basemap definition to ipyleaflet format.
26
    
27
    Returns:
28
        ipyleaflet.TileLayer: Formatted basemap layer
29
    """
30

31
def xyz_to_folium(xyz):
32
    """
33
    Convert XYZ basemap definition to folium format.
34
    
35
    Args:
36
        xyz (dict): XYZ basemap definition
37
        
38
    Returns:
39
        folium.TileLayer: Formatted basemap layer
40
    """
41

42
def xyz_to_plotly(xyz):
43
    """
44
    Convert XYZ basemap definition to plotly format.
45
    
46
    Args:
47
        xyz (dict): XYZ basemap definition
48
        
49
    Returns:
50
        dict: Plotly basemap configuration
51
    """
52

53
def xyz_to_bokeh(xyz):
54
    """
55
    Convert XYZ basemap definition to bokeh format.
56
    
57
    Args:
58
        xyz (dict): XYZ basemap definition
59
        
60
    Returns:
61
        bokeh.models.WMTSTileSource: Bokeh tile source
62
    """
63

64
def xyz_to_pydeck(xyz):
65
    """
66
    Convert XYZ basemap definition to pydeck format.
67
    
68
    Args:
69
        xyz (dict): XYZ basemap definition
70
        
71
    Returns:
72
        dict: Pydeck basemap configuration
73
    """
74
```
75

76
### QuickMapServices Integration
77

78
Search and access basemaps from QuickMapServices (QMS) repository with thousands of additional providers.
79

80
```python { .api }
81
def search_qms(keyword):
82
    """
83
    Search QuickMapServices for basemaps matching keyword.
84
    
85
    Args:
86
        keyword (str): Search term for basemap names/descriptions
87
        
88
    Returns:
89
        list: List of matching QMS basemap definitions
90
    """
91

92
def get_qms(qms_id):
93
    """
94
    Get specific QuickMapServices basemap by ID.
95
    
96
    Args:
97
        qms_id (int): QMS basemap ID
98
        
99
    Returns:
100
        dict: QMS basemap definition with tile URL and metadata
101
    """
102

103
def qms_to_leaflet(qms_id):
104
    """
105
    Convert QMS basemap to ipyleaflet format.
106
    
107
    Args:
108
        qms_id (int): QMS basemap ID
109
        
110
    Returns:
111
        ipyleaflet.TileLayer: Leaflet basemap layer
112
    """
113

114
def qms_to_folium(qms_id):
115
    """
116
    Convert QMS basemap to folium format.
117
    
118
    Args:
119
        qms_id (int): QMS basemap ID
120
        
121
    Returns:
122
        folium.TileLayer: Folium basemap layer
123
    """
124
```
125

126
### Map-Level Basemap Methods
127

128
Add and manage basemaps directly on map instances with automatic styling and layer control integration.
129

130
```python { .api }
131
def add_basemap(self, basemap='OpenStreetMap', show=True, **kwargs):
132
    """
133
    Add basemap to the map.
134
    
135
    Args:
136
        basemap (str or dict): Basemap name or custom definition
137
        show (bool): Whether to show the basemap immediately
138
        **kwargs: Basemap options (opacity, attribution, etc.)
139
    """
140

141
def change_basemap(self, basemap):
142
    """
143
    Change the current basemap.
144
    
145
    Args:
146
        basemap (str): New basemap name
147
    """
148

149
def add_xyz_service(self, provider, **kwargs):
150
    """
151
    Add XYZ tile service as basemap.
152
    
153
    Args:
154
        provider (str): XYZ provider name or URL template
155
        **kwargs: Service options (attribution, max_zoom, etc.)
156
    """
157

158
def add_wms_layer(self, url, layers, **kwargs):
159
    """
160
    Add WMS service as basemap layer.
161
    
162
    Args:
163
        url (str): WMS service URL
164
        layers (str): Comma-separated layer names
165
        **kwargs: WMS options (format, transparent, version, etc.)
166
    """
167
```
168

169
## Built-in Basemap Providers
170

171
### XYZ_TILES Dictionary
172

173
The package includes access to 100+ basemap providers through built-in `XYZ_TILES` and integration with xyzservices:
174

175
```python { .api }
176
XYZ_TILES: dict  # Dictionary of 100+ basemap provider definitions
177

178
# Core XYZ tile providers dictionary structure:
179
XYZ_TILES = {
180
    'OpenStreetMap': {...},
181
    'ROADMAP': {...},           # Google Roads
182
    'SATELLITE': {...},         # Google Satellite  
183
    'TERRAIN': {...},          # Google Terrain
184
    'HYBRID': {...},           # Google Hybrid
185
    'Esri WorldImagery': {...},
186
    'CartoDB positron': {...},
187
    'CartoDB dark_matter': {...},
188
    'OpenTopoMap': {...},
189
    'Stamen Terrain': {...},
190
    'Stamen Toner': {...},
191
    'Stamen Watercolor': {...},
192
    # ... 80+ additional providers
193
}
194

195
# WMS service definitions
196
WMS_TILES: dict  # Dictionary of WMS service providers
197

198
# basemaps object with accessor methods
199
basemaps = Box(XYZ_TILES)  # Box object providing dot notation access
200

201
# Key basemap categories:
202
# - OpenStreetMap variants
203
# - Satellite imagery (Google, Esri, etc.)
204
# - Topographic maps
205
# - Terrain and elevation
206
# - Specialized themes (dark, light, etc.)
207
# - Historical and vintage maps
208
```
209

210
### Popular Basemap Providers
211

212
#### OpenStreetMap Family
213
- `'OpenStreetMap'`: Standard OSM
214
- `'OpenTopoMap'`: Topographic styling
215
- `'Stamen Terrain'`: Terrain visualization
216
- `'Stamen Toner'`: High contrast black and white
217
- `'Stamen Watercolor'`: Artistic watercolor style
218

219
#### Satellite and Imagery
220
- `'SATELLITE'`: Google Satellite
221
- `'ROADMAP'`: Google Roads
222
- `'TERRAIN'`: Google Terrain
223
- `'HYBRID'`: Google Hybrid
224
- `'Esri WorldImagery'`: Esri satellite imagery
225
- `'Esri NatGeoWorldMap'`: National Geographic styling
226

227
#### Specialized Maps
228
- `'CartoDB positron'`: Light theme
229
- `'CartoDB dark_matter'`: Dark theme
230
- `'OpenRailwayMap'`: Railway infrastructure
231
- `'OpenFireMap'`: Fire station and hydrant data
232

233
### WMS Services
234

235
Access to Web Map Services for specialized data layers:
236

237
```python { .api }
238
WMS_TILES: dict  # WMS service definitions
239

240
# Available WMS services include:
241
# - National weather services
242
# - Geological surveys
243
# - Land cover datasets
244
# - Administrative boundaries
245
```
246

247
## Usage Examples
248

249
### Basic Basemap Usage
250

251
```python
252
import leafmap
253

254
# Create map with specific basemap
255
m = leafmap.Map(center=[40, -100], zoom=4, basemap='OpenTopoMap')
256

257
# Add additional basemap
258
m.add_basemap('SATELLITE', show=False)
259

260
# Add layer control to toggle basemaps
261
m.add_layer_control()
262

263
m
264
```
265

266
### Custom Basemap Configuration
267

268
```python
269
import leafmap
270

271
# Define custom XYZ basemap
272
custom_basemap = {
273
    'url': 'https://your-tile-server.com/{z}/{x}/{y}.png',
274
    'attribution': 'Your Attribution',
275
    'name': 'Custom Basemap',
276
    'max_zoom': 18
277
}
278

279
# Create map and add custom basemap
280
m = leafmap.Map()
281
m.add_xyz_service(custom_basemap)
282

283
m
284
```
285

286
### QuickMapServices Integration
287

288
```python
289
import leafmap
290

291
# Search for specific basemap type
292
results = leafmap.search_qms('satellite')
293
print(f"Found {len(results)} satellite basemaps")
294

295
# Use specific QMS basemap
296
m = leafmap.Map()
297

298
if results:
299
    qms_layer = leafmap.qms_to_leaflet(results[0]['id'])
300
    m.add_layer(qms_layer)
301

302
m
303
```
304

305
### Backend-Specific Basemap Usage
306

307
```python
308
# Get basemap dictionary
309
xyz_dict = leafmap.get_xyz_dict()
310

311
# Convert for different backends
312
import leafmap.foliumap as folium_map
313
import leafmap.plotlymap as plotly_map
314

315
# Folium backend
316
folium_basemap = leafmap.xyz_to_folium(xyz_dict['OpenStreetMap'])
317

318
# Plotly backend  
319
plotly_basemap = leafmap.xyz_to_plotly(xyz_dict['OpenStreetMap'])
320
```
321

322
### WMS Layer Integration
323

324
```python
325
import leafmap
326

327
# Add WMS weather layer
328
m = leafmap.Map()
329

330
m.add_wms_layer(
331
    url='https://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0r.cgi',
332
    layers='nexrad-n0r-900913',
333
    name='Weather Radar',
334
    format='image/png',
335
    transparent=True,
336
    opacity=0.6
337
)
338

339
m
340
```
341

342
## Basemap Categories
343

344
### Geographic and Physical
345
- **Topographic**: Elevation contours, terrain features
346
- **Satellite**: High-resolution imagery from space
347
- **Terrain**: 3D-style terrain visualization
348
- **Bathymetry**: Ocean floor and water depth
349

350
### Thematic and Specialized
351
- **Transportation**: Roads, railways, airports
352
- **Land Cover**: Vegetation, urban areas, water bodies
353
- **Administrative**: Political boundaries, census data
354
- **Historical**: Vintage maps and historical imagery
355

356
### Artistic and Stylized
357
- **Watercolor**: Artistic rendering styles
358
- **Minimalist**: Clean, simple designs
359
- **Dark/Light**: Theme-based color schemes
360
- **High Contrast**: Enhanced visibility options
361

362
## Basemap Configuration Options
363

364
### Standard Options
365

366
```python
367
basemap_options = {
368
    'opacity': 1.0,           # Layer opacity (0-1)
369
    'attribution': 'Custom',   # Attribution text
370
    'max_zoom': 18,           # Maximum zoom level
371
    'min_zoom': 0,            # Minimum zoom level
372
    'tms': False,             # TMS tile ordering
373
    'show': True              # Initially visible
374
}
375
```
376

377
### Advanced Options
378

379
```python
380
advanced_options = {
381
    'subdomains': ['a', 'b', 'c'],  # Tile server subdomains
382
    'format': 'png',                # Tile format
383
    'tile_size': 256,               # Tile size in pixels
384
    'zoomOffset': 0,                # Zoom level offset
385
    'detectRetina': True,           # High DPI display support
386
    'crossOrigin': False            # CORS settings
387
}
388
```
389

390
### WMS Specific Options
391

392
```python
393
wms_options = {
394
    'layers': 'layer_name',         # WMS layer names
395
    'styles': '',                   # WMS styles
396
    'format': 'image/png',          # Image format
397
    'transparent': True,            # Background transparency
398
    'version': '1.1.1',            # WMS version
399
    'crs': 'EPSG:3857',            # Coordinate reference system
400
    'uppercase': False              # Parameter case sensitivity
401
}
402
```
403

404
## Provider Information
405

406
### Attribution Requirements
407

408
All basemap providers have specific attribution requirements. Leafmap automatically includes proper attribution for built-in providers:
409

410
- **OpenStreetMap**: © OpenStreetMap contributors
411
- **Google**: Map data ©2023 Google
412
- **Esri**: Source: Esri, Maxar, Earthstar Geographics
413
- **CartoDB**: © CartoDB, © OpenStreetMap contributors
414
- **Stamen**: Map tiles by Stamen Design, under CC BY 3.0
415

416
### Usage Policies
417

418
Different providers have varying usage policies:
419
- **OpenStreetMap**: Open usage with attribution
420
- **Google**: Requires API key for heavy usage
421
- **Esri**: Terms of service apply
422
- **Commercial providers**: May require subscription
423

424
### Performance Considerations
425

426
- **Tile caching**: Most providers cache tiles for performance
427
- **Rate limiting**: Some providers limit request frequency
428
- **Regional availability**: Some services may be region-restricted
429
- **Quality variations**: Resolution and update frequency vary by provider