5. GEE Python API and geemap (5 min)¶
In the last sub-module Introduction to Google Earth Engine (GEE) (5 min) we discussed 2 key ways to access and analyze data in GEE: 1) through the code editor and 2) the Python API.
Here we’ll describe the API.
5.1. Python API¶
5.1.1. Google Colab Python API¶
Relative to the JavaScript API and the code editor, documentation on the Python API is rather limited. The good news is that through use of two key Python modules, earthengine-api and geemap you can get much of the funcationality as in the code editor even if you have to use the JavaScript documentation as a primary reference as to how many of the data structures and algorithms work.
5.2. geemap¶
geemap enables users to analyze and visualize GEE datasets interactively – including within a Jupyter environment.
The key functionality of geemap is organized into several modules [Wu20]:
geemap: the main module for interactive mapping with Google Earth Engine, ipyleaflet, and ipywidgets.eefolium: a module for interactive mapping with Earth Engine and folium. It is designed for users to run geemap with Google Colab. (Note: Google colab doesnt currently integrate with ipyleaflet)conversion: utilities for automatically converting Earth Engine JavaScripts to Python scripts and Jupyter notebooks.basemaps: a module for adding various XYZ and WMS tiled basemaps.legends: a module for adding customized legends to interactive maps.
5.2.1. Getting started¶
geemap is not included in the standard Python library, which means you must download and install it. Unlike jupyter however, geemap is not in the main conda repository so we will install it from the conda-forge channel. We will also install and use a package installer called mamba that makes installing geemp much faster.
So, to install geemap in conda:
activate your env:
$ conda activate onlinstall mamba via conda-forge:
$ conda install mamba -c conda-forgeinstall geemap via mamba:
$ mamba install geemap -c conda-forge
As noted before, you only need to install these packages into your environment once. After that, for each session (in each notebook) you just need to:
import geemap
We are going to use Python’s try and except method to install a package if it is not already imported. This way we include this code in every notebook and the package will be imported if its already installed and if not, it will install it first.
NOTE 1 since we are making these notebooks available in Google Colab, we will use pip to intsall packages if this notebook is running as a Colab instance.
NOTE 2 if you install these libraries in a Google Colab session you will be prompted to restart your kernel in order to import the libraries.
try:
import geemap
except ModuleNotFoundError:
if 'google.colab' in str(get_ipython()):
print("package not found, installing w/ pip in Google Colab...")
!pip install geemap
else:
print("package not found, installing w/ conda...")
!conda install mamba -c conda-forge -y
!mamba install geemap -c conda-forge -y
import geemap
With geemap imported, your Python session or Jupyter notebook is now ready to call on the entire library of GEE images/image collections, etc, and will have the same functionality as the code editor in the GEE console.
Here is a partial list of those functions:
Automated conversion from Earth Engine JavaScripts to Python scripts and Jupyter notebooks.
Displaying Earth Engine data layers for interactive mapping.
Supporting Earth Engine JavaScript API-styled functions in Python, such as Map.addLayer(), Map.setCenter(), Map.centerObject(), Map.setOptions().
Creating split-panel maps with Earth Engine data.
Retrieving Earth Engine data interactively using the Inspector Tool.
Interactive plotting of Earth Engine data by simply clicking on the map.
Converting data format between GeoJSON and Earth Engine.
Using drawing tools to interact with Earth Engine data.
Using shapefiles with Earth Engine without having to upload data to one’s GEE account.
Exporting Earth Engine FeatureCollection to other formats (i.e., shp, csv, json, kml, kmz) using only one line of code.
Exporting Earth Engine Image and ImageCollection as GeoTIFF.
Extracting pixels from an Earth Engine Image into a 3D numpy array.
Calculating zonal statistics by group (e.g., calculating land over composition of each state/country).
Adding a customized legend for Earth Engine data.
Converting Earth Engine JavaScripts to Python code directly within Jupyter notebook.
Adding animated text to GIF images generated from Earth Engine data.
Adding colorbar and images to GIF animations generated from Earth Engine data.
Creating Landsat time lapse animations with animated text using Earth Engine.
Searching places and datasets from Earth Engine Data Catalog.
Using time series inspector to visualize landscape changes over time.
Exporting Earth Engine maps as HTML files and PNG images.
Searching Earth Engine API documentation within Jupyter notebooks.
Importing Earth Engine assets from personal account.
Publishing interactive GEE maps directly within Jupyter notebook.
Adding local raster datasets (e.g., GeoTIFF) to the map.