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
| Function | Returns | Description |
|---|---|---|
collections() | DataFrame | Lists every collection visible to your session (public, plus any private collections your token grants access to) |
item_assets(collection=None, *roles) | DataFrame | Describes 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) | DataFrame | Lists the data providers (producer, processor, licensor, host) for a collection |
read_catalog(**query) | GeoDataFrame | Runs 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:
| Parameter | Accepts | Notes |
|---|---|---|
geo | bbox list [west, south, east, north], WKT string, file path, shapely geometry, GeoDataFrame | Area of interest; omit to search globally |
start_datetime / end_datetime | ISO-8601 string, date/datetime object, or '..' for open-ended | Defaults to an open interval on both ends |
max_cloud_cover | float, 0–100 | Convenience filter, ANDed with query if both are given |
collections | str or list of collection IDs | See the collection ID reference |
grid_ids | Grid object(s) or str(s) (e.g. MGRS-30TVK, WRS2-181023) | Search by sensor grid tile instead of/in addition to geometry |
item_ids | list of item IDs | Fetch specific known items |
query | CQL predicate string | For filters beyond cloud cover, e.g. 'properties.proj:epsg = 32612' |
aggregations | bool | Return faceted counts instead of individual results |
verbose | 0, 1, or 2 | Silent, 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.