Skip to main content

PyEOD (Python Client)

PyEOD (Python module name: earth_ondemand) is a first-party Python client library for the Earth OnDemand catalog service that powers the STAC Catalog at catalog.nuview.space. It wraps the same REST/STAC endpoints documented there in a GeoPandas-native interface, so search results come back as ready-to-use GeoDataFrames instead of raw JSON.

Use it when you want to script searches, load results directly into a pandas/GeoPandas/Jupyter workflow, or avoid hand-rolling STAC query-string/JSON payloads yourself. If you'd rather work with raw HTTP or a generic STAC client, see STAC Catalog instead — both talk to the same backend and the same collections.


Installation​

PyEOD is distributed as a Python wheel rather than published to PyPI, and depends on GeoPandas/GDAL, which are easiest to install correctly via conda:

conda create -n pyeod -c conda-forge python=3.9 geopandas gdal
conda activate pyeod
pip install /path/to/pyeod-{version}-py3-none-any.whl

To also get the Jupyter/IPython extras (the %%eod cell magic and richer notebook visualizations — see below):

pip install 'pyeod[ipython] @ file:///path/to/pyeod-{version}-py3-none-any.whl'

Contact support@nuview.space to obtain the current wheel.


Authentication​

PyEOD reads its credentials from environment variables — set one of these before importing earth_ondemand:

import os
os.environ["BEARER_TOKEN"] = "<your API token>"

Generate a token from Account Management → API Token in the platform — see Finding your API token for the full walkthrough.

As with direct STAC API access, an unauthenticated (no-token) session only sees publicly available collections. Supplying a valid bearer token unlocks any additional collections your account has access to.

Pointing PyEOD at the NUVIEW catalog​

By default, PyEOD talks to its underlying service's production endpoint directly. To make sure you're going through NUVIEW's supported entry point, set EOD_CATALOG_URL explicitly:

os.environ["EOD_CATALOG_URL"] = "https://catalog.nuview.space"

Set both environment variables before importing earth_ondemand, since the client reads them once at session-creation time.


Core functions​

FunctionReturnsDescription
collections()DataFrameLists every collection visible to your session (public, plus any private collections your token grants access to)
item_assets(collection=None, *roles)DataFrameDescribes the assets/bands available on a collection's items — band names, ground sample distance, roles; optionally filter by asset role ("data", "metadata", "thumbnail", …)
providers(collection=None)DataFrameLists the data providers (producer, processor, licensor, host) for a collection
read_catalog(**query)GeoDataFrameRuns a spatiotemporal search and returns one row per matching scene/item, with band/asset columns holding direct asset URIs

read_catalog is the main entry point for search. Key parameters:

ParameterAcceptsNotes
geobbox list [west, south, east, north], WKT string, file path, shapely geometry, GeoDataFrameArea of interest; omit to search globally
start_datetime / end_datetimeISO-8601 string, date/datetime object, or '..' for open-endedDefaults to an open interval on both ends
max_cloud_coverfloat, 0–100Convenience filter, ANDed with query if both are given
collectionsstr or list of collection IDsSee the collection ID reference
grid_idsGrid object(s) or str(s) (e.g. MGRS-30TVK, WRS2-181023)Search by sensor grid tile instead of/in addition to geometry
item_idslist of item IDsFetch specific known items
queryCQL predicate stringFor filters beyond cloud cover, e.g. 'properties.proj:epsg = 32612'
aggregationsboolReturn faceted counts instead of individual results
verbose0, 1, or 2Silent, progress bar, or full request/response logging

Quick start​

import os
os.environ["BEARER_TOKEN"] = "<your API token>"
os.environ["EOD_CATALOG_URL"] = "https://catalog.nuview.space"

import warnings
warnings.filterwarnings('ignore') # GeoPandas emits some noisy deprecation warnings

from earth_ondemand import collections, item_assets, read_catalog

# List available collections
collections()[["id", "title"]]

# Inspect the bands/assets available on a collection
item_assets("sentinel2_l2a")

# Search: Sentinel-2 L2A over an AOI, filtered by cloud cover and date range
results = read_catalog(
collections="sentinel2_l2a",
geo=[-149.9, 61.1, -149.7, 61.3],
start_datetime="2024-06-01",
end_datetime="2024-06-30",
max_cloud_cover=10,
)

results[["datetime", "eo_cloud_cover", "B04_10m", "B08_10m"]]

read_catalog handles pagination internally — it keeps requesting subsequent pages from the service until all matching results are collected, so the returned GeoDataFrame already contains every match (subject to the same catalog data your token can see).


Lower-level HTTP access​

For direct control over requests (or to script something the DataFrame-returning helpers don't cover), EarthOnDemandClient is a requests.Session subclass that wraps the same endpoints described in STAC Catalog:

from earth_ondemand.client import EarthOnDemandClient

client = EarthOnDemandClient() # picks up BEARER_TOKEN / EOD_CATALOG_URL from the environment

resp = client.get_collections()
resp.raise_for_status()
print([c["id"] for c in resp.json()["collections"]])

resp = client.post_search({
"collections": ["sentinel2_l2a"],
"bbox": [-149.9, 61.1, -149.7, 61.3],
"datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z",
"limit": 10,
})
resp.raise_for_status()
items = resp.json()["features"]

EarthOnDemandClient also exposes get_collection(id), get_item(collection, item_id), get_search(params), and (for accounts with write access) post_item/put_item/delete_item for the Transactions API.


Jupyter notebook extras​

Installing the ipython extra adds a %%eod cell magic for running searches directly from notebook cells — handy for pasting a query exported as JSON from the Earth OnDemand web app:

from earth_ondemand.ipython import *
%%eod --name my_results --table
{
"collections": ["sentinel2_l2a"],
"geo": [-149.9, 61.1, -149.7, 61.3],
"start_datetime": "2024-06-01",
"end_datetime": "2024-06-30",
"max_cloud_cover": 10
}

The cell result is stored in a GeoDataFrame variable (named my_results above, or an auto-incrementing eod0, eod1, … if --name is omitted). Additional flags layer on visualization: --table [max_rows] for a richer result table, --extents to plot scene footprints on a map, --heatmap [radius] for a density heatmap of scene centroids, and --hist for a temporal coverage histogram.


Choosing between PyEOD and raw STAC access​

  • PyEOD — best for Python/pandas/GeoPandas workflows, Jupyter notebooks, and anyone who wants search results as a ready-to-use dataframe rather than hand-parsing STAC JSON.
  • Raw STAC API / other STAC clients (curl, pystac-client, QGIS, etc.) — best for non-Python tooling, or when you specifically want STAC-spec JSON/GeoJSON responses. See STAC Catalog for endpoint details, parameters, and the current collection list.

Both access the same catalog, the same collections, and the same authentication model — an API token from Account Management → API Token (walkthrough) is required for anything beyond publicly available collections either way.