Skip to content

SpaceTrackClient

SpaceTrackClient 

SpaceTrackClient(identity: str, password: str, base_url: str = None, rate_limit: RateLimitConfig = None)

SpaceTrack API client with session-based authentication.

Handles authentication and query execution against Space-Track.org. Lazily authenticates on first query and re-authenticates on session expiry.

Parameters:

Name Type Description Default
identity str

Space-Track.org login email.

 required
password str

Space-Track.org password.

 required
base_url str

Custom base URL for testing.

 None
rate_limit RateLimitConfig

Rate limit configuration. Defaults to 25 requests/minute, 250 requests/hour.

 None
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")

# With custom rate limits
config = bh.RateLimitConfig(max_per_minute=10, max_per_hour=100)
client = bh.SpaceTrackClient("user@example.com", "password", rate_limit=config)

query = (
    bh.SpaceTrackQuery(bh.RequestClass.GP)
    .filter("NORAD_CAT_ID", "25544")
    .order_by("EPOCH", bh.SortOrder.DESC)
    .limit(1)
)
data = client.query_json(query)

Initialize instance.

authenticate method descriptor 

authenticate() -> Any

Explicitly authenticate with Space-Track.org.

Called automatically on first query. Call explicitly to verify credentials early.

Raises:

Type Description
BraheError

If authentication fails.

fileshare_delete method descriptor 

fileshare_delete(file_id: str) -> str

Delete a file from the Space-Track file share.

Parameters:

Name Type Description Default
file_id str

File identifier to delete.

 required

Returns:

Name Type Description
str str

Server response.

Raises:

Type Description
BraheError

On network, auth, or deletion errors.

fileshare_download method descriptor 

fileshare_download(file_id: str) -> bytes

Download a file from the Space-Track file share.

Parameters:

Name Type Description Default
file_id str

File identifier to download.

 required

Returns:

Name Type Description
bytes bytes

File content as bytes.

Raises:

Type Description
BraheError

On network, auth, or download errors.
Example 
1
2
3
4
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
data = client.fileshare_download("12345")

fileshare_download_folder method descriptor 

fileshare_download_folder(folder_id: str) -> bytes

Download all files in a folder from the Space-Track file share.

Parameters:

Name Type Description Default
folder_id str

Folder identifier to download.

 required

Returns:

Name Type Description
bytes bytes

Folder content as bytes (typically a zip archive).

Raises:

Type Description
BraheError

On network, auth, or download errors.

fileshare_list_files method descriptor 

fileshare_list_files() -> list[FileShareFileRecord]

List files in the Space-Track file share.

Returns:

Type Description
list[FileShareFileRecord]

list[FileShareFileRecord]: File metadata records.

Raises:

Type Description
BraheError

On network, auth, or parse errors.
Example 
1
2
3
4
5
6
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
files = client.fileshare_list_files()
for f in files:
    print(f.file_name, f.file_size)

fileshare_list_folders method descriptor 

fileshare_list_folders() -> list[FolderRecord]

List folders in the Space-Track file share.

Returns:

Type Description
list[FolderRecord]

list[FolderRecord]: Folder metadata records.

Raises:

Type Description
BraheError

On network, auth, or parse errors.

fileshare_upload method descriptor 

fileshare_upload(folder_id: str, file_name: str, file_data: bytes) -> str

Upload a file to the Space-Track file share.

Parameters:

Name Type Description Default
folder_id str

Target folder identifier.

 required
file_name str

Name for the uploaded file.

 required
file_data bytes

File content as bytes.

 required

Returns:

Name Type Description
str str

Server response (typically JSON confirmation).

Raises:

Type Description
BraheError

On network, auth, or upload errors.
Example 
1
2
3
4
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
response = client.fileshare_upload("100", "data.txt", b"file contents")

publicfiles_download method descriptor 

publicfiles_download(file_name: str) -> bytes

Download a public file from Space-Track (no auth required).

Parameters:

Name Type Description Default
file_name str

Name of the public file to download.

 required

Returns:

Name Type Description
bytes bytes

File content as bytes.

Raises:

Type Description
BraheError

On network or download errors.
Example 
1
2
3
4
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
data = client.publicfiles_download("catalog.txt")

publicfiles_list_dirs method descriptor 

publicfiles_list_dirs() -> list[dict]

List public file directories on Space-Track (no auth required).

Returns:

Type Description
list[dict]

list[dict]: Directory listing as JSON objects.

Raises:

Type Description
BraheError

On network or parse errors.

query_gp method descriptor 

query_gp(query: SpaceTrackQuery) -> list[GPRecord]

Execute a GP query and return typed GP records.

Parameters:

Name Type Description Default
query SpaceTrackQuery

The query to execute (must use JSON format).

 required

Returns:

Type Description
list[GPRecord]

list[GPRecord]: List of typed GP records.

Raises:

Type Description
BraheError

On network, auth, parse, or format errors.
Example 
1
2
3
4
5
6
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
query = bh.SpaceTrackQuery(bh.RequestClass.GP).filter("NORAD_CAT_ID", "25544").limit(1)
records = client.query_gp(query)
print(records[0].object_name)

query_json method descriptor 

query_json(query: SpaceTrackQuery) -> list[dict]

Execute a query and return parsed JSON values.

Parameters:

Name Type Description Default
query SpaceTrackQuery

The query to execute (must use JSON format).

 required

Returns:

Type Description
list[dict]

list[dict]: List of JSON objects.

Raises:

Type Description
BraheError

On network, auth, parse, or format errors.
Example 
1
2
3
4
5
6
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
query = bh.SpaceTrackQuery(bh.RequestClass.GP).filter("NORAD_CAT_ID", "25544").limit(1)
data = client.query_json(query)
print(data[0]["OBJECT_NAME"])

query_raw method descriptor 

query_raw(query: SpaceTrackQuery) -> str

Execute a query and return the raw response body as a string.

Parameters:

Name Type Description Default
query SpaceTrackQuery

The query to execute.

 required

Returns:

Name Type Description
str str

Raw response body.

Raises:

Type Description
BraheError

On network, auth, or HTTP errors.

query_satcat method descriptor 

query_satcat(query: SpaceTrackQuery) -> list[SATCATRecord]

Execute a SATCAT query and return typed SATCAT records.

Parameters:

Name Type Description Default
query SpaceTrackQuery

The query to execute (must use JSON format).

 required

Returns:

Type Description
list[SATCATRecord]

list[SATCATRecord]: List of typed SATCAT records.

Raises:

Type Description
BraheError

On network, auth, parse, or format errors.
Example 
1
2
3
4
5
6
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
query = bh.SpaceTrackQuery(bh.RequestClass.SATCAT).filter("NORAD_CAT_ID", "25544").limit(1)
records = client.query_satcat(query)
print(records[0].satname)

spephemeris_download method descriptor 

spephemeris_download(file_id: str) -> bytes

Download an SP ephemeris file from Space-Track.

Parameters:

Name Type Description Default
file_id str

SP ephemeris file identifier.

 required

Returns:

Name Type Description
bytes bytes

Ephemeris file content as bytes.

Raises:

Type Description
BraheError

On network, auth, or download errors.
Example 
1
2
3
4
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
data = client.spephemeris_download("99999")

spephemeris_file_history method descriptor 

spephemeris_file_history() -> list[dict]

List SP ephemeris file history.

Returns:

Type Description
list[dict]

list[dict]: File history records as JSON objects.

Raises:

Type Description
BraheError

On network, auth, or parse errors.

spephemeris_list_files method descriptor 

spephemeris_list_files() -> list[SPEphemerisFileRecord]

List available SP ephemeris files.

Returns:

Type Description
list[SPEphemerisFileRecord]

list[SPEphemerisFileRecord]: Ephemeris file metadata records.

Raises:

Type Description
BraheError

On network, auth, or parse errors.
Example 
1
2
3
4
5
6
import brahe as bh

client = bh.SpaceTrackClient("user@example.com", "password")
files = client.spephemeris_list_files()
for f in files:
    print(f.file_name, f.norad_cat_id)

See Also