Каталог для ваших проектов

Запросы и экономия трафика

Начните с небольшого манифеста. Сохраните 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: keep the local manifest. No response body.
# 429: wait for the Retry-After response header.

Быстрое скачивание 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; 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.

Схема и смысл полей

Версия схемы отделена от версии снимка. Читайте поля по именам и допускайте появление новых полей. Идентификатор NORAD хранится строкой, без ограничения пятью цифрами.

Неизвестный статус активности не означает «неактивен». Сведения семейства или события могут описывать группу объектов, а не индивидуальную историю аппарата: сохраняйте 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: базовые GP/OMM и SATCAT допускают перераспространение по опубликованному общему разрешению USSPACECOM при надлежащем указании источника. Это разрешение не распространяется автоматически на все продукты Space-Track.
• CelesTrak: источник уточнений названий и активности там, где это указано в метаданных. Политика получения данных не является универсальной лицензией на дальнейшее распространение всех продуктов. Above Us не предоставляет дополнительных прав на материалы CelesTrak.
• GCAT — Jonathan C. McDowell: CC BY 4.0. Данные сопоставлены с NORAD, нормализованы и изложены на русском, английском и упрощённом китайском. Сохраните имя автора, ссылку на каталог и лицензию, а также обозначение этих изменений.
• Wikidata (CC0): структурированные названия, aliases и краткие descriptions — CC0; это не лицензия на текст Wikipedia и не лицензия на изображения.
• NASA: источник фактов для самостоятельно составленных справок. У сторонних материалов и обозначений NASA отдельные условия; упоминание источника не означает его поддержку проекта.
• Debris Clouds Catalog J. McDowell указан отдельно от GCAT: ссылка на факт не объявляет весь этот раздел CC BY 4.0. Авторские тексты Above Us и сторонние материалы сохраняют собственные условия.
• Wikimedia Commons: каждое изображение имеет свою лицензию. Передаются ссылки и сведения об авторе/лицензии, а не права собственности. CC BY-SA относится к изображению и его адаптациям, а не автоматически ко всему каталогу. Ссылка на картинку не освобождает от её условий.

Сохраняйте sourceIds, источники и оговорки неопределённости вместе с описаниями. Для нового использования проверяйте ссылки на действующие условия первоисточников.