API Documentation - VA3ODC Network

Overview

The VA3ODC Network provides two high-performance public gateways for retrieving real-time ICMP ping diagnostics and host configurations. Both endpoints sweep network nodes in parallel via background processes to deliver responses in under 2 seconds.

Zero-CORS

JavaScript & JSONP API

For client-side websites, static pages, and standalone .js scripts. Loads via a standard <script> tag with zero CORS restrictions.

https://dstar.tor.solosoft.ca/online/api-jsonp.php

REST

Standard JSON API

For backend servers, microservices, cron jobs, Python, Node.js, and web apps using fetch() or cURL.

https://dstar.tor.solosoft.ca/online/api.php

Interactive API Sandbox

Test endpoints directly in your browser and inspect live response payloads.

GET

Response Payload

Status: Ready Time: -- ms

// Click "Execute Request" above to test live endpoint...

Drop-in HTML Status Badge Widget Generator

Generate custom embeddable HTML & JavaScript status badges for any individual repeater or the entire network:

Choose Repeater / Target:

Generated HTML & JS Embed Code:

<!-- Loading embed snippet... -->

Minimal Status Dot & Latency Indicator Generator

Generate an ultra-compact, inline HTML snippet (colored status dot + latency text) to embed inside tables, headers, lists, or navigation bars:

Choose Repeater:

Generated Inline HTML & JS Snippet: Ultra-Lightweight

<!-- Loading snippet... -->

Integration Examples by Language

1. Client-Side JavaScript (Dynamic Zero-CORS)

Fetch status dynamically on button click or timer without page reloads:

function checkNetworkStatus() {
  const script = document.createElement('script');
  const callbackName = 'va3odc_cb_' + Date.now();
  
  window[callbackName] = function(data) {
    console.log("Active hosts:", data.results.filter(h => h.online));
    delete window[callbackName];
    script.remove();
  };

  script.src = `https://dstar.tor.solosoft.ca/online/api-jsonp.php?callback=${callbackName}`;
  document.head.appendChild(script);
}

// Call on demand
checkNetworkStatus();

2. Modern JavaScript (Fetch / async-await)

Using standard async/await for applications that support CORS:

async function fetchStatus() {
  try {
    const res = await fetch('https://dstar.tor.solosoft.ca/online/api.php');
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const data = await res.json();
    
    data.results.forEach(host => {
      console.log(`${host.name} (${host.ip}): ${host.online ? 'ONLINE (' + host.latency + 'ms)' : 'OFFLINE'}`);
    });
  } catch (err) {
    console.error("Diagnostic error:", err);
  }
}

fetchStatus();

3. Python (requests)

For Python scripts, bots, or server monitoring jobs:

import requests

url = "https://dstar.tor.solosoft.ca/online/api.php"
response = requests.get(url, timeout=5)
data = response.json()

if data.get("success"):
    for host in data["results"]:
        status = f"ONLINE ({host['latency']}ms)" if host["online"] else "OFFLINE"
        print(f"[{host['name']}] {host['details']} -> {status}")

4. PHP (cURL / file_get_contents)

Include status directly inside your PHP websites:

<?php
$json = file_get_contents("https://dstar.tor.solosoft.ca/online/api.php");
$data = json_decode($json, true);

if ($data && $data['success']) {
    foreach ($data['results'] as $host) {
        $state = $host['online'] ? "ONLINE ({$host['latency']}ms)" : "OFFLINE";
        echo "Host: {$host['name']} - {$state}<br>";
    }
}
?>

Endpoint & Parameter Reference

Parameter	Type	Supported Gateway	Description
`id`	Integer (0-9)	`api.php`, `api-jsonp.php`	Diagnoses a specific host index (e.g. `?id=0` for pistar1).
`list`	Integer (`1`)	`api.php`, `api-jsonp.php`	Returns host configuration metadata immediately without executing ICMP ping sweeps.
`callback`	String	`api-jsonp.php`	Wraps output in a custom JavaScript callback function name (e.g. `?callback=myHandler`).
`var`	String	`api-jsonp.php`	Sets the global variable name on the `window` object (defaults to `VA3ODC_STATUS`).

Response Schema Dictionary

Field	Type	Description
`success`	Boolean	`true` when the diagnostic sweep executed normally.
`timestamp`	Integer	UNIX epoch timestamp of when the diagnostics completed.
`results[].id`	Integer	Zero-based index of the monitored system.
`results[].name`	String	Host identifier label (e.g. `"pistar1"`, `"VE3XII"`).
`results[].details`	String	Callsign and location description (e.g. `"VA3ODC B - Chatham"`).
`results[].ip`	String	Target IP address.
`results[].online`	Boolean	`true` if ICMP packet responded successfully; `false` if timed out.
`results[].latency`	Float \| null	Round-trip ping latency in milliseconds (`null` when offline).
`results[].interfaces`	Array	Configured quick action web interfaces (e.g. `["pistar", "wx"]`).