0
# Geographic Charts
1

2
Map-based visualizations for geographic and spatial data analysis. pyecharts provides comprehensive mapping capabilities with support for multiple map providers, custom geographic coordinates, and over 400 built-in map files for countries, provinces, and cities.
3

4
## Capabilities
5

6
### Choropleth Maps
7

8
Geographic maps with regions colored by data values, ideal for visualizing regional statistics and geographic distributions.
9

10
```python { .api }
11
class Map:
12
    def __init__(self, init_opts=None, render_opts=None):
13
        """
14
        Initialize a choropleth map.
15
        
16
        Args:
17
            init_opts (InitOpts, optional): Chart initialization options
18
            render_opts (RenderOpts, optional): Rendering options
19
        """
20

21
    def add(self, series_name, data_pair, maptype="china", **kwargs):
22
        """
23
        Add choropleth map data.
24
        
25
        Args:
26
            series_name (str): Name of the data series
27
            data_pair (list): List of [region_name, value] pairs or MapItem objects
28
            maptype (str): Map type identifier ("china", "world", province names, etc.)
29
            is_roam (bool, optional): Enable pan and zoom
30
            zoom (float, optional): Initial zoom level
31
            center (list, optional): Map center coordinates [longitude, latitude]
32
            is_map_symbol_show (bool, optional): Show map symbols
33
            
34
        Returns:
35
            Map: Self for method chaining
36
        """
37
```
38

39
**Usage Example:**
40
```python
41
from pyecharts.charts import Map
42
from pyecharts import options as opts
43

44
data = [
45
    ("北京", 199),
46
    ("上海", 188),
47
    ("广东", 150),
48
    ("江苏", 139),
49
    ("浙江", 134)
50
]
51

52
map_chart = (
53
    Map()
54
    .add("销售额", data, "china")
55
    .set_global_opts(
56
        title_opts=opts.TitleOpts(title="中国各省份销售额"),
57
        visualmap_opts=opts.VisualMapOpts(max_=200)
58
    )
59
)
60
```
61

62
### Geographic Coordinate Charts
63

64
Scatter plots and other visualizations on geographic coordinate systems.
65

66
```python { .api }
67
class Geo:
68
    def __init__(self, init_opts=None, render_opts=None):
69
        """
70
        Initialize a geographic coordinate chart.
71
        
72
        Args:
73
            init_opts (InitOpts, optional): Chart initialization options
74
            render_opts (RenderOpts, optional): Rendering options
75
        """
76

77
    def add_coordinate(self, name, longitude, latitude):
78
        """
79
        Add custom geographic coordinates.
80
        
81
        Args:
82
            name (str): Location name
83
            longitude (float): Longitude coordinate
84
            latitude (float): Latitude coordinate
85
            
86
        Returns:
87
            Geo: Self for method chaining
88
        """
89

90
    def add(self, series_name, data_pair, **kwargs):
91
        """
92
        Add geographic data series.
93
        
94
        Args:
95
            series_name (str): Name of the data series
96
            data_pair (list): List of [location_name, value] pairs or GeoItem objects
97
            type_ (str): Chart type ("scatter", "effectScatter", "heatmap", "lines")
98
            symbol (str, optional): Symbol type for scatter plots
99
            symbol_size (int|list, optional): Symbol size
100
            is_roam (bool, optional): Enable pan and zoom
101
            maptype (str, optional): Map type identifier
102
            
103
        Returns:
104
            Geo: Self for method chaining
105
        """
106
```
107

108
### Baidu Maps Integration
109

110
Integration with Baidu Maps for web-based interactive mapping with street-level detail.
111

112
```python { .api }
113
class BMap:
114
    def __init__(self, init_opts=None, render_opts=None):
115
        """
116
        Initialize a Baidu map chart.
117
        
118
        Args:
119
            init_opts (InitOpts, optional): Chart initialization options
120
            render_opts (RenderOpts, optional): Rendering options
121
        """
122

123
    def add(self, series_name, data_pair, **kwargs):
124
        """
125
        Add data to Baidu map.
126
        
127
        Args:
128
            series_name (str): Name of the data series
129
            data_pair (list): List of [location_name, value] pairs
130
            type_ (str): Chart type ("scatter", "effectScatter", "heatmap", "lines")
131
            is_roam (bool, optional): Enable map interaction
132
            map_style (dict, optional): Baidu map styling options
133
            
134
        Returns:
135
            BMap: Self for method chaining
136
        """
137

138
    def add_schema(self, **kwargs):
139
        """
140
        Configure Baidu map settings.
141
        
142
        Args:
143
            baidu_ak (str): Baidu API key
144
            center (list): Map center coordinates [longitude, latitude]
145
            zoom (int): Initial zoom level
146
            is_roam (bool): Enable pan and zoom
147
            map_style (dict): Map styling configuration
148
            
149
        Returns:
150
            BMap: Self for method chaining
151
        """
152
```
153

154
### Google Maps Integration
155

156
Integration with Google Maps for global mapping capabilities.
157

158
```python { .api }
159
class GMap:
160
    def __init__(self, init_opts=None, render_opts=None):
161
        """
162
        Initialize a Google map chart.
163
        
164
        Args:
165
            init_opts (InitOpts, optional): Chart initialization options
166
            render_opts (RenderOpts, optional): Rendering options
167
        """
168

169
    def add(self, series_name, data_pair, **kwargs):
170
        """
171
        Add data to Google map.
172
        
173
        Args:
174
            series_name (str): Name of the data series
175
            data_pair (list): List of [location_name, value] pairs
176
            type_ (str): Chart type ("scatter", "effectScatter", "heatmap", "lines")
177
            is_roam (bool, optional): Enable map interaction
178
            
179
        Returns:
180
            GMap: Self for method chaining
181
        """
182

183
    def add_schema(self, **kwargs):
184
        """
185
        Configure Google map settings.
186
        
187
        Args:
188
            google_api_key (str): Google Maps API key
189
            center (list): Map center coordinates [longitude, latitude]
190
            zoom (int): Initial zoom level
191
            map_type (str): Map type ("roadmap", "satellite", "hybrid", "terrain")
192
            
193
        Returns:
194
            GMap: Self for method chaining
195
        """
196
```
197

198
### Alibaba Maps Integration
199

200
Integration with Alibaba's AMap (Gaode Maps) service.
201

202
```python { .api }
203
class AMap:
204
    def __init__(self, init_opts=None, render_opts=None):
205
        """
206
        Initialize an Alibaba map chart.
207
        
208
        Args:
209
            init_opts (InitOpts, optional): Chart initialization options
210
            render_opts (RenderOpts, optional): Rendering options
211
        """
212

213
    def add(self, series_name, data_pair, **kwargs):
214
        """
215
        Add data to Alibaba map.
216
        
217
        Args:
218
            series_name (str): Name of the data series
219
            data_pair (list): List of [location_name, value] pairs
220
            type_ (str): Chart type ("scatter", "effectScatter", "heatmap", "lines")
221
            
222
        Returns:
223
            AMap: Self for method chaining
224
        """
225
```
226

227
### Leaflet Maps Integration
228

229
Integration with Leaflet for customizable web mapping.
230

231
```python { .api }
232
class LMap:
233
    def __init__(self, init_opts=None, render_opts=None):
234
        """
235
        Initialize a Leaflet map chart.
236
        
237
        Args:
238
            init_opts (InitOpts, optional): Chart initialization options
239
            render_opts (RenderOpts, optional): Rendering options
240
        """
241

242
    def add(self, series_name, data_pair, **kwargs):
243
        """
244
        Add data to Leaflet map.
245
        
246
        Args:
247
            series_name (str): Name of the data series
248
            data_pair (list): List of [location_name, value] pairs
249
            type_ (str): Chart type ("scatter", "effectScatter", "heatmap", "lines")
250
            
251
        Returns:
252
            LMap: Self for method chaining
253
        """
254
```
255

256
## Geographic Data Types
257

258
```python { .api }
259
class MapItem:
260
    def __init__(self, name=None, value=None, **kwargs):
261
        """
262
        Map data item for choropleth maps.
263
        
264
        Args:
265
            name (str): Region name
266
            value (numeric): Data value
267
            **kwargs: Additional styling options
268
        """
269

270
class GeoItem:
271
    def __init__(self, name=None, value=None, **kwargs):
272
        """
273
        Geographic coordinate data item.
274
        
275
        Args:
276
            name (str): Location name
277
            value (numeric): Data value
278
            **kwargs: Additional styling options
279
        """
280
```
281

282
## Geographic Configuration Options
283

284
```python { .api }
285
class GeoRegionsOpts:
286
    def __init__(self, **kwargs):
287
        """
288
        Geographic region styling options.
289
        
290
        Args:
291
            name (str): Region name
292
            itemstyle_opts (ItemStyleOpts): Region styling
293
            label_opts (LabelOpts): Region label options
294
            emphasis_opts (EmphasisOpts): Hover/focus styling
295
        """
296

297
class BMapCopyrightTypeOpts:
298
    def __init__(self, **kwargs):
299
        """Baidu map copyright configuration."""
300

301
class BMapGeoLocationControlOpts:
302
    def __init__(self, **kwargs):
303
        """Baidu map geolocation control options."""
304

305
class BMapNavigationControlOpts:
306
    def __init__(self, **kwargs):
307
        """Baidu map navigation control options."""
308

309
class BMapOverviewMapControlOpts:
310
    def __init__(self, **kwargs):
311
        """Baidu map overview control options."""
312

313
class BMapScaleControlOpts:
314
    def __init__(self, **kwargs):
315
        """Baidu map scale control options."""
316

317
class BMapTypeControlOpts:
318
    def __init__(self, **kwargs):
319
        """Baidu map type selection control options."""
320
```
321

322
## Geographic Data Management
323

324
pyecharts includes comprehensive geographic data support:
325

326
```python { .api }
327
# Geographic data dictionaries (from pyecharts.datasets)
328
FILENAMES  # FuzzyDict containing map filename mappings
329
COORDINATES  # FuzzyDict containing city coordinate mappings
330

331
# Registration functions for custom geographic data
332
def register_url(asset_url):
333
    """
334
    Register external map asset URLs.
335
    
336
    Args:
337
        asset_url (str): Base URL for map assets
338
    """
339

340
def register_files(asset_files):
341
    """
342
    Register custom map files.
343
    
344
    Args:
345
        asset_files (dict): Mapping of region names to filenames
346
    """
347

348
def register_coords(coords):
349
    """
350
    Register custom coordinates.
351
    
352
    Args:
353
        coords (dict): Mapping of location names to [longitude, latitude] pairs
354
    """
355
```
356

357
**Usage Example:**
358
```python
359
from pyecharts.datasets import register_coords
360

361
# Add custom coordinates
362
custom_coords = {
363
    "Custom Location": [116.46, 39.92],
364
    "Another Place": [121.48, 31.22]
365
}
366
register_coords(custom_coords)
367
```
368

369
## Available Map Types
370

371
pyecharts includes over 400 built-in map files:
372

373
- **World**: Global country maps
374
- **China**: National, provincial, and city-level maps  
375
- **International**: Maps for major countries and regions
376
- **Historical**: Historical boundary maps
377
- **Special**: Administrative regions, economic zones
378

379
Common map type identifiers:
380
- `"china"` - China national map
381
- `"world"` - World map
382
- `"北京"` - Beijing city map
383
- `"广东"` - Guangdong province map
384
- `"USA"` - United States map
385
- `"UK"` - United Kingdom map