{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/worldbank/OpenNightLights/blob/master/onl/tutorials/mod2_5_GEE_PythonAPI_and_geemap.ipynb)\n", "\n", "\n", "# GEE Python API and geemap (5 min)\n", "\n", "In the last sub-module {doc}`mod2_4_introduction_to_GEE` we discussed 2 key ways to access and analyze data in GEE: 1) through the code editor and 2) the Python API.\n", "\n", "Here we'll describe the API.\n", "\n", "## Python API\n", "
\n", "GEE does provide some overview and documentation on the Python API.
\n", "\n", "### Google Colab Python API\n", "
\n", "Google also provides a guide for using the Python API in a Google Colab notebook.
\n", " \n", "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.\n", " \n", "## geemap\n", "\n", "
\n", "geemap is a Python package for interactive mapping with GEE.\n", "
\n", "\n", "`geemap` enables users to analyze and visualize GEE datasets interactively -- including within a Jupyter environment.\n", "\n", "The key functionality of `geemap` is organized into several modules {cite}`wu2020geemap`: \n", "- `geemap`: the main module for interactive mapping with Google Earth Engine, ipyleaflet, and ipywidgets.\n", "- `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)\n", "- `conversion`: utilities for automatically converting Earth Engine JavaScripts to Python scripts and Jupyter notebooks.\n", "- `basemaps`: a module for adding various XYZ and WMS tiled basemaps.\n", "- `legends`: a module for adding customized legends to interactive maps.\n", "\n", "### Getting started\n", "`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.\n", "\n", "So, to install `geemap` in conda:\n", "1. activate your env: `$ conda activate onl`\n", "2. install mamba via conda-forge: `$ conda install mamba -c conda-forge`\n", "3. install geemap via mamba: `$ mamba install geemap -c conda-forge`\n", "\n", "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:\n", "`import geemap`\n", "\n", "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.\n", "\n", "**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.\n", "\n", "**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." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "try:\n", " import geemap\n", "except ModuleNotFoundError:\n", " if 'google.colab' in str(get_ipython()):\n", " print(\"package not found, installing w/ pip in Google Colab...\")\n", " !pip install geemap\n", " else:\n", " print(\"package not found, installing w/ conda...\")\n", " !conda install mamba -c conda-forge -y\n", " !mamba install geemap -c conda-forge -y\n", " import geemap" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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. \n", "\n", "Here is a partial list of those functions:\n", "- Automated conversion from Earth Engine JavaScripts to Python scripts and Jupyter notebooks.\n", "- Displaying Earth Engine data layers for interactive mapping.\n", "- Supporting Earth Engine JavaScript API-styled functions in Python, such as Map.addLayer(), Map.setCenter(), Map.centerObject(), Map.setOptions().\n", "- Creating split-panel maps with Earth Engine data.\n", "- Retrieving Earth Engine data interactively using the Inspector Tool.\n", "- Interactive plotting of Earth Engine data by simply clicking on the map.\n", "- Converting data format between GeoJSON and Earth Engine.\n", "- Using drawing tools to interact with Earth Engine data.\n", "- Using shapefiles with Earth Engine without having to upload data to one’s GEE account.\n", "- Exporting Earth Engine FeatureCollection to other formats (i.e., shp, csv, json, kml, kmz) using only one line of code.\n", "- Exporting Earth Engine Image and ImageCollection as GeoTIFF.\n", "- Extracting pixels from an Earth Engine Image into a 3D numpy array.\n", "- Calculating zonal statistics by group (e.g., calculating land over composition of each state/country).\n", "- Adding a customized legend for Earth Engine data.\n", "- Converting Earth Engine JavaScripts to Python code directly within Jupyter notebook.\n", "- Adding animated text to GIF images generated from Earth Engine data.\n", "- Adding colorbar and images to GIF animations generated from Earth Engine data.\n", "- Creating Landsat time lapse animations with animated text using Earth Engine.\n", "- Searching places and datasets from Earth Engine Data Catalog.\n", "- Using time series inspector to visualize landscape changes over time.\n", "- Exporting Earth Engine maps as HTML files and PNG images.\n", "- Searching Earth Engine API documentation within Jupyter notebooks.\n", "- Importing Earth Engine assets from personal account.\n", "- Publishing interactive GEE maps directly within Jupyter notebook.\n", "- Adding local raster datasets (e.g., GeoTIFF) to the map.\n", "\n", "
\n", "Like many popular Python packages, geemap provides comprehensive and clear documentation.
\n", "\n", "
\n", "And examples and video tutorials.
\n", "\n", "## Google Colab\n", "\n", "
\n", "`geemap` has recently released a version that works well with Google Colabs. See here for an intro and tutorial about using `geemap` for Google Colab.\n", "
\n", "\n", "\n", "## References:\n", "```{bibliography} ../references.bib\n", ":filter: docname in docnames\n", "```" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "hide_input": false, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.9" }, "toc": { "base_numbering": 1, "nav_menu": {}, "number_sections": false, "sideBar": true, "skip_h1_title": false, "title_cell": "Table of Contents", "title_sidebar": "Contents", "toc_cell": false, "toc_position": {}, "toc_section_display": true, "toc_window_display": false } }, "nbformat": 4, "nbformat_minor": 4 }