SpaceTrack

The SpaceTrack package allows to interact with www.space-track.org API.

1. Installation
2. Client
3. Authentication
4. SpaceTrack entities
   • Filters
   • Sorting
5. Supported entities
   • Satellite catalog
   • General perturbations

1 Installation

To add SpaceTrack package into your project one should insert this line into dependencies array in your Package.swift file:

.package(url: "https://github.com/fundaev/spacetrack.git", from: "1.1.0"),

One should also add something like that:

.target(name: "MyProject", dependencies: [.product(name: "SpaceTrack", package: "spacetrack")]),

in your target specification.

2 Client

The Client class is "entry point" of this package. It's responsible for:

1. Authentication;
2. Receiving data from www.space-track.org.

It uses AsyncHTTPClient package, based on swift-nio package, and threfore requires EventLoopGroup instance.

You may ask client to create this group:

import Foundation
import NIOCore
import SpaceTrack 
...
let client = Client(eventLoopGroupProvider: .createNew)
...

or pass already existing one:

import Foundation
import NIOCore
import SpaceTrack 
...
let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount)
let client = Client(eventLoopGroupProvider: .shared(eventLoopGroup))
...

Alternatively one can ask client to create event loop group itself:

3 Authentication

www.space-track.org provides a data to registered users only. It means that you should create an account there if you don't have it yet.

To receive a data you should authorize the client instance.

let authResult = try await client.auth(username: "your.username@test.info", password: "123456")
if (authResult != Result.Success) {
    // handle failed authentication
}

let authFuture = client.authorize(username: "your.username@test.info", password: "123456")
let result = try authFuture.wait()
if (result != Result.Success) {
    // handle failed authentication
}

4 SpaceTrack entities

www.space-track.org provides several kinds of data: satellite catalog, general perturbations, predicted and historical decay information etc. Each of them can be requested by a specifiec request. The corresponding responses contains a list of some entities.

For example, the response for satellite catalog request contains a list of satellites. The satellite in this terminology is just set of properties: satellite name, number, launch date, launch number in the year etc.

SpaceTrack package provides speciel public structures for each of these entities. Let's name them entities structures. The received entities list is wrapped by another structure, containing the list itself and the total number of such entities, satisfying the provided filter.

4.1 Filters

To support filters each entity structure provides Key enumiration. Its members represent the properties of coresponding entities. This enumiration supports the following operators: ==, !=, <, >. One should use them to construct some filter. For example:

let filter = Satellite.Key.name == "NOAA 17"

There are also such methods as oneOf and between:

let filter1 = Satellite.Key.noradCatId.oneOf(values: [25544, 23118, 19186])
let filter2 = Satellite.Key.launchYear.between(from: 2007, to: 2022)

One may construct filter with several conditions using && operator:

let filter = Satellite.Key.name == "NOAA" && Satellite.Key.inclination > 98;

4.2 Sorting

Key enumirations can be used to sort the requested entities list. For that Key provides asc and desc read-only properties:

let order1 = Satellite.Key.name.asc
let order2 = Satellite.Key.launchYear.desc

You may sort the result by several fields using & operator:

let order = Satellite.Key.name.asc & Satellite.Key.launchYear.desc

5 Supported entities

5.1 Satellite catalog

To get the available list of the satellites one should use satelliteCatalog method.

For example, let's request first 10 satellites with "NOAA" word in their names, launched after 2000 year and sorted by name:

let response = try await client.satelliteCatalog(
    where: Satellite.Key.name == "~~NOAA~~" && Satellite.Key.launchYear > 2000,
    order: Satellite.Key.name.asc,
    limit: 10,
    offset: 100
)

for satellite in response.data {
    print("\(satellite.name)")
}
print("-------------------------------")
print("\(response.data.count) item(s) from \(response.count)")

let satFuture = client.requestSatelliteCatalog(
    where: Satellite.Key.name == "~~NOAA~~" && Satellite.Key.launchYear > 2000,
    order: Satellite.Key.name.asc,
    limit: 10,
    offset: 100
)
let result = try satFuture.wait()
for sat in result.data {
    print("\(sat.name)")
}
print("-------------------------------")
print("\(result.data.count) item(s) from \(result.count)")

5.2 General perturbations

To get the keplerian elements of the satellite one should use generalPerturbations method:

let response = try await client.generalPerturbations(
    where: GeneralPerturbations.Key.noradCatId == 25544,
    order: GeneralPerturbations.Key.noradCatId.asc,
    limit: 10,
    offset: 0
)
for gp in response.data {
    print("\(gp.semimajorAxis)")
}
print("-------------------------------")
print("\(response.data.count) item(s) from \(response.count)")

let gpFuture = client.requestGeneralPerturbations(
    where: GeneralPerturbations.Key.noradCatId == 25544,
    order: GeneralPerturbations.Key.noradCatId.asc,
    limit: 10,
    offset: 0
)
let result = try gpFuture.wait()
for gp in result.data {
    print("\(gp.semimajorAxis)")
}
print("-------------------------------")
print("\(result.data.count) item(s) from \(result.count)")