Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

eoAPI Workshop

Welcome to the eoAPI Workshop!

This interactive session will introduce you to eoAPI - a powerful cloud-native framework that simplifies access to Earth observation data. By the end of this workshop, you’ll understand how to use eoAPI to catalog, discover, visualize, and analyze geospatial data efficiently.

Workshop Objectives

  • Explore how eoAPI can fit into your geospatial workflows

  • Learn about STAC (SpatioTemporal Asset Catalog) and its role in Earth observation

  • Explore the key components of eoAPI and how they work together

  • Gain hands-on experience working with metadata, raster, and vector services

Workshop Infrastructure:

Interactive tutorial outline

  1. STAC metadata generation

  2. The Database: pgstac

  3. The STAC API: stac-fastapi-pgstac

  4. The raster API: titiler-pgstac

  5. The vector API: tipg

1. Introduction

1.1 What is eoAPI?

eoAPI is an assemblage of state-of-the-art services that combine to enable data discovery, search, visualization, and access.

eoAPI presents an open-source and reusable framework for harnessing earth observation data. eoAPI takes the work out of constructing a cloud-native EO infrastructure through a set of sensible defaults that fit most EO and geospatial infrastructure needs. Built with modularity as a core principle, eoAPI can easily be customized to your needs.

Additional resources

1.2 Why would you use eoAPI?

  • You want to make your data catalog easily searchable for internal and/or external users

  • You want to serve dynamic visualizations of collections in data catalog

  • You want to use the growing list of tools and frameworks that can consume STAC metadata

2. Cloud Fundamentals

2.1 The Cloud-Native Approach

Traditional geospatial workflows involve:

  • Downloading entire datasets

  • Processing them on local machines

  • Managing complex software installations

  • Dealing with interoperability challenges

Cloud-native geospatial changes this paradigm:

  • Data stays in place: Access only what you need, when you need it

  • Compute happens near the data: Minimize data movement, run analyses in the cloud (like this binder notebook server!)

  • Standards-based interfaces: Interoperate with existing tools

  • Scalable infrastructure: Automatically scale up compute resources when you need them, turn them off when you don’t

eoAPI’s components enable you to adopt cloud-native practices with relative ease. Tradiditional workflows are still possible with the eoAPI stack, though. For example, if your users still want to download files to their own disk they can use the STAC API to search for the items they need then use the download links for the assets in each item.

Additional resources

2.2 Infrastructure as Code

A key concept for reliable and reproducible cloud resource deployments is Infrastructure as Code (IaC), which:

  • Defines your infrastructure in code files rather than manual configuration in a web portal

  • Makes deployments reproducible and versioned

  • Enables easy scaling and updates

  • Enables review of proposed changes via code review

eoAPI provides IaC templates for AWS CDK and Kubernetes

3. STAC 101

3.1 What is STAC?

The SpatioTemporal Asset Catalog (STAC) specification is a common language for describing geospatial data:

  • Simple: Based on JSON, a widely-used data format

  • Extensible: Core specification with optional extensions

  • Self-describing: Contains both metadata and links to data

  • Hierarchical: Collections contain items which reference assets (the actual data files)

STAC helps solve a fundamental problem: making Earth observation data findable, accessible, interoperable, and reusable (FAIR principles).

Additional resources

3.2 STAC Structure

STAC has a few key concepts:

  • Catalog: A container that organizes collections and items

  • Collection: A group of items sharing common metadata

  • Item: A single observation or dataset with specific spatial and temporal extent

  • Asset: The actual data file (e.g., GeoTIFF, NetCDF, etc.)

Here’s a simplified representation:

Catalog
├── Collection A
│   ├── Item 1
│   │   ├── Asset 1 (e.g., visual.tif)
│   │   ├── Asset 2 (e.g., metadata.xml)
│   │   └── Asset 3 (e.g., thumbnail.png)
│   └── Item 2
│       └── ...
└── Collection B
    └── ...

3.3 STAC Extensions

The STAC specification can be extended to support specific use cases:

  • Electro-Optical: For optical imagery

  • SAR: For synthetic aperture radar data

  • Projection: For specifying coordinate reference systems

  • Scientific: For scientific datasets

  • Datacube: For multidimensional data

  • And many more

Additional resources:

3.4 STAC API

While static STAC catalogs are useful, the real power comes from making them searchable via STAC API:

  • STAC API: RESTful API for searching STAC Items and Collections

  • Filtering: Search by time, location, properties, etc.

  • Pagination: Handle large result sets efficiently

  • Extensions: Additional capabilities like sorting, transactions, etc.

Additional resources

3.5 STAC Ecosystem

STAC has grown into a vibrant ecosystem:

  • Creation tools: stactools, pystac, rio-stac

  • API implementations: stac-fastapi, stac-fastapi-pgstac, stac-fastapi-elasticsearch

  • Clients: pystac-client, stac-browser, rstac, rustac

  • Visualization: titiler, stac-browser

  • Validation: stac-validator, pystac, stac-pydantic

Additional resources

4. eoAPI Components

4.1 Database: pgSTAC

At the center of eoAPI is the pgSTAC database:

  • PostgreSQL extension for storing and querying STAC metadata

  • Optimized for performance with millions of items

  • Supports complex filtering with CQL2

  • Handles spatio-temporal queries efficiently

Advantages:

  • Builds on top of PostgreSQL

  • Designed for industrial-scale datasets (like Microsoft Planetary Computer)

  • Transaction support (add/update/delete)

Disadvantages:

  • Requires running a PostgreSQL database

Additional resources

4.2 STAC API: stac-fastapi-pgstac

To make the catalog searchable, eoAPI uses stac-fastapi-pgstac:

  • REST API following the STAC API specification

  • Built on FastAPI for modern Python performance

  • Connects to pgSTAC for efficient queries

  • Supports core STAC API endpoints:

    • /collections: List and filter collections

    • /collections/{id}/items: Get items in a collection

    • /search: Search across collections

    • /queryables: Expose searchable properties

Additional resources

3.3 Raster Service: titiler-pgstac

For visualizing and analyzing raster data, eoAPI includes titiler-pgstac:

  • Dynamic map tile server that connects directly to a pgstac database to identify relevant assets for rendering tiles for a mosaic of images from a STAC collection

  • Powered by titiler

  • On-the-fly processing of most file formats supported by GDAL

  • Supports filtering, band selection, color correction, expressions

  • Creates web-friendly tiles for use in mapping applications

  • Enables mosaics of multiple items based on STAC queries

Key capabilities:

  • Easily generate OGC API Tiles endpoints that any map client can use

  • Dynamic tiling: store your data once, visualize it how you want it when you want it

  • Single item rendering

  • Multi-item mosaics

  • Collection-wide mosaics!

  • Band math and indices (e.g., NDVI)

  • Color manipulation (stretch, colormap)

  • WMTS endpoints

Additional resources

4.4 Vector Service: tipg

For working with vector data stored in PostgreSQL, eoAPI uses tipg:

  • Connects to PostGIS tables and views

  • OGC API Features + OGC API Tiles implementation

  • FastAPI-based Python application

  • Vector tile generation

tipg is not the only tool for serving features/tiles from PostGIS, but it is written in Python with FastAPI which makes it a nice complement to the other eoAPI services.

Alternatives to tipg:

Additional resources

5. eoAPI Deployment Options

eoAPI offers multiple deployment options to suit your needs:

5.1 Local Development with Docker

For testing and development, eoAPI provides a Docker compose setup:

git clone https://github.com/developmentseed/eoAPI.git
cd eoAPI
docker compose up

This creates a local environment with all services running in containers on your laptop which you can interact with via any http client.

The pgstac database will be accessible via psql on port 5439:

psql postgresql://username:password@localhost:5439/postgis

5.2 AWS Deployment with CDK

For production deployments on AWS, use eoapi-cdk:

  • Deploys a pgstac database to AWS’ Relational Database Service (RDS) with an EC2 instance running pgbouncer for connection pooling

  • Deploys stac-fastapi-pgstac, titiler-pgstac, and tipg as serverless Lambda functions

  • Sets up API Gateway endpoints for the REST APIs

  • Handles permissions and networking between the services

Advantages

  • Lowest cost deployment option

  • Autoscaling: serverless functions that spin up when you need them, turn off when you aren’t using them

  • Most mature eoAPI deployment system available

Disadvantages

  • Locked into AWS

  • Serverless functions can take be slow to warm up from a cold start

5.3 Kubernetes Deployment

For container-based deployments, use eoapi-k8s:

  • Helm charts for Kubernetes

  • Deployable to any Kubernetes cluster

  • Suitable for on-premises or cloud deployments

Advantages

  • Cloud-agnostic: run anywhere you can run a Kubernetes cluster

  • Autoscaling: Kubernetes can handle autoscaling based on demand

Disadvantages

  • More expensive to run a Kubernetes cluster than just a PostgreSQL database and some serverless functions

Next: Interactive Exploration

next, you will get a chance to interact with the eoAPI services that have been set up for this workshop. You’ll learn how to:

  1. Create STAC metadata

  2. Load STAC metadata into a pgstac database

  3. Search for data using the STAC API

  4. Visualize raster data with dynamic tiling

  5. Work with vector data in interactive maps

Now you are ready to get started with Creating STAC Metadata!

eoAPI Workshop
1. STAC metadata generation