Spaces:

giswqs
/

ee-tile-request

Paused

App Files Files Community

ee-tile-request / README.md

giswqs

Enhance Dockerfile and main.py for security hardening and input validation (#10)

4d108d9 unverified 3 months ago

preview code

Raw

History Blame Contribute Delete

8.25 kB

metadata

title: Ee Tile Request
emoji: 😻
colorFrom: pink
colorTo: gray
sdk: docker
app_port: 7865
pinned: false
license: mit
short_description: Earth Engine Tile URL Generator

Earth Engine Tile URL Generator

A FastAPI service that generates tile URLs for Google Earth Engine assets, suitable for use with web mapping libraries like Leaflet, Mapbox, or OpenLayers.

Features

Generate tile URLs for Earth Engine Images, ImageCollections, and FeatureCollections
Optional date range filtering for ImageCollections
Optional bounding box filtering for spatial subsetting
Customizable visualization parameters
Validates public API inputs before Earth Engine requests
REST API and web UI (Gradio)
FastAPI auto-generated documentation

Setup

Prerequisites

Python 3.12+
Google Earth Engine account with authentication token

Installation

Clone the repository:

git clone <repository-url>
cd ee-tile-request

Install dependencies:

pip install -r requirements.txt

Set your Earth Engine token:

export EARTHENGINE_TOKEN="your_token_here"

Optional deployment settings:

export ALLOWED_ORIGINS="https://ee.opengeos.org"
export ALLOWED_HOSTS="ee.opengeos.org,localhost,127.0.0.1"
export MAX_REQUEST_BYTES="1048576"

Running the App

Local Development

uvicorn main:app --host 0.0.0.0 --port 7865 --reload

Docker

docker build -t ee-tile-request .
docker run -p 7865:7865 -e EE_SERVICE_ACCOUNT="$EE_SERVICE_ACCOUNT" ee-tile-request

Access Points

Web UI: http://localhost:7865
Cloudflare Tunnel Web UI: https://ee.opengeos.org
API Documentation: http://localhost:7865/docs
Tile Endpoint: POST http://localhost:7865/tile
JRC Water Stats Endpoint: POST http://localhost:7865/jrc-water-stats

Tile URL API

Tile Endpoint

POST /tile

Tile Request Parameters

Parameter	Type	Required	Description
`asset_id`	string	Yes	Earth Engine asset ID or supported ee constructor expression
`vis_params`	object	No	Visualization parameters (min, max, palette, bands, etc.)
`start_date`	string	No	Start date for filtering (format: "YYYY-MM-DD")
`end_date`	string	No	End date for filtering (format: "YYYY-MM-DD")
`bbox`	array	No	Bounding box [west, south, east, north] in degrees

Examples

Basic Request

curl -X POST "http://localhost:7865/tile" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "USGS/SRTMGL1_003",
    "vis_params": {
      "min": 0,
      "max": 5000,
      "palette": ["blue", "green", "red"]
    }
  }'

With Date Range Filtering

Filter Sentinel-2 imagery to a specific time period:

curl -X POST "http://localhost:7865/tile" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "COPERNICUS/S2_SR",
    "start_date": "2023-06-01",
    "end_date": "2023-08-31",
    "vis_params": {
      "bands": ["B4", "B3", "B2"],
      "min": 0,
      "max": 3000
    }
  }'

With Bounding Box Filtering

Filter to San Francisco Bay Area:

curl -X POST "http://localhost:7865/tile" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "COPERNICUS/S2_SR",
    "bbox": [-122.5, 37.5, -122.0, 38.0],
    "vis_params": {
      "bands": ["B4", "B3", "B2"],
      "min": 0,
      "max": 3000
    }
  }'

Combined Filters

Date range and spatial filtering together:

curl -X POST "http://localhost:7865/tile" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "COPERNICUS/S2_SR",
    "start_date": "2023-07-01",
    "end_date": "2023-07-31",
    "bbox": [-122.5, 37.5, -122.0, 38.0],
    "vis_params": {
      "bands": ["B4", "B3", "B2"],
      "min": 0,
      "max": 3000
    }
  }'

Tile Response

{
  "tile_url": "https://earthengine.googleapis.com/v1/projects/.../maps/.../tiles/{z}/{x}/{y}"
}

JRC Water Statistics API

JRC Endpoint

POST /jrc-water-stats

Computes JRC monthly water history and water occurrence statistics for a given bounding box and scale. Returns JSON data suitable for creating plots.

JRC Request Parameters

Parameter	Type	Required	Default	Description
`bbox`	array	Yes	N/A	Bounding box [west, south, east, north] in degrees
`scale`	number	No	30	Scale in meters for computation
`start_date`	string	No	"1984-03-16"	Start date (format: "YYYY-MM-DD")
`end_date`	string	No	today	End date (format: "YYYY-MM-DD")
`start_month`	integer	No	1	Start month for calendar filtering (1-12)
`end_month`	integer	No	12	End month for calendar filtering (1-12)
`frequency`	string	No	"year"	Aggregation frequency: "month" or "year"
`denominator`	number	No	10000	Area unit conversion (10000 = hectares)

Example

curl -X POST "http://localhost:7865/jrc-water-stats" \
  -H "Content-Type: application/json" \
  -d '{
    "bbox": [-90.5, 29.5, -90.0, 30.0],
    "scale": 30,
    "start_month": 5,
    "end_month": 10,
    "frequency": "year"
  }'

JRC Response

{
  "monthly_history": {
    "frequency": "year",
    "unit": "hectares",
    "data": [
      { "Year": "1984", "Area": 123.45 },
      { "Year": "1985", "Area": 130.2 }
    ]
  },
  "water_occurrence": {
    "stats": {
      "mean": 45.2,
      "min": 0,
      "max": 100,
      "stdDev": 28.3
    },
    "histogram": {
      "bin_edges": [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
      "counts": [1500, 200, 150, 100, 80, 60, 50, 40, 30, 300]
    }
  },
  "parameters": {
    "bbox": [-90.5, 29.5, -90.0, 30.0],
    "scale": 30,
    "start_date": "1984-03-16",
    "end_date": "2026-03-05",
    "start_month": 5,
    "end_month": 10,
    "frequency": "year"
  }
}

When frequency is "month", the data array contains {"Month": "Jan", "Area": ...} entries instead of Year.

Using with Web Mapping Libraries

Leaflet

const tileUrl = response.tile_url;
L.tileLayer(tileUrl, {
  attribution: "Google Earth Engine",
  maxZoom: 18,
}).addTo(map);

Mapbox GL JS

map.addSource("ee-tiles", {
  type: "raster",
  tiles: [response.tile_url],
  tileSize: 256,
});

map.addLayer({
  id: "ee-layer",
  type: "raster",
  source: "ee-tiles",
});

Web UI (Gradio)

Access the web interface at http://localhost:7865 to:

Enter Earth Engine asset IDs
Specify visualization parameters as JSON
Get tile URLs instantly
No need to write code

Supported Data Types

Images (ee.Image): Single images with optional clipping to bbox
ImageCollections (ee.ImageCollection): Filtered by date and/or bbox
FeatureCollections (ee.FeatureCollection): Filtered by bbox

Notes

Date filtering only works with ImageCollections
Bounding box format: [west, south, east, north] in WGS84 degrees
asset_id can be a literal Earth Engine asset ID or one of ee.Image("..."), ee.ImageCollection("..."), or ee.FeatureCollection("...").
Arbitrary Python expressions are rejected.
Browser CORS is limited to ALLOWED_ORIGINS; set it to the domains that should call the API.
Host headers are limited to ALLOWED_HOSTS; include ee.opengeos.org when serving through the Cloudflare tunnel.
All filtering parameters are optional and backward compatible
Check the FastAPI docs at /docs for interactive API testing

License

MIT

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference