Earth Engine Python API

1.7.22 · active · verified Wed Apr 15

The Earth Engine Python API provides client libraries for interacting with Google Earth Engine, a planetary-scale cloud-based platform for geospatial analysis. It offers access to a multi-petabyte catalog of satellite imagery and other geospatial datasets, enabling users to perform complex analyses like detecting changes, mapping trends, and quantifying differences on the Earth's surface. The API is in active development, with frequent updates.

Warnings

breaking Major changes to authentication mechanisms and the underlying API have occurred, particularly around November 2020 (v0.1.242) and subsequent updates up to March 2026. This includes removal of `use_cloud_api` and `data.startProcessing`, and shifts to the v1 API for asset property access.
Fix: Ensure your `earthengine-api` library is updated (`pip install --upgrade earthengine-api`). Re-authenticate using `ee.Authenticate()` and update `ee.Initialize()` to explicitly pass a `project` ID. Adjust code accessing asset properties (e.g., `my_asset['properties']['title']`).
gotcha Forgetting to call `ee.Authenticate()` and `ee.Initialize(project='your-project-id')` at the beginning of a script or session is a common error. This often results in 'Google Earth Engine API has not been used in project...' or 'Caller does not have required permission'.
Fix: Always include `ee.Authenticate()` (for interactive login) and `ee.Initialize(project='YOUR_CLOUD_PROJECT_ID')`. Ensure your Google Cloud Project has the Earth Engine API enabled and your account is registered for Earth Engine access.
gotcha Confusing client-side (Python) operations with server-side (Earth Engine) operations. Earth Engine objects are computational graphs executed on Google's servers. Attempting to use Python functions directly on `ee.Object` instances without resolving them with `.getInfo()` will lead to errors (e.g., 'Cannot concatenate 'str' and 'ComputedObject' objects'). Using `.getInfo()` on large objects can also lead to browser locking or memory issues, especially within loops.
Fix: Understand when an operation is client-side vs. server-side. Use `.getInfo()` only when you need to bring data to the client and be mindful of the data volume. Avoid calling `.getInfo()` inside `for` loops or mapped functions. Optimize server-side computations before fetching results.
gotcha Hitting server-side computation limits, such as 'User memory limit exceeded' or 'Too many concurrent aggregations'. This usually occurs with highly nested mapped functions or complex reductions over large datasets.
Fix: Optimize your Earth Engine scripts. Filter data (spatial, temporal, spectral) early, combine reducers, and consider adjusting the `tileScale` parameter in computations. Review the debugging guide and optimization tips in the official documentation.

Install

pip install earthengine-api PyPI
conda install -c conda-forge earthengine-api Conda (recommended)

Imports

ee
wrong:
```
from earthengine_api import ee
```
correct:
```
import ee
```
The canonical import is 'import ee'. Direct import from the package structure is not typical for the main client library object.

Quickstart

This quickstart demonstrates how to authenticate, initialize the Earth Engine API, and perform a basic operation (loading an image collection and getting its size). Users must replace `your-earthengine-project-id` with their actual Google Cloud Project ID, which needs to have the Earth Engine API enabled and registered for use.

import ee
import os

# IMPORTANT: Replace 'your-earthengine-project-id' with your actual Google Cloud Project ID.
# This project must have the Earth Engine API enabled.
# If running in Colab or a local environment with gcloud SDK, ee.Authenticate() will open a browser for login.
# For service account authentication, set GOOGLE_APPLICATION_CREDENTIALS env var.

project_id = os.environ.get('EE_PROJECT', 'your-earthengine-project-id')

try:
    ee.Authenticate()
    ee.Initialize(project=project_id, opt_url='https://earthengine-api.googleapis.com')
    print('Earth Engine initialized successfully.')
    
    # Example: Load a Landsat 8 image collection and print its size.
    collection = ee.ImageCollection('LANDSAT/LC08/C01/T1_SR')\
                     .filterDate('2020-01-01', '2020-01-31')
    
    # All Earth Engine operations are server-side. To get a client-side value,
    # use .getInfo(). Be mindful of data size when using getInfo().
    print(f'Collection size: {collection.size().getInfo()}')
    
except ee.EEException as e:
    print(f'Earth Engine initialization failed: {e}')
    print('Please ensure you have registered for Earth Engine access, enabled the API for your Google Cloud Project, and authenticated.')
    print('Refer to https://developers.google.com/earth-engine/guides/getstarted for setup instructions.')
except Exception as e:
    print(f'An unexpected error occurred: {e}')

view raw JSON →