REST API Usage

The is the primary programmatic interface for catalog discovery, queries, and reprocessing. Use api_url from outputs — CORS does not apply to curl and server-side clients.

Setup

From the demo repo root:

export API_URL="$(terraform -chdir=terraform output -raw api_url)"
echo "$API_URL"

Catalog — discover stations and dates

List all stations with processed output:

curl "${API_URL}/catalog"

List available dates for a station:

curl -s "${API_URL}/catalog?station=auck" | jq .

Catalog derives stations and dates from processed key prefixes under processed/tec/. Raw ingest alone does not populate the catalog.

Query — fetch TEC time series

curl -s "${API_URL}/query?station=auck&start_time=2026-06-28T00:00:00Z&end_time=2026-06-28T23:59:59Z&sv=G01" | jq .

Query tips

Scenario	Recommendation
Full-day query on a busy station	Add `&sv=G01` (or another satellite) to reduce row count
Large result sets	Check `meta.truncated`; narrow time range or add `sv` filter
Max time range	7 days between `start_time` and `end_time`
Row cap	Default 2000 rows (`QUERY_MAX_ROWS`)

Reprocess — submit and poll jobs

Submit:

JOB=$(curl -s -X POST "${API_URL}/reprocess" \
  -H "Content-Type: application/json" \
  -d '{"station": "auck", "year": 2026, "doy": 179, "parameters": {"NAV_DAY_OFFSET": 2}}')
echo "$JOB"

Poll:

JOB_ID=$(echo "$JOB" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
curl "${API_URL}/reprocess/${JOB_ID}"

Supported parameters keys: NAV_DAY_OFFSET, SAVE_PARQUET, SAVE_CSV, SAVE_JSON, SAVE_STATIC_PLOTS, SAVE_INTERACTIVE_PLOTS. Any other key returns HTTP 400.

Browser vs CLI

Client	URL	Notes
curl, scripts, Postman	`api_url`	No CORS restrictions
portal	`app_url`	Requires CORS Lockdown