0
# Basemap Integration
1

2
Functions for adding web or local basemaps to existing matplotlib axes with automatic coordinate handling, provider support, and custom styling options. These functions are the core of contextily's matplotlib integration.
3

4
## Capabilities
5

6
### Adding Basemaps
7

8
Add web or local tile basemaps to matplotlib axes with comprehensive customization options including zoom levels, tile sources, coordinate transformations, and visual styling.
9

10
```python { .api }
11
def add_basemap(ax, zoom='auto', source=None, interpolation='bilinear', 
12
               attribution=None, attribution_size=8, reset_extent=True, 
13
               crs=None, resampling=Resampling.bilinear, zoom_adjust=None, 
14
               **extra_imshow_args):
15
    """
16
    Add a (web/local) basemap to ax.
17

18
    Parameters:
19
    - ax: AxesSubplot - Matplotlib axes object (extent assumed to be EPSG:3857 unless crs specified)
20
    - zoom: int or 'auto' - Level of detail for basemap, calculated automatically if 'auto'
21
    - source: TileProvider, str, or None - Tile source (web provider, URL, or local file path)
22
    - interpolation: str - Interpolation algorithm for imshow ('bilinear', 'nearest', etc.)
23
    - attribution: str or None - Attribution text (defaults to source attribution)
24
    - attribution_size: int - Font size for attribution text (default 8)
25
    - reset_extent: bool - Whether to reset axes extent to original bounds
26
    - crs: str or CRS - Target coordinate reference system for warping
27
    - resampling: Resampling - Resampling method for warping operations
28
    - zoom_adjust: int - Adjustment to automatically calculated zoom level (-1 to 1 recommended)
29
    - **extra_imshow_args: Additional parameters passed to matplotlib's imshow
30

31
    Returns:
32
    None (modifies axes in-place)
33
    """
34
```
35

36
**Usage Examples:**
37

38
```python
39
import contextily as ctx
40
import matplotlib.pyplot as plt
41
import geopandas as gpd
42

43
# Add basemap to existing plot (data must be in Web Mercator EPSG:3857)
44
gdf = gpd.read_file('data.shp').to_crs(epsg=3857)
45
ax = gdf.plot(figsize=(10, 10), alpha=0.5, color='red')
46
ctx.add_basemap(ax, source=ctx.providers.Stamen.Toner)
47
plt.show()
48

49
# Use custom zoom level and different provider
50
ax = gdf.plot(figsize=(10, 10), alpha=0.5)
51
ctx.add_basemap(ax, zoom=12, source=ctx.providers.CartoDB.Positron)
52
plt.show()
53

54
# Add basemap with coordinate transformation (data in different CRS)
55
gdf_4326 = gpd.read_file('data.shp')  # WGS84 data
56
ax = gdf_4326.plot(figsize=(10, 10))
57
ctx.add_basemap(ax, crs=gdf_4326.crs, source=ctx.providers.OpenStreetMap.HOT)
58
plt.show()
59

60
# Use local raster file as basemap
61
ctx.add_basemap(ax, source='path/to/local_basemap.tif')
62

63
# Custom styling with additional imshow parameters
64
ctx.add_basemap(ax, alpha=0.7, cmap='gray', vmin=0, vmax=255)
65
```
66

67
### Attribution Management
68

69
Add or customize attribution text on matplotlib plots to properly credit tile providers and data sources.
70

71
```python { .api }
72
def add_attribution(ax, text, font_size=8, **kwargs):
73
    """
74
    Add attribution text to matplotlib axes.
75

76
    Parameters:
77
    - ax: AxesSubplot - Matplotlib axes object
78
    - text: str - Attribution text to display
79
    - font_size: int - Font size for attribution text (default 8)
80
    - **kwargs: Additional keyword arguments passed to matplotlib's text method
81

82
    Returns:
83
    matplotlib.text.Text - Text object added to the plot
84
    """
85
```
86

87
**Usage Examples:**
88

89
```python
90
import contextily as ctx
91
import matplotlib.pyplot as plt
92

93
fig, ax = plt.subplots(figsize=(10, 8))
94

95
# Add basemap without automatic attribution
96
ctx.add_basemap(ax, attribution=False)
97

98
# Add custom attribution
99
ctx.add_attribution(ax, "© Custom Data Source 2024", font_size=10)
100

101
# Add attribution with custom styling
102
ctx.add_attribution(ax, "Map data © OpenStreetMap contributors", 
103
                   font_size=12, color='blue', weight='bold')
104
plt.show()
105
```
106

107
## Provider Sources
108

109
### Web Tile Providers  
110

111
Access pre-configured tile providers through the `providers` object (re-exported from xyzservices):
112

113
```python
114
# Popular basemap providers
115
ctx.providers.OpenStreetMap.HOT          # Humanitarian OpenStreetMap
116
ctx.providers.Stamen.Toner              # Black and white map
117
ctx.providers.Stamen.Terrain            # Terrain with labels
118
ctx.providers.CartoDB.Positron          # Light colored basemap
119
ctx.providers.CartoDB.DarkMatter        # Dark themed basemap
120
ctx.providers.ESRI.WorldImagery         # Satellite imagery
121
```
122

123
### Custom Sources
124

125
```python
126
# Custom tile URL (placeholders: {x}, {y}, {z})
127
custom_url = "https://tiles.example.com/{z}/{x}/{y}.png"
128
ctx.add_basemap(ax, source=custom_url)
129

130
# TileProvider object for advanced configuration
131
from xyzservices import TileProvider
132
provider = TileProvider(
133
    url="https://tiles.example.com/{z}/{x}/{y}.png",
134
    attribution="© Example Tiles",
135
    name="ExampleTiles"
136
)
137
ctx.add_basemap(ax, source=provider)
138

139
# Local raster file
140
ctx.add_basemap(ax, source="/path/to/local/basemap.tif")
141
```
142

143
## Coordinate System Handling
144

145
### Automatic Projection (Default)
146

147
By default, `add_basemap` assumes axes are in Web Mercator (EPSG:3857):
148

149
```python  
150
# Data must be in EPSG:3857 for automatic handling
151
gdf_3857 = gdf.to_crs(epsg=3857)
152
ax = gdf_3857.plot()
153
ctx.add_basemap(ax)  # Works automatically
154
```
155

156
### Custom CRS Support
157

158
Use the `crs` parameter to work with data in other coordinate systems:
159

160
```python
161
# Data in WGS84 (EPSG:4326)
162
gdf_4326 = gpd.read_file('data.shp')
163
ax = gdf_4326.plot()
164
ctx.add_basemap(ax, crs=gdf_4326.crs)  # Handles transformation automatically
165

166
# Data in custom projection
167
gdf_custom = gdf.to_crs(epsg=32633)  # UTM Zone 33N
168
ax = gdf_custom.plot()  
169
ctx.add_basemap(ax, crs='EPSG:32633')
170
```
171

172
## Performance and Caching
173

174
### Zoom Level Optimization
175

176
```python
177
# Let contextily calculate optimal zoom
178
ctx.add_basemap(ax, zoom='auto')
179

180
# Fine-tune automatic zoom calculation  
181
ctx.add_basemap(ax, zoom='auto', zoom_adjust=1)  # One level higher detail
182
ctx.add_basemap(ax, zoom='auto', zoom_adjust=-1) # One level lower detail
183

184
# Manual zoom for performance control
185
ctx.add_basemap(ax, zoom=10)  # Fixed zoom level
186
```
187

188
### Caching and Performance
189

190
Tiles are automatically cached per Python session. Use `set_cache_dir()` for persistent caching:
191

192
```python
193
import contextily as ctx
194

195
# Set persistent cache directory
196
ctx.set_cache_dir('/path/to/cache')
197

198
# Now basemaps will use persistent cache
199
ctx.add_basemap(ax, source=ctx.providers.OpenStreetMap.HOT)
200
```
201

202
## Error Handling
203

204
Common issues and solutions:
205

206
```python
207
# Handle missing tiles gracefully
208
try:
209
    ctx.add_basemap(ax, source=ctx.providers.OpenStreetMap.HOT)
210
except Exception as e:
211
    print(f"Basemap failed: {e}")
212
    # Fallback to different provider or no basemap
213

214
# Check data CRS before adding basemap
215
if gdf.crs != 'EPSG:3857':
216
    print(f"Data CRS: {gdf.crs}, converting for basemap")
217
    gdf = gdf.to_crs(epsg=3857)
218
```