Usage¶

import spacetrack.operators as op
from spacetrack import SpaceTrackClient

st = SpaceTrackClient(identity='user@example.com', password='password')

Request classes are presented as methods on the SpaceTrackClient object. For example, st.tle_publish(). Request predicates are passed as keyword arguments. Valid arguments can be checked using the get_predicates() method.

st.tle_publish.get_predicates()
# which is equivalent to
st.get_predicates('tle_publish')

Returned object:

[Predicate(name='publish_epoch', type_='datetime', nullable=False),
 Predicate(name='tle_line1', type_='str', nullable=False),
 Predicate(name='tle_line2', type_='str', nullable=False)]

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

st = SpaceTrackClient(identity='user@example.com', password='password')

data = st.tle_latest(iter_lines=True, ordinal=1, 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():
    st = AsyncSpaceTrackClient(identity='user@example.com',
                               password='password')

    with st:
        data = await st.tle_latest(
            iter_lines=True, ordinal=1, 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())

Rate Limiter¶

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

The client will ensure that no more than 19 HTTP requests are sent per minute 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 the time that the module is sleeping until, in seconds since the epoch (as with time.time()).

import time

from spacetrack import SpaceTrackClient

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

st = SpaceTrackClient(identity='user@example.com', password='password')
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.tle_latest(ordinal=1, epoch='>now-30',
              mean_motion=op.inclusive_range(0.99, 1.01),
              eccentricity=op.less_than(0.01), format='tle')

st.tle_latest(ordinal=1, epoch='>now-30', mean_motion=op.greater_than(11.25),
              format='3le')

st.tle_latest(favorites='Amateur', ordinal=1, epoch='>now-30', format='3le')

st.tle_latest(
    ordinal=1,
    norad_cat_id=[
        36000,
        op.inclusive_range(36001, 36004),
        op.like(36005),
        op.startswith(3600),
        36010
    ],
    orderby='norad_cat_id',
    format='html')

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

st.omm(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')