Tests PyPI version Python versions Conda-Forge version License

The Earth Engine Session Client is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through custom authentication.

Why This Package?

While Google Earth Engine applications can be created using a global service account, this approach has significant limitations: users cannot access their private GEE assets without making them public. This package solves this problem by handling custom authentication, allowing each user to access their own private assets securely.

Unlike the standard GEE API—which relies on a global session object and does not support multi-user environments—this client ensures that each session is authenticated and managed independently with user-specific credentials.

Each session is instantiated via the EESession class, which supports several credential sources — a service-account key, an EARTHENGINE_TOKEN environment variable, earthengine authenticate OAuth credentials, or Application Default Credentials. Once authenticated, the session exposes an operations property that provides easy access to key API methods.

Key Features

  • Custom User Authentication: Enable users to access their private GEE assets without requiring them to be public, solving the limitation of global service account approaches.

  • Multi-User Session Management: Encapsulate user-specific credentials and project data in independent EESession objects.

  • Enhanced API Operations: Access GEE functionalities via the operations property, which includes methods such as: - get_info: Retrieve detailed information about an Earth Engine object. - get_map_id: Generate a map ID for an Earth Engine image. - get_asset: Fetch information about a specific Earth Engine asset.

  • Seamless GEE Integration: Integrate custom methods into your existing Earth Engine workflow with minimal changes.

Installation

To install the package, simply use pip:

pip install ee-client

Usage

Initialization and Authentication

A session can be built from any standard Google/Earth Engine credential via factory constructors, each holding a live, refreshable credential:

from eeclient import EESession

# Service-account key (dict or path)
session = EESession.from_service_account("sa-key.json")

# EARTHENGINE_TOKEN env var, else ~/.config/earthengine/credentials
session = EESession.from_earthengine_token()

# An existing google.auth Credentials object
session = EESession.from_google_credentials(creds, project="my-project")

# Application Default Credentials (explicit opt-in)
session = EESession.from_application_default()

# Resolve from the environment (opt-in): EARTHENGINE_TOKEN / EE OAuth file
session = EESession.from_default()

Credentials are never resolved implicitly — a bare EESession() constructor call is not supported; always use a from_* factory to build a session. To resolve from the environment explicitly, call EESession.from_default(), which walks local sources only, in this order:

  1. EARTHENGINE_TOKEN environment variable

  2. Earth Engine credentials file (~/.config/earthengine/credentials)

The credentials file is accepted only when it holds an OAuth refresh token — the file earthengine authenticate writes. A service-account key at that path is refused with ServiceAccountFileRefusedError: it is a machine-wide identity, so resolving it implicitly would give every caller on the host the same Earth Engine account. To use it anyway, opt in explicitly:

session = EESession.from_default(allow_service_account_file=True)

Prefer EESession.from_service_account("sa-key.json"), which names the key you mean. Any other file shape — unparsable, or without a refresh token — raises CredentialsFileUnrecognizedError. Both errors subclass CredentialsResolutionError, so a single except covers every way from_default() can fail to resolve.

Application Default Credentials are not included — call EESession.from_application_default() to use them.

To see which source a session ended up using, inspect session.auth_mode (the credential kind: file/oauth/service_account/adc/sepal) and session.auth_source (the precise origin: earthengine_token/ee_oauth_file/ee_service_account_file/service_account/application_default/google_credentials/sepal_file/sepal_session).

Making API Calls

After initializing the session, use the operations property to access the key GEE methods. For example, you can retrieve information about Earth Engine objects, generate map IDs, or fetch asset details:

import ee

# Initialize the Earth Engine library (this can use any authentication method/account)
# The purpose of this is to ensure the ee library is available for use
ee.Initialize()

# Use the operations available in the session
result_info = session.operations.get_info(ee.Number(5))
print(result_info) # the GEE server call is done using the custom EE client

# Example: Generate a map ID for an Earth Engine image
image = ee.Image('COPERNICUS/S2/20190726T104031_20190726T104035_T31TGL')
map_id = session.operations.get_map_id(image)
print(map_id)

# Example: Retrieve asset information
asset_info = session.operations.get_asset("users/your_username/your_asset")
print(asset_info)

Contributing

We welcome contributions from the community. If you wish to help improve this package, please submit issues or pull requests.

Forking and Branching

  1. Fork the repository.

  2. Create a new branch:

    git checkout -b feature-branch

  3. Commit your changes:

    git commit -am 'Add new feature'

  4. Push the branch:

    git push origin feature-branch

  5. Create a new Pull Request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Project links

Data verified by PyPI on Sep 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dfguerrerom from gravatar.com dfguerrerom

Credits

Author: Daniel Guerrero

GitHub Statistics

Data verified by PyPI on Sep 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.10

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ee_client-3.2.1.tar.gz (49.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ee_client-3.2.1-py3-none-any.whl (39.9 kB view details)

Uploaded Python 3

File details

Details for the file ee_client-3.2.1.tar.gz.

File metadata

  • Download URL: ee_client-3.2.1.tar.gz
  • Upload date:
  • Size: 49.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ee_client-3.2.1.tar.gz
Algorithm Hash digest
SHA256 a15e0b50a15f5ff8ef9a2e215efdbc1620e4ae042f7ed956da4bf7fc79b59850
MD5 5ace31bcd304ec53b3def234b6578a9a
BLAKE2b-256 b778b199905c43ff7bd241259a3661032712596e5011d8f80269bfbbc7b2a968

See more details on using hashes here.

Provenance

The following attestation bundles were made for ee_client-3.2.1.tar.gz:

Publisher: release.yaml on dfguerrerom/ee-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ee_client-3.2.1-py3-none-any.whl.

File metadata

  • Download URL: ee_client-3.2.1-py3-none-any.whl
  • Upload date:
  • Size: 39.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ee_client-3.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 931de229f2fc0bf1831c59755c2768d47993033e21e48747115369f6bbcd8520
MD5 86d6bd290926eb46c166fce7cf9f0e97
BLAKE2b-256 7724f0dfb1e0dcf59128ee8a3dd3b07912c71cd217c7f68960fe59efd9449f96

See more details on using hashes here.

Provenance

The following attestation bundles were made for ee_client-3.2.1-py3-none-any.whl:

Publisher: release.yaml on dfguerrerom/ee-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

3.2.1 This release

2 files

3.2.0

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.0

2 files

Pre-release

3.0.0rc0

2 files

2.6.3

2 files

2.6.2

2 files

2.6.1

2 files

2.6.0

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.0

2 files

2.3.0

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.3

2 files

2.0.1

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

0.7.0

2 files

0.6.1

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.0

2 files

0.1.0

2 files

0.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page