@kquika-inc/s-system

The TypeScript client for S-System, the airline operations platform from Kquika.

Flight operations and airport operations: live status, on-time performance, route analytics, stand utilization and terminal congestion, from the platform that forecasts disruption up to four days out.

npm install @kquika-inc/s-system

Browser and Node 18+. Fully typed, no fetch polyfill. MIT licensed.

Also available for Python as kquika-ssystem.

Data provenance

Every flight carries data_confidence, so your code can read the origin of a record before acting on it.

| Value | Meaning | |---|---| | live_feed | Observed from the live provider feed. | | database | Observed on an earlier read and persisted. |

Every record this API returns is an observation. live_feed is the current reading from the provider; database is the same reading persisted from an earlier call, so it may lag the feed. Neither is an estimate.

Fields are left null where the source carries no value. A null delay_minutes means no time was reported.

Denominators

on_time_percentage is calculated over measured_flights, and both counts are in the response. Flights that reported no time are excluded from that denominator, so other ratios can be derived from the same payload.

on_time counts departures within on_time_threshold_minutes, which is returned on the response and defaults to 15. Read it rather than assuming it.

on_time_percentage is null when the figure cannot be measured, and ontime_unavailable_reason says why. Three cases:

• Nothing was measured.
• Coverage was too thin to describe the operation.
• The sample was censored: every flight carrying a time was late, and none departed early or on schedule. This happens when the upstream feed publishes a delay only when there is one, so "on time" and "unknown" collapse into the same absence. A rate over only late flights reads near zero whatever the real punctuality is, so no rate is returned at all.

gate_conflicts is keyed on airport and gate together, so gate labels are only compared within a single station.

What you can call

| | Plan | |---|---| | List flights with origin, destination and date filters | Standard | | One flight by number | Standard | | Metrics: on-time performance, average delay, gate conflicts | Standard | | Search by number, route or date | Standard | | Route analytics: performance grouped by route | Professional | | Refresh the live feed on demand | Professional | | Airport overview: movements, delay, stand utilization | Standard | | Passenger heatmap: density by zone, measured or modeled | Professional | | Congestion: current level plus 1h and 3h forecast | Professional | | Disruption lists: the flights most at risk, with causes and actions | IOCC Briefing | | Aircraft rotations: how a delay travels through the day | Disruption Prediction or IOCC Briefing | | Passengers, crew and fuel: counts, duty margins and tankering | The matching capability, or IOCC Briefing | | Stations and airfield congestion | Airport Heatmap or IOCC Briefing |

Passenger intelligence is delivered through the application and through scheduled data delivery. Contact your account manager about direct access for your integration.

Plans and rate limits

Each key carries an hourly request limit, set with your plan. Every response reports it in X-RateLimit-Limit, with what remains in X-RateLimit-Remaining and in the quota block, so read it there instead of hardcoding a number. A refused request returns 429 with Retry-After, in seconds.

API access starts at Standard. Starter covers the dashboard and basic passenger insights without programmatic access.

Capabilities follow the plan too. GET /subscription returns the feature codes your account carries, so an integration can hide what it cannot reach instead of surfacing a 403 to a user who cannot act on it.

Using the client

Getting started

import { client, listFlights } from '@kquika-inc/s-system';

client.setConfig({
  baseUrl: 'https://www.s-system.cloud',
  headers: { 'X-API-Key': process.env.S_SYSTEM_API_KEY! },
});

const { data, error } = await listFlights({ query: { origin: 'JFK', limit: 25 } });

if (error || !data?.success) {
  console.error(data?.message ?? error);
} else {
  for (const f of data.data!.flights!) {
    console.log(f.flight_number, f.origin, f.destination, f.data_confidence);
  }
}

Check success before reading data. Every response carries {success, data, message}, and data is null when success is false.

data_confidence

for (const flight of data.data.flights) {
  // Both values are observations, so both are safe to schedule against.
  // Branch on freshness only when it matters to you: `database` may lag the
  // live feed by a sync interval.
  if (flight.data_confidence === 'live_feed') scheduleNow(flight);
  else queueForRefresh(flight);
}

live_feed is the current reading from the provider. database is the same reading persisted from an earlier call, so it may lag the feed by up to one sync interval.

TypeScript narrows the union, so a typo fails to compile instead of silently never matching.

Nulls

null carries meaning in each of these fields.

| Field | null means | |---|---| | delay_minutes | No time was reported. | | scheduled_departure | No schedule source covers this flight. | | departure_gate | Unassigned, or the source carries no gate. | | on_time_percentage | Nothing was measured. |

// Wrong: counts an unreported flight as on time.
const avg = flights.reduce((s, f) => s + (f.delay_minutes ?? 0), 0) / flights.length;

// Right: denominated on what was actually measured.
const measured = flights.filter(f => f.delay_minutes !== null);
const avg = measured.reduce((s, f) => s + f.delay_minutes!, 0) / measured.length;

Airport operations

import {
  getAirportOverview, getAirportHeatmap, getAirportCongestion,
} from '@kquika-inc/s-system';

const heat = await getAirportHeatmap({ path: { airport_code: 'JFK' } });
const h = heat.data!.data!;

console.log(h.data_source);             // measured, or modelled
for (const p of h.points!) {
  console.log(p.zone, p.intensity, p.wait_time_minutes);
}

avg_wait_minutes covers queueing zones only: security, check-in, immigration and customs. Gates and lounges are out of scope.

Points come from the sensor or survey readings an airport shares, and are modeled where it shares none; lidar_available keeps its name for compatibility and is true when readings are available. Check data_source on the heatmap response before acting on occupancy or wait times. measured means a sensor, gate read or throughput count is behind the figure. modelled means it is derived from terminal layout and time of day with no sensor behind it, in which case two calls seconds apart can return different values with no underlying event. Do not diff them to infer movement.

Heatmap and congestion require Professional. Overview is Standard.

Flight metrics and route analytics

import { getFlightMetrics, getRouteAnalytics } from '@kquika-inc/s-system';

const m = await getFlightMetrics();
const d = m.data!.data!;
console.log(d.on_time, 'of', d.measured_flights, 'measured');
console.log('of', d.total_flights, 'scheduled');

Two denominators are returned. on_time_percentage divides by measured_flights. Dividing by total_flights yourself treats an unreported flight as on time.

gate_conflicts is null when no flight carried both a gate and a scheduled time, which means the check could not run. Null and 0 carry different meanings here.

Operations

The disruption lists, rotations, passengers, crew, fuel and stations your operations team works from.

import { getDisruptions, getRotation } from '@kquika-inc/s-system';

const risk = await getDisruptions({ query: { kind: 'daily' } });
for (const flight of risk.data!.data!.items as any[]) {
  console.log(flight.flight_number, flight.probability, flight.action);
}

const day = await getRotation({ query: { tail: 'N123XX', seed: 45 } });   // a 45 minute what-if

Each needs the capability shown in What you can call and a key carrying its permission. Dates are YYYY-MM-DD and default to today; times are UTC.

Errors

| Code | Meaning | |---|---| | unauthorized | No valid key. Check X-API-Key. | | forbidden | The key lacks the permission for this endpoint. | | plan_required | Your plan does not cover this endpoint. | | rate_limited | Back off for retry_after_seconds. | | not_found | No such flight or station among yours. | | bad_request | A parameter is missing or malformed; message says which. | | server_error | Ours to fix. Retry once, then contact support. |

error is a stable code and safe to branch on. message is for a human and its wording may change.

plan_required is a billing matter: route analytics and refresh need Professional, as do heatmap and congestion.

On 429, wait for retry_after_seconds before the next call. Rejected requests count toward the limit.

Types

Every schema is exported.

import type {
  Flight,
  MetricsResponse,
  HeatmapResponse,
  ErrorResponse,
} from '@kquika-inc/s-system';

function isActionable(flight: Flight): boolean {
  // delay_minutes must be null-checked first. `?? 0` here would treat an
  // unreported flight as departing exactly on schedule.
  return flight.delay_minutes !== null && flight.delay_minutes > 15;
}

Disruption lists are on the Operations endpoints. Passenger-rights exposure is delivered through the application and through scheduled data delivery; talk to your account manager about direct access.

Support

An API key, a plan change, or a capability you need that your plan does not carry: www.s-system.cloud

S-System is built by Kquika, Inc.