Usage

import spacetrack.operators as op
from spacetrack import SpaceTrackClient

with SpaceTrackClient(identity="user@example.com", password="password") as st:
    ...

Request classes are presented as methods on the SpaceTrackClient object. For example, st.tle_publish(). Each request class is part of a request controller. Since most request classes are only part of one request controller, spacetrack looks up the controller for you. It can be specified explicitly in several ways. All the following are equivalent:

st.gp_history()
st.gp_history(controller="basicspacedata")
st.basicspacedata.gp_history()
st.generic_request("gp_history")
st.generic_request("gp_history", controller="basicspacedata")

Request predicates are passed as keyword arguments. Valid arguments can be checked using the get_predicates() method. The following are equivalent:

st.gp_history.get_predicates()
st.gp_history.get_predicates(controller="basicspacedata")
st.basicspacedata.gp_history.get_predicates()
st.basicspacedata.get_predicates("gp_history")
st.get_predicates("gp_history")
st.get_predicates("gp_history", controller="basicspacedata")

Returned object:

[
    Predicate(name='creation_date', type_='datetime', nullable=True, default=None),
    Predicate(name='object_name', type_='str', nullable=True, default=None),
    Predicate(name='eccentricity', type_='float', nullable=True, default=None),
    ... # and many more
]

Internally, the client uses this mechanism to verify the keyword arguments. Types are not currently checked.

Streaming Downloads

It is possible to stream responses by passing iter_content=True (100 KiB chunks) or iter_lines=True to the request class methods.

Example

The same example is shown below synchronously and asynchronously.

import spacetrack.operators as op
from spacetrack import SpaceTrackClient

with SpaceTrackClient(identity="user@example.com", password="password") as st:
    data = st.gp(
        iter_lines=True,
        epoch=">now-30",
        mean_motion=op.inclusive_range(0.99, 1.01),
        eccentricity=op.less_than(0.01),
        format="tle",
    )

    with open("tle_latest.txt", "w") as fp:
        for line in data:
            fp.write(line + "\n")

import asyncio

import spacetrack.operators as op
from spacetrack.aio import AsyncSpaceTrackClient


async def download_latest_tles():
    async with AsyncSpaceTrackClient(
        identity="user@example.com", password="password"
    ) as st:
        data = await st.gp(
            iter_lines=True,
            epoch=">now-30",
            mean_motion=op.inclusive_range(0.99, 1.01),
            eccentricity=op.less_than(0.01),
            format="tle",
        )

        with open("tle_latest.txt", "w") as fp:
            async for line in data:
                fp.write(line + "\n")


loop = asyncio.get_event_loop()
loop.run_until_complete(download_latest_tles())

File Uploads

To use the upload request class, pass a file keyword argument with the opened file:

from spacetrack import SpaceTrackClient

with SpaceTrackClient(identity="user@example.com", password="password") as st:
    with open("somefile.txt", "rb") as fp:
        st.upload(file=fp)

Rate Limiting

As quoted in the Space-Track API Use Guidelines:

“Space-track throttles API use in order to maintain consistent performance for all users. To avoid error messages, please limit your query frequency.”

Limit API queries to less than 30 requests per 1 minute(s) / 300 requests per 1 hour(s)

Important

While this library will manage the above rate limiting for you, it cannot help you with the other limits outlined in the API Use Guidelines such as how often you download certain data.

Also consider that the above rate limiting is handled per process and cannot determine how often you start new processes or scripts using your account. The SpaceTrackClient.rush_store argument can be used to use a distributed cache for this purpose.

The client will ensure that no more requests than this are made by sleeping if the rate exceeds this. This will be logged to the spacetrack module’s logger. You can register a callback with the SpaceTrackClient or AsyncSpaceTrackClient classes. It will be passed a value to be compared against time.monotonic() to get the remaining time:

import time

from spacetrack import SpaceTrackClient


def mycallback(until):
    duration = int(round(until - time.monotonic()))
    print("Sleeping for {:d} seconds.".format(duration))


with SpaceTrackClient(identity="user@example.com", password="password") as st:
    st.callback = mycallback

Sample Queries

The Space-Track website lists some sample queries, which are shown here using the Python module.

output = st.boxscore(format="csv")

decay_epoch = op.inclusive_range(date(2012, 7, 2), date(2012, 7, 9))
st.decay(decay_epoch=decay_epoch, orderby=["norad_cat_id", "precedence"], format="xml")

st.satcat(launch=">now-7", current="Y", orderby="launch desc", format="html")

st.satcat(
    period=op.inclusive_range(1430, 1450),
    current="Y",
    decay=None,
    orderby="norad_cat_id",
    format="html",
)

st.satcat(period=op.less_than(128), decay=None, current="Y")

st.gp(
   epoch=">now-30",
   mean_motion=op.inclusive_range(0.99, 1.01),
   eccentricity=op.less_than(0.01),
   format="tle",
)

st.gp(
    epoch=">now-30", mean_motion=op.greater_than(11.25), format="3le"
)

st.gp(
    norad_cat_id=[
        36000,
        op.inclusive_range(36001, 36004),
        op.like(36005),
        op.startswith(3600),
        36010,
    ],
    orderby="norad_cat_id",
    format="html",
)

st.gp_history(norad_cat_id=25544, orderby="epoch desc", limit=22, format="tle")

st.gp_history(norad_cat_id=25544, orderby="epoch desc", limit=22, format="xml")

st.tip(norad_cat_id=[60, 38462, 38351], format="html")

st.cdm(constellation="iridium", limit=10, orderby="creation_date desc", format="html")

st.cdm(constellation="iridium", limit=10, orderby="creation_date desc", format="kvn")

st.cdm(
    constellation="intelsat",
    tca=">now",
    predicates=["message_for", "tca", "miss_distance"],
    orderby="miss_distance",
    format="html",
    metadata=True,
)

st.cdm(
    constellation="intelsat",
    tca=">now",
    predicates=["message_for", "tca", "miss_distance"],
    orderby="miss_distance",
    format="kvn",
)