IonoFlux Node.js SDK

1. Create a Server key

Sign in on your account page and create a Server API key. This SDK is for Node.js, so keep the key on your backend. Do not include it in browser or React client bundles, HTML, logs or source control.

Server key creation requires a service URL. Use a URL that fits the existing service policy; the SDK does not issue keys or bypass this requirement.

export IONOFLUX_API_KEY='your-server-key'

2. Quick start

import { Client } from 'ionoflux';

const client = new Client();
try {
  const current = await client.spaceWeather.current();
  console.log(current.data);
  console.log(current.rateLimit.remaining);
} finally {
  client.close();
}

new Client() reads IONOFLUX_API_KEY; The apiKey option overrides it. Save the ESM examples as .mjs (or use a package with type: module). Dates accept a valid Date or an ISO string with Z/an explicit offset and are sent in UTC. sources() and data.status() work without a key and never send a configured key.

import { Client, RateLimitError } from 'ionoflux';

const client = new Client({ timeoutMs: 10000, maxRetries: 1 });
try {
  const series = await client.solar.flux({
    start: '2026-10-01T00:00:00Z',
    end: '2026-10-02T00:00:00Z',
    interval: '1h', limit: 100,
  });
  console.log(series.data.unit, series.data.attribution);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(error.retryAfter, error.rateLimit.resetSeconds);
  } else {
    throw error;
  }
} finally {
  client.close();
}

CommonJS is supported too: use require below, then call the same Promise methods inside an async function. TypeScript declarations are included.

const { Client } = require('ionoflux');

Supported calls

Every Promise resolves to APIResponse with data (original JSON fields), rawBody (bytes), statusCode, safe headers and rateLimit. Input options use camelCase; returned JSON field names stay unchanged. Series calls share start, end, interval and limit options.

Ionosphere, propagation and observations

Included from 0.1.3; all these calls need a Server key. Locations accept "lat,lon", a Maidenhead locator or a place name. Invalid argument ranges raise RangeError before sending a request.

import { Client } from 'ionoflux';

const client = new Client();
try {
  const muf = await client.ionosphere.muf({ lat: 37.57, lon: 126.98 });
  console.log(muf.data.muf_mhz, muf.data.attribution);

  const path = await client.propagation.path({
    from: 'Seoul, South Korea', to: 'FN20', frequency: 14.074, mode: 'ft8',
  });
  console.log(path.data.prediction, path.data.model);

  const heard = await client.observations.paths({
    from: 'PM37', to: 'PM95', hours: 1, band: '20m',
  });
  console.log(heard.data.a_to_b);
} finally {
  client.close();
}

Model TEC/MUF and every propagation result are model outputs from NOAA GloTEC maps; ionosonde MUF and stations are measurements. Reception reports prove one-way propagation at that moment, but no reports does not mean a closed band. Keep each response's attribution: WSPRnet data is not for commercial use.

Scope and limits

This version supports Node.js 22+ and does not provide a browser/React client, map rendering, or bulk/historical spot downloads. Use the REST API for other operations. The SDK uses HTTPS and refuses redirects.

timeoutMs defaults to 10000 ms for each complete attempt, including reading the body. maxRetries defaults to 1 (maximum 3), for selected transient network failures and HTTP 502/503/504. A Retry-After header or remaining quota 0 suppresses HTTP retries; 429 is never automatically retried. Retries can consume quota. close() aborts pending requests without closing the shared Node.js fetch pool.

Details: API options and limits · Changelog · Korean README

License and terms

The SDK code is licensed under the PolyForm Noncommercial License 1.0.0. It permits noncommercial use, including personal and hobby use and the educational, research and other institutional uses it lists. Commercial use outside those permissions requires a separate written license; it is not an OSI open-source license.

When you redistribute the SDK, keep the license terms and the Required Notice from NOTICE:

Required Notice: IonoFlux (https://ionoflux.runvia.app)

The SDK license covers the code only. API access, attribution of API results and the original providers' data licenses are separate; please keep each response's source and attribution.