Wolfram Cloud Page

The following is a draft of the first chapter of Google Earth Engine Client Cookbook, a Practical Guide for Wolfram Language Users

Second part of this work: https://community.wolfram.com/groups/-/m/t/3715214

Google Earth Engine puts petabytes of Earth observation data at your fingertips -- and this paclet lets you access it from a Mathematica notebook. This chapter explains what the GoogleEarthEngineClient paclet provides, walks through installation and authentication, and demonstrates five practical queries that showcase the breadth of the paclet. By the end, you will understand how expression trees work, which functions trigger server-side computation, and the conventions used throughout this book.

1.1 What Is Google Earth Engine?

Google Earth Engine (GEE) is a planetary-scale geospatial analysis platform that hosts over 80 petabytes of satellite imagery, climate records, terrain models, land-cover classifications, and vector datasets. Unlike a simple tile server, GEE provides a full computation engine: you describe an analysis as an expression tree, and the platform evaluates it across its distributed infrastructure. Only the final result travels over the network.

The GEE REST API v1 exposes this computation engine through standard HTTP endpoints. You can:

◼

Retrieve pixels for any region of any raster dataset, with server-side filtering, compositing, and visualization applied before download.

◼

Query point values at arbitrary coordinates without downloading an entire scene.

◼

Query vector features from tables such as administrative boundaries, protected areas, and census geographies.

◼

Compute statistics by reducing images over regions -- mean elevation across a watershed, total forest area in a country, or median reflectance over a growing season.

◼

Build complex pipelines that chain filtering, band math, masking, compositing, and reduction -- all evaluated server-side.

Why Access GEE from Mathematica?

Mathematica already has strong geospatial capabilities:

GeoGraphics

GeoImage

GeoElevationData

TimeSeries

, advanced image processing, and a rich visualization system. What it lacks is direct access to GEE's petabyte catalog and its server-side processing.

The GoogleEarthEngineClient paclet bridges this gap. You get the best of both worlds:

◼

GEE's catalog and compute -- 80+ petabytes of analysis-ready data, server-side filtering and compositing, no need to download raw scenes.

◼

Wolfram Language's analysis toolkit -- symbolic computation, built-in machine learning, publication-quality graphics, notebook-based workflows.

A typical workflow looks like this: use GEE expression builders to define a cloud-filtered, spectrally indexed satellite composite; retrieve the result as an

Image

; then analyze, classify, or visualize it with Wolfram Language functions. The heavy lifting happens on Google's infrastructure; the creative analysis happens in your notebook.

1.2 The Google Earth Engine (GEE)Client Paclet

The paclet provides approximately 95 public functions organized into eight categories:

Out[]=

Category	Key Functions	Count
Authentication	GEEConnect, $GEEConnection	2
Asset Metadata	GEEGetAssetInfo, GEEListAssets	2
Image Retrieval	GEEComputePixels, GEEImage, GEEGetTile	3
Point Queries	GEEIdentify, GEEGetSamples	2
Feature Queries	GEEComputeFeatures	1
Computation	GEECompute	1
Visualization	GEEGeoGraphics	1
Expression Builders	GEECollection, GEEFilterDate, GEEMedian, ~70 others	~80

Architecture

The paclet communicates with GEE through its REST API v1. The workflow has three layers:

Expression builders (

GEECollection

GEEFilterDate

GEESelectBands

GEEMedian

, etc.) construct an Association-based expression tree. No network calls happen at this stage.

Terminal functions (

GEEComputePixels

GEEImage

GEEIdentify

GEECompute

, etc.) serialize the expression tree to JSON, send it to the GEE REST API, and return the result as a Wolfram Language object -- an

Image

, an

Association

, a number, or a list of features.

Authentication is handled by

GEEConnect

, which creates a JWT from your service account key, exchanges it for an OAuth2 access token, and stores the token in

$GEEConnection

. Tokens are automatically refreshed when they expire.

Key Concept: Server-Side Evaluation

When you write:

GEECollection["COPERNICUS/S2_SR_HARMONIZED"]//GEEFilterDate["2024-06-01","2024-09-01"]//GEEFilterBounds[{2.2,48.8,2.5,48.9}]//GEEFilterProperty["CLOUDY_PIXEL_PERCENTAGE","LessThan",10]//GEESelectBands[{"B4","B3","B2"}]//GEEMedian

...no data moves. The result is a nested

Association

that describes a computation. Only when you pass this to a terminal function like

GEEComputePixels

GEEImage

does the paclet send the expression to Google's servers for evaluation. This means you can build, inspect, and modify pipelines freely before executing them.

1.3 Installation and Authentication

Installing the Paclet

Paclet resource can be found in https://www.wolframcloud.com/obj/dzviovich/DeployedResources/Paclet/DiegoZviovich/GEE/

PacletInstall[ResourceObject["https://wolfr.am/1E4DSMFmm"]]

Once installed, load it in any notebook or script:

Needs["DiegoZviovich`GEE`"]

Setting Up a GCP Service Account

Before you can authenticate, you need a Google Cloud Platform service account with the Earth Engine API enabled. Here is the short version:

Go to the Google Cloud Console.

Create a project (or select an existing one).

Enable the Earth Engine API in the API Library.

Go to IAM & Admin > Service Accounts and create a new service account.

Grant the service account the Earth Engine Resource Viewer role.

Create a JSON key for the service account and download it.

The downloaded file will look something like this:

{
"type": "service_account",
"project_id": "my-gee-project",
"private_key_id": "abc123...",
"private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
"client_email": "gee-reader@my-gee-project.iam.gserviceaccount.com",
...
}

Store this file securely. It is the only credential you need.

Connecting to Earth Engine

conn=GEEConnect["/path/to/service-account-key.json"]

On success,

GEEConnect

returns a status Association and stores the full connection state in

$GEEConnection

conn(*<|"Project"->"my-gee-project","Status"->"Connected","Expiry"->DateObject[...]|>*)

The access token has a one-hour lifetime and is automatically refreshed by subsequent API calls. You only need to call

GEEConnect

once per session.

Checking Connection State

$GEEConnection(*<|"AccessToken"->"ya29...","Expiry"->1743868200,"Project"->"my-gee-project","KeyFile"->"/path/to/service-account-key.json","KeyData"-><|...|>|>*)

You can inspect individual fields:

$GEEConnection["Project"](*"my-gee-project"*)$GEEConnection["Expiry"](*1743868200--Unixtimestamp;useFromUnixTimetoconvert*)FromUnixTime[$GEEConnection["Expiry"]](*DateObject[{2026,4,5,15,30,0},"Instant","Gregorian","UTC"]*)

Overriding the Project

If your service account has access to multiple GCP projects, you can specify which project to use:

GEEConnect["key.json","Project"->"my-other-project"]

Common Authentication Issues

"JWT signing failed" --

GEEConnect

uses

GenerateDigitalSignature

for RS256 JWT signing, which requires Wolfram Language 14.0 or later. Upgrade if you are running an older version.

"Earth Engine API not enabled" -- The Earth Engine API must be explicitly enabled in your GCP project. Go to the API Library in the Cloud Console and enable it.

"Permission denied" -- Your service account needs the Earth Engine Resource Viewer IAM role. Without it, authentication succeeds but all data requests fail.

"File not found" -- The key file path must be an absolute path or relative to the current working directory. Use

FindFile

to verify:

FindFile["/path/to/key.json"]

1.4 Your First Queries

The following examples assume you have already called

GEEConnect

successfully. Each example demonstrates a different category of the paclet's functionality. If the

pipe syntax is unfamiliar, see Section 1.5 for how expression trees work.

Example 1: Point Query -- Elevation at a Location

The simplest thing you can do with GEE is ask "what is the value of this dataset at this point?"

GEEIdentify

answers that question.

Dataset:

USGS/SRTMGL1_003

-- NASA Shuttle Radar Topography Mission, 30-meter resolution global elevation.

result=GEEIdentify

Mount Everest

MOUNTAIN

,"USGS/SRTMGL1_003"

Expected output:

<|"Position"->GeoPosition[{27.9881,86.925}],"Values"->{8752},"Bands"->{"elevation"}|>

The returned value is the SRTM elevation in meters at 30-meter resolution. The SRTM value for Everest (8752 m) differs slightly from the surveyed peak (8849 m) because the radar beam reflects off ice and snow, and the 30-meter pixel averages the terrain around the summit.

You can extract just the elevation value:

Why this matters: Point queries are the fastest way to extract data. No image download is needed -- GEE evaluates a single pixel server-side and returns just the number. This makes it practical to query hundreds of locations in a loop.

Comparing Elevations Across Cities

Example 2: Image Retrieval -- Geo-Tagged Satellite Image

Expected output: A 512x512 color-mapped elevation image of the Sierra Nevada, with greens in the valleys, yellows and oranges at mid-elevations, reds at high elevations, and white at the peaks (Mount Whitney, 4421 m).

The image carries geo-metadata that you can access:

Sentinel-2 True Color

Switching to optical satellite imagery is just a matter of changing the asset ID and specifying the appropriate bands:

Example 3: Expression Pipeline -- Cloud-Filtered Sentinel-2 Composite

Goal: Create a cloud-free RGB median composite of Barcelona for summer 2024.

Expected output: A crisp, cloud-free true-color image of Barcelona at 1024x1024 pixels. The Mediterranean appears dark blue, the city is a gray patchwork, and the surrounding hills show green vegetation.

Let us break down what each step does:

The per-pixel median is the standard approach for creating cloud-free composites. Because clouds are bright outliers, the median naturally rejects them without explicit cloud masking. For most applications over 3+ months of data, this produces clean results.

Example 4: Feature Query -- Protected Areas

Goal: Find protected areas near Yellowstone National Park.

Expected output: A list of Associations, each representing a protected area polygon:

Why this matters: Vector queries let you combine GEE's tabular data with Wolfram Language's data analysis. You could, for example, query all protected areas in a country, compute their total area, and overlay them on a satellite image.

Example 5: Server-Side Computation -- Mean Elevation of a Region

Goal: Compute the mean elevation of the Everest region.

Expected output:

Let us unpack the expression:

Comparing Elevation Statistics Across Mountain Ranges

You can use the same pattern to build comparative analyses:

Expected output: A bar chart showing the Himalayas with the highest mean elevation, followed by the Andes, the Rockies, and the Alps.

1.5 Understanding Expression Trees

The expression builder system is central to how the paclet works. This section explains the mechanics so you can build, inspect, and debug pipelines confidently.

What an Expression Builder Returns

returns something like:

This is not a Wolfram Language symbolic expression in the traditional sense. It is a data structure -- an Association tree -- that mirrors the JSON structure expected by the GEE REST API.

GEEMedian
|
GEESelectBands[{"B4", "B3", "B2"}]
|
GEEFilterDate["2024-01-01", "2024-06-01"]
|
GEECollection["COPERNICUS/S2_SR_HARMONIZED"]

Inspecting an Expression Tree

You can look at any expression directly:

Or examine the top-level function name:

For more detailed inspection:

No Data Moves Until You Call a Terminal Function

This is the most important principle to understand. Expression builders are purely local operations that construct data structures. No HTTP request is made, no pixels are transferred, and no computation happens on GEE's servers until you call one of these terminal functions:

Example: Same Pipeline, Different Terminal Functions

A single expression can be reused with different terminal functions:

This composability is one of the paclet's strengths. Define the processing once; consume the result in whatever form you need.

1.6 Discovering Datasets

Before you can query a dataset, you need to know what it contains. The paclet provides two functions for exploring the GEE data catalog.

Asset Metadata

Knowing the band names is essential for selecting the right bands in your pipelines.

Listing Assets in a Folder

1.7 Conventions Used in This Book

The following conventions are used throughout all chapters of this cookbook.

Bounding Boxes

Points

Date Strings

Band Names

Band names vary by dataset. Common examples:

Visualization Parameters

Common keys:

GeoGraphics Integration

Function Naming Conventions

A Note on Error Messages

Check the message text for the specific GEE error. Common causes include invalid band names, excessively large requests (>48 MB uncompressed), expired authentication, and invalid asset IDs.

1.8 Quick Reference Card

Here is a one-page summary of the most commonly used functions, organized by workflow stage.

Load and Connect

Explore

Build a Pipeline

Retrieve Results

1.9 What Comes Next

With authentication working and a basic understanding of the paclet's architecture, you are ready to tackle real analysis workflows. The remaining chapters of this cookbook build on the foundations laid here:

◼

Chapter 2: Satellite Imagery Fundamentals -- Landsat, Sentinel-2, MODIS, and NAIP workflows; band combinations; cloud masking with SCL; temporal compositing; and visualization techniques.

◼

Chapter 3: Climate and Weather Analysis -- surface temperature, precipitation, evapotranspiration, atmospheric data, solar radiation, and multi-variable climate dashboards using ERA5, CHIRPS, and MODIS.

◼

Chapter 4: Terrain and Geophysical Analysis -- DEMs, slope, aspect, hillshade, land cover classification, soil properties, texture analysis, and 3D visualization with SRTM and ALOS data.

◼

Chapter 5: Vegetation, Agriculture & Precision Farming -- NDVI, EVI, LAI, crop phenology, yield estimation, variable rate application maps, and ground sensor integration.

◼

Chapter 6: Water Resources and Hydrology -- water body detection, reservoir monitoring, flood mapping with SAR, snow and ice, precipitation analysis, water quality, and watershed-scale budgets.

◼

Chapter 7: Urban and Population Analysis -- nighttime lights, urban heat islands, impervious surfaces, change detection, population density, air quality, and multi-city comparative dashboards.

◼

Chapter 8: Advanced Techniques and Wolfram Language Integration -- machine learning classification, time series analysis, image processing pipelines, geographic visualization, data import/export, and parallel batch processing.

◼

Chapter 9: Appendices -- function quick reference, dataset catalog, common pipeline patterns, Wolfram Language integration cheat sheet, troubleshooting guide, and glossary.

Each chapter follows the same pattern: explain the scientific context, show the GEE dataset, build the pipeline step by step, and analyze the result with Wolfram Language tools. The code is designed to be copied, adapted, and extended for your own research.

Next: Chapter 2: Satellite Imagery Fundamentals

CITE THIS NOTEBOOK

Google Earth Engine (GEE) client paclet
by Diego Zviovich
Wolfram Community, STAFF PICKS, May 12, 2026
https://community.wolfram.com/groups/-/m/t/3714827