A catalog for your projects

Requests and efficient downloads

Start with the small manifest. Save its ETag and send it in If-None-Match: HTTP 304 means the local manifest is still current. Download a catalog file only when its version changes.

curl -i 'https://aboveus.space/api/v1/catalog/manifest.json'

curl -i -H 'If-None-Match: "saved-etag"' 'https://aboveus.space/api/v1/catalog/manifest.json'
# 304: keep the local manifest. No response body.
# 429: wait for the Retry-After response header.

Quick JSON download

The --compressed option accepts compressed transfer and automatically saves decompressed JSON.

curl --fail --compressed --output catalog.json.part 'https://aboveus.space/api/v1/catalog/latest/spacetrack.json'

Download a gzip archive

A .json.gz file stays compressed; it does not need --compressed. Decompress the archive before reading.

curl --fail --output catalog.json.gz.part 'https://aboveus.space/api/v1/catalog/latest/spacetrack.json.gz'

On Windows, run these single-line commands with curl.exe instead of curl. Output is saved to .part; rename the file only after a successful download. For recurring updates and SHA-256 verification, use the example below.

Reliable download: use a temporary file

Example for a POSIX shell, curl, and jq. It never replaces a working file with a 304 response, an HTML error, or a partial download. Temporary files are removed on failure.

#!/bin/sh
set -eu
base='https://aboveus.space'
tmp=$(mktemp -d './.aboveus-download.XXXXXX')
trap 'rm -rf -- "$tmp"' EXIT HUP INT TERM

# curl >= 7.68; a missing ETag file is allowed on the first run.
[ -s catalog.json.gz ] && [ -s catalog-manifest.json ] || rm -f catalog.etag
status=$(curl --silent --show-error --connect-timeout 15 --max-time 120 \
  --etag-compare catalog.etag --etag-save "$tmp/etag" \
  --dump-header "$tmp/headers" --output "$tmp/manifest.json" \
  --write-out '%{http_code}' 'https://aboveus.space/api/v1/catalog/manifest.json')
case "$status" in
  304) echo 'Unchanged; keeping local files.'; exit 0 ;;
  200) ;;
  429|503) cat "$tmp/headers" >&2; exit 1 ;; # Honor Retry-After.
  *) echo "Manifest HTTP $status" >&2; exit 1 ;;
esac

# Choose catalog-zh.json.gz, catalog-en.json.gz, or catalog-ru.json.gz for localized knowledge.
file='spacetrack.json.gz'
url=$(jq -er --arg file "$file" '.files[] | select(.name == $file) | .url' "$tmp/manifest.json")
printf '%s' "$url" | grep -Eq '^/api/v1/catalog/snapshots/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/(spacetrack|catalog|catalog-ru|catalog-en|catalog-zh)\.json\.gz$'
expected=$(jq -er --arg file "$file" '.files[] | select(.name == $file) | .sha256' "$tmp/manifest.json")
printf '%s' "$expected" | grep -Eq '^[0-9a-f]{64}$'
curl --fail --silent --show-error --connect-timeout 15 --max-time 3600 \
  --dump-header "$tmp/download-headers" --output "$tmp/catalog.json.gz" "$base$url" \
  || { cat "$tmp/download-headers" >&2; exit 1; }
printf '%s  %s\n' "$expected" "$tmp/catalog.json.gz" | sha256sum --check -
gzip -t "$tmp/catalog.json.gz"
mv -f "$tmp/catalog.json.gz" catalog.json.gz
mv -f "$tmp/manifest.json" catalog-manifest.json
mv -f "$tmp/etag" catalog.etag
# Change the chosen variant? Remove catalog.etag to force a fresh download.

Schema and field meaning

Schema version and snapshot version are separate. Read fields by name and tolerate additional fields. NORAD identifiers are strings, with no five-digit limit.

An unknown activity status does not mean inactive. Family or event knowledge can describe a group rather than an individual spacecraft: preserve scope and sources.

CSV

UTF-8, commas, and RFC 4180 quoting. Numbers use decimal points; an empty cell means a missing value. Import identifiers and designators as text so spreadsheet software does not change them. CSV is a compact flat representation. OMM fields have separate columns without the omm prefix; orbitSource/nameSource/cosparSource/countrySource/activitySource are also flat. Enriched variants add language, localizedName, summary, knowledgeStatus, knowledgeLevel, reviewedAt, familyId, eventId, sourceIds, sourceUrls, imagePageUrl, imageAuthor, imageLicense, imageLicenseUrl, and wikidataId. sourceIds and sourceUrls are | separated lists in the same order. Full facts, their scope, date precision, detailed provenance, and image captions remain in JSON. Image files are not included. To prevent spreadsheet formulas, textual cells beginning with =, +, -, @ or control whitespace receive a leading apostrophe; numeric values stay numeric.

This is a normalized Above Us catalog, not a standalone CCSDS OMM standard document. Orbital elements use SGP4, TEME, and UTC; do not substitute them into another model without accounting for these conventions.

Updates, coverage, and limitations

A new export is published after a successful catalog update. If an update fails, the last valid snapshot remains available. File generation time is not orbital epoch: check source retrieval times and each object’s epoch.

The dataset covers current GP used by Above Us, not every object ever launched. Space-Track uses a 30-day epoch filter; CelesTrak adds objects from its current list. spacetrack is a snapshot of that GP feed, not a complete raw SATCAT. A missing record does not prove reentry. Read the object count and freshness warnings from the manifest.

The latest 2 successful releases are retained; this is not a permanent archive. Keep required files locally together with their manifest and attribution. After a 404, request the current manifest.

The data supports research and visualization. Public GP does not replace operational flight or conjunction assessment data. Above Us does not guarantee accuracy, completeness, or uninterrupted availability.

Sources, attribution, and rights

The combined catalog has no single license that replaces all source terms. When sharing it further, preserve the manifest sources, attribution on this page, and individual field provenance.

• Space-Track.org / USSPACECOM: basic GP/OMM and SATCAT can be redistributed under the published USSPACECOM blanket approval with appropriate citation. This permission does not automatically cover all Space-Track products.
• CelesTrak: a source for name and activity enrichment where identified by metadata. Its retrieval policy is not a universal redistribution license for all products. Above Us grants no additional rights in CelesTrak material.
• GCAT — Jonathan C. McDowell: CC BY 4.0. Data is matched to NORAD identifiers, normalized, and expressed in Russian, English, and Simplified Chinese. Retain the author, catalog link, license, and notice of these changes.
• Wikidata (CC0): structured labels, aliases, and short descriptions are CC0; this is not a license for Wikipedia prose or images.
• NASA: a factual source for independently written summaries. Third-party materials and NASA identifiers have separate terms; attribution does not imply endorsement.
• J. McDowell’s Debris Clouds Catalog is identified separately from GCAT: a factual citation does not declare that entire section CC BY 4.0. Above Us original text and third-party material retain their own terms.
• Wikimedia Commons: each image has its own license. Links and author/license metadata convey no ownership. CC BY-SA applies to the image and its adaptations, not automatically to the entire catalog. Linking an image does not waive its terms.

Keep sourceIds, citations, and uncertainty notes with descriptions. Check the linked upstream terms for your intended use.