0
# Geemap
1

2
A comprehensive Python package for interactive geospatial analysis and visualization with Google Earth Engine (GEE). Geemap bridges the gap between GEE's JavaScript API and Python's scientific computing ecosystem, providing interactive mapping capabilities within Jupyter environments and supporting multiple mapping backends (ipyleaflet, folium, plotly, kepler.gl, pydeck, maplibre).
3

4
## Package Information
5

6
- **Package Name**: geemap
7
- **Language**: Python
8
- **Installation**: `pip install geemap`
9
- **Documentation**: https://geemap.org
10

11
## Core Imports
12

13
```python
14
import geemap
15
```
16

17
For working with maps:
18

19
```python
20
# Main Map class (backend depends on USE_FOLIUM environment variable)
21
from geemap import Map
22

23
# Specific backend imports if needed
24
from geemap.geemap import Map as IPyLeafletMap  # ipyleaflet backend
25
from geemap.foliumap import Map as FoliumMap    # folium backend
26
```
27

28
## Basic Usage
29

30
```python
31
import geemap
32
import ee
33

34
# Initialize Earth Engine
35
ee.Initialize()
36

37
# Create an interactive map
38
m = geemap.Map(center=[40, -100], zoom=4)
39

40
# Add Earth Engine data
41
dataset = ee.ImageCollection('USDA/NAIP/DOQQ')
42
trueColorVis = {
43
    'min': 0,
44
    'max': 255,
45
    'bands': ['R', 'G', 'B']
46
}
47
m.addLayer(dataset, trueColorVis, 'True Color')
48

49
# Display the map
50
m
51
```
52

53
## Architecture
54

55
Geemap uses a modular architecture with conditional imports:
56

57
- **Backend Selection**: Automatically chooses between ipyleaflet and folium based on `USE_FOLIUM` environment variable
58
- **Core Module**: Provides abstract base classes and common functionality shared across backends
59
- **Backend Modules**: Specific implementations for different mapping libraries
60
- **Utility Modules**: Extensive collection of helper functions for data processing, conversion, and Earth Engine integration
61
- **Widget System**: Interactive components for legends, toolbars, layer management, and data inspection
62

63
## Capabilities
64

65
### Interactive Mapping
66

67
Core mapping functionality with multiple backend support, providing interactive visualization capabilities for geospatial data with Earth Engine integration.
68

69
```python { .api }
70
class Map:
71
    def __init__(self, **kwargs) -> None:
72
        """
73
        Initialize the map with given keyword arguments.
74
        
75
        Args:
76
            **kwargs: Additional keyword arguments for the map including:
77
                center (list, optional): Center of the map (lat, lon). Defaults to [0, 0].
78
                zoom (int, optional): Zoom level of the map. Defaults to 2.
79
                height (str, optional): Height of the map. Defaults to "600px".
80
                width (str, optional): Width of the map. Defaults to "100%".
81
                basemap: Basemap to use. Defaults to first available basemap.
82
        """
83

84
    def add_layer(self, ee_object, vis_params=None, name=None, shown=True, opacity=1.0):
85
        """
86
        Adds a layer to the map.
87
        
88
        Args:
89
            ee_object: The Earth Engine object to add as a layer.
90
            vis_params (dict, optional): Visualization parameters. Defaults to None.
91
            name (str, optional): Name of the layer. Defaults to None.
92
            shown (bool, optional): Whether the layer is shown. Defaults to True.
93
            opacity (float, optional): Opacity of the layer. Defaults to 1.0.
94
        """
95

96
    def center_object(self, ee_object, zoom=None):
97
        """
98
        Centers the map on an Earth Engine object.
99
        
100
        Args:
101
            ee_object: The Earth Engine object to center on.
102
            zoom (int, optional): Zoom level. Defaults to None.
103
        """
104

105
    def set_center(self, lon, lat, zoom=None):
106
        """
107
        Sets the center and zoom of the map.
108
        
109
        Args:
110
            lon (float): Longitude of the center.
111
            lat (float): Latitude of the center.
112
            zoom (int, optional): Zoom level. Defaults to None.
113
        """
114

115
    # Aliases for Earth Engine JavaScript API compatibility
116
    addLayer = add_layer
117
    centerObject = center_object
118
    setCenter = set_center
119
```
120

121
[Interactive Mapping](./interactive-mapping.md)
122

123
### Data Export and Processing  
124

125
Comprehensive data export capabilities for Earth Engine assets to various formats and storage destinations including Google Drive, Cloud Storage, and local files.
126

127
```python { .api }
128
def ee_export_image(ee_object, filename, scale=None, crs=None, crs_transform=None, 
129
                   region=None, dimensions=None, file_per_band=False, 
130
                   format="ZIPPED_GEO_TIFF", unzip=True, unmask_value=None, 
131
                   timeout=300, proxies=None, verbose=True):
132
    """
133
    Exports an ee.Image as a GeoTIFF.
134
    
135
    Args:
136
        ee_object: The ee.Image to download.
137
        filename (str): Output filename for the exported image.
138
        scale (float, optional): Default scale for bands. Defaults to None.
139
        crs (str, optional): Default CRS string. Defaults to None.
140
        crs_transform (list, optional): Default affine transform. Defaults to None.
141
        region: Polygon specifying region to download. Defaults to None.
142
        dimensions (list, optional): Width and height for cropping. Defaults to None.
143
        file_per_band (bool, optional): Produce different GeoTIFF per band. Defaults to False.
144
        format (str, optional): Export format. Defaults to "ZIPPED_GEO_TIFF".
145
        unzip (bool, optional): Whether to unzip downloaded file. Defaults to True.
146
        unmask_value (float, optional): Value for masked pixels. Defaults to None.
147
        timeout (int, optional): Request timeout in seconds. Defaults to 300.
148
        proxies (dict, optional): Proxy servers to use. Defaults to None.
149
        verbose (bool, optional): Whether to print descriptive text. Defaults to True.
150
    """
151

152
def ee_export_image_to_drive(image, description="myExportImageTask", folder=None, 
153
                            fileNamePrefix=None, dimensions=None, region=None, 
154
                            scale=None, crs=None, crsTransform=None, maxPixels=None, 
155
                            shardSize=None, fileDimensions=None, skipEmptyTiles=None, 
156
                            fileFormat=None, formatOptions=None, priority=None, **kwargs):
157
    """
158
    Exports an Earth Engine Image to Google Drive.
159
    
160
    Args:
161
        image: The ee.Image to export.
162
        description (str, optional): Task description. Defaults to "myExportImageTask".
163
        folder (str, optional): Drive folder name. Defaults to None.
164
        fileNamePrefix (str, optional): Name prefix for exported file. Defaults to None.
165
        dimensions: Dimensions for export. Defaults to None.
166
        region: Export region. Defaults to None.
167
        scale (float, optional): Export scale. Defaults to None.
168
        crs (str, optional): CRS for export. Defaults to None.
169
        crsTransform: CRS transform. Defaults to None.
170
        maxPixels: Maximum pixels. Defaults to None.
171
        shardSize: Shard size. Defaults to None.
172
        fileDimensions: File dimensions. Defaults to None.
173
        skipEmptyTiles: Skip empty tiles. Defaults to None.
174
        fileFormat: File format. Defaults to None.
175
        formatOptions: Format options. Defaults to None.
176
        priority (int, optional): Task priority. Defaults to None.
177
        **kwargs: Additional keyword arguments.
178
    """
179

180
def ee_export_vector_to_drive(collection, description="myExportTableTask", 
181
                             folder=None, fileNamePrefix=None, fileFormat=None, 
182
                             selectors=None, maxVertices=None, **kwargs):
183
    """
184
    Exports an Earth Engine FeatureCollection to Google Drive.
185
    
186
    Args:
187
        collection: The ee.FeatureCollection to export.
188
        description (str, optional): Task description. Defaults to "myExportTableTask".
189
        folder (str, optional): Drive folder name. Defaults to None.
190
        fileNamePrefix (str, optional): Name prefix for exported file. Defaults to None.
191
        fileFormat (str, optional): Export file format. Defaults to None.
192
        selectors: Property selectors. Defaults to None.
193
        maxVertices: Maximum vertices per feature. Defaults to None.
194
        **kwargs: Additional keyword arguments.
195
    """
196
```
197

198
[Data Export and Processing](./data-export.md)
199

200
### Earth Engine Integration
201

202
Specialized tools and utilities for working with Google Earth Engine, including tile layer creation, authentication, and API integration.
203

204
```python { .api }
205
def ee_tile_layer(ee_object, vis_params: Dict = {}, name: str = "Layer", shown: bool = True, opacity: float = 1.0) -> ipyleaflet.TileLayer: ...
206
def ee_initialize(token_name: str = "EARTHENGINE_TOKEN", **kwargs) -> None: ...
207
```
208

209
[Earth Engine Integration](./earth-engine.md)
210

211
### Data Conversion and Utilities
212

213
Extensive collection of utility functions for data format conversion, file operations, and geospatial data processing.
214

215
```python { .api }
216
def csv_to_geojson(in_csv: str, out_geojson: str = None, latitude: str = "latitude", longitude: str = "longitude") -> None: ...
217
def shp_to_geojson(in_shp: str, out_geojson: str = None) -> None: ...
218
def download_from_url(url: str, out_file_name: str = None, out_dir: str = ".", unzip: bool = True) -> str: ...
219
```
220

221
[Data Conversion and Utilities](./data-conversion.md)
222

223
### Visualization and Plotting
224

225
Advanced visualization tools including charts, plots, legends, and timelapse animations for geospatial data analysis.
226

227
```python { .api }
228
def bar_chart(data, x: str, y: str, **kwargs) -> None: ...
229
def line_chart(data, x: str, y: str, **kwargs) -> None: ...
230
def create_timeseries(ee_object, region: ee.Geometry, start_date: str, end_date: str) -> None: ...
231
```
232

233
[Visualization and Plotting](./visualization.md)
234

235
### Interactive Widgets and Tools
236

237
Rich collection of interactive widgets for map controls, data inspection, layer management, and custom toolbars.
238

239
```python { .api }
240
class LayerManager:
241
    def __init__(self, map_object) -> None: ...
242

243
class Inspector:
244
    def __init__(self, map_object) -> None: ...
245

246
class Toolbar:
247
    def __init__(self, map_object) -> None: ...
248
```
249

250
[Interactive Widgets and Tools](./widgets-tools.md)
251

252
### AI and Machine Learning
253

254
AI-powered features including the Genie assistant widget and machine learning utilities for Earth Engine classifiers.
255

256
```python { .api }
257
class Genie:
258
    def __init__(self) -> None: ...
259

260
def fc_to_classifier(features: ee.FeatureCollection, classifier: str = "RandomForest") -> ee.Classifier: ...
261
```
262

263
[AI and Machine Learning](./ai-ml.md)
264

265
## Environment Configuration
266

267
```python { .api }
268
def use_folium():
269
    """
270
    Whether to use the folium or ipyleaflet plotting backend.
271
    
272
    Returns:
273
        bool: True if USE_FOLIUM environment variable is set, False otherwise.
274
    """
275

276
def in_colab_shell():
277
    """
278
    Tests if the code is being executed within Google Colab.
279
    
280
    Returns:
281
        bool: True if running in Google Colab, False otherwise.
282
    """
283
```
284

285
**Environment Variables:**
286
- `USE_FOLIUM`: Set to use folium backend instead of ipyleaflet
287
- `USE_EEREPR`: Control Earth Engine object representation (enabled by default)
288

289
## Package Metadata
290

291
```python { .api }
292
__version__ = "0.36.2"
293
__author__ = "Qiusheng Wu"
294
__email__ = "giswqs@gmail.com"
295
```