API Documentation

POST /api/v1/auth
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

{
  "token": "Aha8iPmNDFr76K6jhweaLEHf",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Authorization: Bearer YOUR_API_TOKEN

{
  "error": {
    "code": "TIMESTAMP_OUTSIDE_WINDOW",
    "message": "timestamp outside analysis window",
    "details": {
      "valid_range": {
        "start": "2025-12-06T08:00:00Z",
        "end": "2025-12-13T08:00:00Z"
      }
    }
  },
  "meta": {
    "request_id": "a702aa12-...",
    "timestamp": "2025-12-09T10:30:00Z"
  }
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699876543
Retry-After: 45

{"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded"}, "retry_after": 45}

# 1. Clone the client library repository
# Download client libraries from https://vega.space/api-clients/
# Each language directory contains a README, client class, and runnable script
cd python/    # (or javascript/, go/, rust/, java/, cpp/, matlab/)

# 2. Copy the environment template and add your credentials
cp .env.example .env      # (MATLAB: cp env.example env.local)
# Edit .env — set VEGA_API_TOKEN  (or both VEGA_EMAIL + VEGA_PASSWORD)

# 3. Install dependencies (if needed) and run
pip install -r requirements.txt
python pull_interference.py

POST /auth  (or use API token)
  → GET /tracked_satellites     → get satellite IDs
  → GET /ground_stations        → get station lat/lon
  → GET /interference/timeseries?tracked_satellite_id=ID&lat=LAT&lon=LON

# Set your token
export TOKEN="your_api_token_here"

# Check auth
curl -s -H "Authorization: Bearer $TOKEN" "https://vega.space/api/v1/me"

# List your satellites
curl -s -H "Authorization: Bearer $TOKEN" "https://vega.space/api/v1/tracked_satellites"

# List your ground stations
curl -s -H "Authorization: Bearer $TOKEN" "https://vega.space/api/v1/ground_stations"

# Pull interference timeseries (full 7-day window, omit start/end)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://vega.space/api/v1/interference/timeseries?tracked_satellite_id=1&lat=37.76&lon=-122.44"

# Filter by frequency band
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://vega.space/api/v1/interference/timeseries?tracked_satellite_id=1&lat=37.76&lon=-122.44&frequency_band=Ka"

import requests

BASE_URL = "https://vega.space/api/v1"
TOKEN = "YOUR_API_TOKEN"
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {TOKEN}"})

# List tracked satellites
sats = session.get(f"{BASE_URL}/tracked_satellites").json()
for sat in sats["data"]["tracked_satellites"]:
    info = sat["satellite"]
    print(f"ID: {sat['id']}  Name: {info['name']}  NORAD: {info['norad_number']}")

# List ground stations
stations = session.get(f"{BASE_URL}/ground_stations").json()
for gs in stations["data"]["ground_stations"]:
    print(f"ID: {gs['id']}  Name: {gs['name']}  Lat: {gs['latitude']}  Lon: {gs['longitude']}")

# Pull interference timeseries (full 7-day window)
resp = session.get(f"{BASE_URL}/interference/timeseries", params={
    "tracked_satellite_id": 1,
    "lat": 37.76,
    "lon": -122.44,
})
data = resp.json()["data"]
ts = data["timeseries"]
intensities = [p["intensity"] for p in ts]
print(f"Points: {len(ts)}, Max: {max(intensities)}, Mean: {sum(intensities)/len(intensities):.4f}")

# Filter by frequency band
resp = session.get(f"{BASE_URL}/interference/timeseries", params={
    "tracked_satellite_id": 1,
    "lat": 37.76,
    "lon": -122.44,
    "frequency_band": "Ka",
})

import axios from "axios";

const BASE_URL = "https://vega.space/api/v1";
const TOKEN = "YOUR_API_TOKEN";
const http = axios.create({
  baseURL: BASE_URL,
  headers: { Authorization: `Bearer ${TOKEN}` },
});

// List tracked satellites
const { data: satResp } = await http.get("/tracked_satellites");
for (const sat of satResp.data.tracked_satellites) {
  console.log(`ID: ${sat.id}  Name: ${sat.satellite.name}`);
}

// List ground stations
const { data: gsResp } = await http.get("/ground_stations");
for (const gs of gsResp.data.ground_stations) {
  console.log(`${gs.name} (${gs.latitude}, ${gs.longitude})`);
}

// Pull interference timeseries (full 7-day window)
const { data: tsResp } = await http.get("/interference/timeseries", {
  params: { tracked_satellite_id: 1, lat: 37.76, lon: -122.44 },
});
const ts = tsResp.data.timeseries;
const intensities = ts.map((p) => p.intensity);
console.log(`Points: ${ts.length}, Max: ${Math.max(...intensities)}`);

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    baseURL := "https://vega.space/api/v1"
    token := "YOUR_API_TOKEN"

    // Helper: authenticated GET
    get := func(path string) []byte {
        req, _ := http.NewRequest("GET", baseURL+path, nil)
        req.Header.Set("Authorization", "Bearer "+token)
        resp, _ := http.DefaultClient.Do(req)
        defer resp.Body.Close()
        body, _ := io.ReadAll(resp.Body)
        return body
    }

    // List tracked satellites
    fmt.Println(string(get("/tracked_satellites")))

    // Pull interference timeseries
    body := get("/interference/timeseries?tracked_satellite_id=1&lat=37.76&lon=-122.44")
    var result map[string]interface{}
    json.Unmarshal(body, &result)
    fmt.Println("Response:", string(body))
}

use reqwest::blocking::Client;

fn main() {
    let client = Client::builder().timeout(std::time::Duration::from_secs(120)).build().unwrap();
    let base = "https://vega.space/api/v1";
    let token = "YOUR_API_TOKEN";

    // List tracked satellites
    let resp = client.get(format!("{}/tracked_satellites", base))
        .bearer_auth(token)
        .send().unwrap().text().unwrap();
    println!("{}", resp);

    // Pull interference timeseries
    let resp = client.get(format!("{}/interference/timeseries", base))
        .bearer_auth(token)
        .query(&[("tracked_satellite_id", "1"), ("lat", "37.76"), ("lon", "-122.44")])
        .send().unwrap().text().unwrap();
    println!("{}", resp);
}

import java.net.URI;
import java.net.http.*;

public class VegaExample {
    static final String BASE = "https://vega.space/api/v1";
    static final String TOKEN = "YOUR_API_TOKEN";
    static final HttpClient client = HttpClient.newHttpClient();

    static String get(String path) throws Exception {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + path))
            .header("Authorization", "Bearer " + TOKEN)
            .GET().build();
        return client.send(req, HttpResponse.BodyHandlers.ofString()).body();
    }

    public static void main(String[] args) throws Exception {
        // List tracked satellites
        System.out.println(get("/tracked_satellites"));

        // Pull interference timeseries
        System.out.println(get("/interference/timeseries"
            + "?tracked_satellite_id=1&lat=37.76&lon=-122.44"));
    }
}

#include <curl/curl.h>
#include <string>
#include <iostream>

static size_t write_cb(void* p, size_t sz, size_t n, void* ud) {
    ((std::string*)ud)->append((char*)p, sz * n);
    return sz * n;
}

std::string get(const std::string& url, const std::string& token) {
    std::string body;
    CURL* curl = curl_easy_init();
    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb);
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &body);
    struct curl_slist* h = curl_slist_append(nullptr, ("Authorization: Bearer " + token).c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, h);
    curl_easy_perform(curl);
    curl_slist_free_all(h);
    curl_easy_cleanup(curl);
    return body;
}

int main() {
    std::string base = "https://vega.space/api/v1";
    std::string token = "YOUR_API_TOKEN";

    // List tracked satellites
    std::cout << get(base + "/tracked_satellites", token) << std::endl;

    // Pull interference timeseries
    std::cout << get(base + "/interference/timeseries"
        "?tracked_satellite_id=1&lat=37.76&lon=-122.44", token) << std::endl;
}

base_url = 'https://vega.space/api/v1';
token = 'YOUR_API_TOKEN';
opts = weboptions('HeaderFields', {'Authorization', ['Bearer ' token]}, ...
                   'ContentType', 'json', 'Timeout', 30);

% List tracked satellites
sats = webread([base_url '/tracked_satellites'], opts);
for i = 1:length(sats.data.tracked_satellites)
    s = sats.data.tracked_satellites(i);
    fprintf('ID: %d  Name: %s\n', s.id, s.satellite.name);
end

% Pull interference timeseries (full 7-day window)
data = webread([base_url '/interference/timeseries'], ...
    'tracked_satellite_id', '1', 'lat', '37.76', 'lon', '-122.44', opts);
intensities = [data.data.timeseries.intensity];
fprintf('Points: %d, Max: %d, Mean: %.4f\n', length(intensities), max(intensities), mean(intensities));