ABOVE US
首页 / API

ABOVE US · 数据访问

为你的项目提供航天目录

即用文件包含轨道根数和参考资料。下载快照并保存在本地,仅在数据变化时更新。

JSON / CSVgzipETag / 304无需 API 密钥

五种目录版本

文件已提前生成。每种版本均提供 JSON、CSV 及其 gzip 压缩文件。增强目录可能比单独的 Space-Track 数据包含更多目标。为获得可复现的下载,请使用清单中的不可变链接。

清单加载后将显示当前文件大小和版本。

快照版本
—
生成时间(UTC)
—
目标数量
—
版本JSONJSON + gzipCSVCSV + gzip
spacetrackSpace-Track GP 数据,不含 CelesTrak 补充信息。JSON—JSON.GZ—CSV—CSV.GZ—
catalog合并后的轨道与基础字段。JSON—JSON.GZ—CSV—CSV.GZ—
catalog-ru包含俄语参考资料的合并目录。JSON—JSON.GZ—CSV—CSV.GZ—
catalog-en包含英语参考资料的合并目录。JSON—JSON.GZ—CSV—CSV.GZ—
catalog-zh包含简体中文参考资料的合并目录。JSON—JSON.GZ—CSV—CSV.GZ—

下载无需账户或 API 密钥。gzip 是单独的压缩文件,读取前请先解压。CSV 包含平面字段和摘要,详细事实和图片说明保留在 JSON 中。大小对应下载文件,SHA-256 校验值见清单。

请求与高效下载

先获取较小的清单。保存其 ETag,并通过 If-None-Match 发送:HTTP 304 表示本地清单仍然有效。只有版本变化时才下载目录文件。

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:保留本地清单。响应无正文。
# 429:按响应头 Retry-After 指定的时间等待。

快速下载 JSON

选项 --compressed 允许压缩传输,并自动保存解压后的 JSON。

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

下载 gzip 压缩文件

.json.gz 文件保存为压缩格式,无需使用 --compressed。读取前请先解压。

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

在 Windows 中,请用 curl.exe 代替 curl 运行这些单行命令。结果保存到 .part 文件,只有下载成功后才重命名。定期更新和 SHA-256 校验请参考下方示例。

可靠下载:先使用临时文件

以下示例使用 POSIX shell、curl 和 jq。它不会用 304 响应、HTML 错误页面或未完成的下载覆盖正常文件。失败时会删除临时文件。

#!/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;首次运行时允许 ETag 文件不存在。
[ -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 '没有变化,保留本地文件。'; exit 0 ;;
  200) ;;
  429|503) cat "$tmp/headers" >&2; exit 1 ;; # 遵循 Retry-After。
  *) echo "清单 HTTP $status" >&2; exit 1 ;;
esac

# 选择 catalog-zh.json.gz、catalog-en.json.gz 或 catalog-ru.json.gz 获取对应语言的参考资料。
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
# 切换目录版本时,删除 catalog.etag 以强制重新下载。

限制

每个 IP:清单每分钟最多 30 次请求;文件每分钟最多 2 次请求,短时突发允许额外 8 次;每个 IP 最多 2 个并发连接,整个服务最多 8 个。文件速度限制为 128 KiB/秒。检查清单的间隔至少为 60 分钟。

不要并行运行下载循环。收到 429 时遵循 Retry-After;收到 503 时保留之前的快照,稍后再试。避免立即反复重试。

服务器响应

200 — 数据 · 304 — 无变化 · 404 — 未知或已过期的版本 · 429 — 请求频率受限 · 503 — 导出尚不可用.

GET 下载文件,HEAD 返回响应头。CORS 允许浏览器应用读取这个公共 API。

数据结构与字段含义

结构版本与快照版本相互独立。按名称读取字段,并允许新增字段。NORAD 编号存储为字符串,不限制为五位数字。

字段类型含义
schemaVersion / versionstring / UUIDJSON 外层结构版本与快照版本。记录位于 objects[] 中。
generatedAt / sourcesUTC / object导出生成时间和来源目录的获取时间。清单中的 metadataRevision 和 knowledgeRevision 标识参考资料版本。
noradId / cosparstring / string|nullNORAD 编号与国际标识。null 表示信息缺失,不表示零。
namestring来源名称;合并数据集在可用时使用 CelesTrak 的显示名称。
objectType / rawObjectTypeenum / string|nullpayload、rocket-body、debris 或 unknown;rawObjectType 保留 Space-Track 原始分类。
activityenumlisted-active:在 CelesTrak 列表中;assumed-active:Above Us 的启发式判断;unknown:没有确认状态。spacetrack 中始终为 unknown。
orbitClass / countryCode / launchDateenum / string|null / string|nullLEO、MEO、GEO、HEO;目录中的所有者代码;发射日期已知时采用 YYYY-MM-DD。
epoch / omm.EPOCHUTC string来源平均根数的历元,并非卫星当前位置所对应的时间。
omm.MEAN_MOTION / ECCENTRICITYnumber平均运动:圈/日。偏心率:无量纲。
omm.INCLINATION / RA_OF_ASC_NODE / ARG_OF_PERICENTER / MEAN_ANOMALYnumber角度单位为度。
omm.BSTAR / MEAN_MOTION_DOT / MEAN_MOTION_DDOTnumberBSTAR:地球半径的倒数。导数采用来源 GP 约定中的圈/日² 和圈/日³(TLE 系数为 ½ 和 ⅙);不要自动调整比例。
provenanceobjectorbitSource、nameSource、cosparSource、countrySource 和 activitySource。优先使用轨道历元更新的数据;历元相同时优先 Space-Track。
knowledgeobject (catalog-ru / catalog-en / catalog-zh)语言、status、level、localizedName、aliases、summary、facts 和 sourceIds。包含全部可用事实,不会为缺失的故事编造内容。
knowledge.language / localizedName / summarystring / string|null / string|null语言版本为 ru、en 和 zh(简体中文)。外部中文参考资料缺失时使用英语。localizedName 缺失时请使用原始 name。编号和枚举值保持不变。旧快照不可变,catalog-zh 将在下一次成功更新后出现。
references / knowledge.sourceIdsobject / string[]在增强 JSON 外层结构中,references 是按 id 索引的共享引用字典:references[id] 包含 id、title、url、checkedAt、license、attribution 和 termsUrl。knowledge.sourceIds 与 facts[].sourceIds 引用其键。checkedAt 是参与汇总的来源记录中最近的检查时间,并不代表重新核查了全部事实。knowledge.metadataCheckedAt 保留导入元数据的日期。license 为 null 不代表开放许可。外层 sources 描述 Space-Track/CelesTrak 轨道快照,与这些参考资料引用相互独立。
knowledge.facts[].scope / sourceIdsenum / string[]object、event 或 family:陈述所针对的主体。sourceIds 将陈述连接到引用来源。
knowledge.provenanceobject, optional母体、事件、原因与日期。请保留 precision、dateKind、uncertain 和 uncertaintyKind;phase-start 并不能证明具体解体时间。
knowledge.imageobject, optionalCommons 文件引用、caption、subject、作者、许可证、licenseUrl、pageUrl 和 checkedAt。它是已审核的引用,不包含图片字节,也不承诺再次审核。

活动状态未知不等于停用。系列或事件资料可能描述一组目标,而不是单个航天器的历史;请保留 scope 和来源。

CSV

采用 UTF-8、逗号分隔及 RFC 4180 引号规则。数字使用小数点,空单元格表示缺失值。请将编号和国际标识作为文本导入,避免电子表格软件更改它们。CSV 是紧凑的平面表示。OMM 字段使用独立列,不带 omm 前缀;orbitSource/nameSource/cosparSource/countrySource/activitySource 也使用平面列。增强版本增加 language、localizedName、summary、knowledgeStatus、knowledgeLevel、reviewedAt、familyId、eventId、sourceIds、sourceUrls、imagePageUrl、imageAuthor、imageLicense、imageLicenseUrl 和 wikidataId。sourceIds 和 sourceUrls 是以 | 分隔且顺序一致的列表。完整事实、scope、日期精度、详细 provenance 和图片说明保留在 JSON 中,不包含图片文件。为防止电子表格公式执行,以 =、+、-、@ 或控制空白字符开头的文本单元格会加上前导单引号;数值仍保持为数值。

这是经过规范化的 Above Us 目录,并非独立的 CCSDS OMM 标准文档。轨道根数采用 SGP4、TEME 和 UTC;将它们用于其他模型前,必须考虑这些约定。

更新、覆盖范围与限制

目录成功更新后会发布新导出。更新失败时,最后一个有效快照仍然可用。文件生成时间不等于轨道历元:请检查来源获取时间及各目标的 epoch。

数据集覆盖 Above Us 使用的当前 GP,而不是历史上发射的所有目标。Space-Track 使用 30 天历元过滤,CelesTrak 从其当前列表补充目标。spacetrack 是该 GP 数据流的快照,并非完整的原始 SATCAT。缺失记录并不证明目标已经再入大气层。目标数量与时效警告请以清单为准。

仅保留最近 2 个成功版本,这不是永久档案。请将所需文件连同清单和署名保存在本地。收到 404 后,请获取当前清单。

数据用于研究与可视化。公开 GP 不能替代实际飞行控制或交会评估数据。Above Us 不保证精度、完整性或持续可用性。

来源、署名与权利

合并目录不存在能够替代全部来源条款的统一许可证。再次分享时,请保留清单中的来源、本页署名和各字段的来源信息。

  • Space-Track.org / USSPACECOM: 根据 USSPACECOM 已公布的一般授权,基本 GP/OMM 和 SATCAT 可以在适当注明来源的前提下再分发。此授权不会自动涵盖 Space-Track 的所有产品。
  • CelesTrak: 在元数据明确标注时,用于补充名称和活动状态。其数据获取政策并非所有产品的通用再分发许可。Above Us 不授予 CelesTrak 材料的额外权利。
  • GCAT — Jonathan C. McDowell: CC BY 4.0. 数据与 NORAD 编号匹配、经过规范化,并以俄语、英语和简体中文表述。请保留作者、目录链接、许可证以及这些修改的说明。
  • Wikidata (CC0): 结构化名称、aliases 和简短 descriptions 使用 CC0;这并不是 Wikipedia 正文或图片的许可证。
  • NASA: 是独立撰写摘要所用的事实来源。第三方材料和 NASA 标识有各自的使用条款;注明来源不代表获得其认可。
  • J. McDowell 的 Debris Clouds Catalog 与 GCAT 分别列出:引用某项事实不代表该部分整体采用 CC BY 4.0。Above Us 原创文字和第三方材料各自保留其使用条款。
  • Wikimedia Commons: 每张图片都有自己的许可证。链接以及作者和许可元数据不转移所有权。CC BY-SA 适用于图片及其改编作品,不会自动适用于整个目录。提供图片链接不免除其使用条件。

请将 sourceIds、引用和不确定性说明与描述一并保留。根据预期用途,检查链接中的上游使用条款。