{"id":6612,"library":"earthengine-api","title":"Earth Engine Python API","description":"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.","status":"active","version":"1.7.22","language":"en","source_language":"en","source_url":"https://github.com/google/earthengine-api","tags":["geospatial","satellite imagery","remote sensing","earth observation","GIS","cloud computing","Google Earth Engine"],"install":[{"cmd":"pip install earthengine-api","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge earthengine-api","lang":"bash","label":"Conda (recommended)"}],"dependencies":[{"reason":"Required Python version.","package":"python","version":">=3.10"},{"reason":"The `gcloud` CLI is often used for initial authentication and project setup.","package":"google-cloud-sdk","optional":true}],"imports":[{"note":"The canonical import is 'import ee'. Direct import from the package structure is not typical for the main client library object.","wrong":"from earthengine_api import ee","symbol":"ee","correct":"import ee"}],"quickstart":{"code":"import ee\nimport os\n\n# IMPORTANT: Replace 'your-earthengine-project-id' with your actual Google Cloud Project ID.\n# This project must have the Earth Engine API enabled.\n# If running in Colab or a local environment with gcloud SDK, ee.Authenticate() will open a browser for login.\n# For service account authentication, set GOOGLE_APPLICATION_CREDENTIALS env var.\n\nproject_id = os.environ.get('EE_PROJECT', 'your-earthengine-project-id')\n\ntry:\n    ee.Authenticate()\n    ee.Initialize(project=project_id, opt_url='https://earthengine-api.googleapis.com')\n    print('Earth Engine initialized successfully.')\n    \n    # Example: Load a Landsat 8 image collection and print its size.\n    collection = ee.ImageCollection('LANDSAT/LC08/C01/T1_SR')\\\n                     .filterDate('2020-01-01', '2020-01-31')\n    \n    # All Earth Engine operations are server-side. To get a client-side value,\n    # use .getInfo(). Be mindful of data size when using getInfo().\n    print(f'Collection size: {collection.size().getInfo()}')\n    \nexcept ee.EEException as e:\n    print(f'Earth Engine initialization failed: {e}')\n    print('Please ensure you have registered for Earth Engine access, enabled the API for your Google Cloud Project, and authenticated.')\n    print('Refer to https://developers.google.com/earth-engine/guides/getstarted for setup instructions.')\nexcept Exception as e:\n    print(f'An unexpected error occurred: {e}')","lang":"python","description":"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."},"warnings":[{"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']`).","message":"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.","severity":"breaking","affected_versions":"<=0.1.242 and potentially later for auth updates"},{"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.","message":"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'.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}