Metadata-Version: 2.4
Name: satnogs-api-client
Version: 0.4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Communications :: Ham Radio
License-File: LICENSE
Summary: Python bindings for the SatNOGS Network API, written in Rust
Keywords: satnogs,satellite,ground station,api
Author: Martin Hübner
License-Expression: AGPL-3.0-only
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Issues, https://codeberg.org/akira25/satnogs-api-client/issues
Project-URL: Repository, https://codeberg.org/akira25/satnogs-api-client

# satnogs-api-client

A rust-based API client for the [SatNOGS network](https://network.satnogs.org)

> [!TIP]
> Main Repository: [codeberg.org/akira25/satnogs-api-client](https://codeberg.org/akira25/satnogs-api-client). Please contribute there.

This api client provides a rust and a python interface to communicate with the JSON-API of the SatNOGS network.

## How to install

You can get this packet easily via pypi:

```sh
$ pip install satnogs-api-client
```

For usage examples, you can have a look in the examples section below.

## How to build

For building this, you will need a rust-toolchain. Please get it from https://rustup.rs

For development purposes you can build the project using uv:

```sh
$ uv run maturin develop
# evaluating in python env
$ uv run python
```

## Examples

This sections shows you some examples, on how you can use this package.
Conceptually, functions are divided into different groups:

- Single object calls, like e.g. `get_observation(id: uint64)` and
- Multi-Object calls e.g.: `get_observation*s*(f: Filter)`

Multi-Object functions take a filter object, that defines criteria that you search for. As your request might be that big, that it will be paginated by the server, you should consider performance inplications there.

### Example: Fetch observations

This sample requests the observations made by station 106 during the last 12 hours:

```python
from satnogs_api_client import APIClient, ObservationFilter
import datetime as dt

api = APIClient("https://network.satnogs.org/api")

now = dt.datetime.utcnow()

# create Jobfilter with keyword-syntax
f = ObservationFilter(
    ground_station = 106,
    start = now - dt.timedelta(hour=12),
    end = now,
)

obs = api.get_observations(f)

for ob in obs:
    print(ob)

```

### Example: Authenticate with API-Token

For some actions, you must authenticate against the API with your token.

```python
from satnogs_api_client import APIClient, ObservationFilter
import datetime as dt

api = APIClient("https://network.satnogs.org/api", api_token="INSERT_TOKEN_HERE")

s = api.get_station(1860)
print(s)
```

### Example: Delete a Job on your own Station

This will delete the job/observation from your stations observation scheduler. This works for observations that will start in the future only.

```python
from satnogs_api_client import APIClient, JobFilter, ObservationFilter
from datetime import datetime, UTC
from time import sleep

token = "INSERT_TOKEN_HERE"
api = APIClient("https://network.satnogs.org/api", token)

f = ObservationFilter(ground_station=106, end__gt=datetime.now(tz=UTC))

jobs = api.get_observations(f)

for j in jobs:
    print(j.id, j.start, f"https://network.satnogs.org/observations/{j.id}/", j.observer)

for j in jobs:
    if j.observer == "Someone":
        print(f"deleting {j.id}...")
        api.delete_job(j.id)
        sleep(1)
```

