@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. |

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.

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 | | LiDAR heatmap: passenger density by zone | Professional | | Congestion: current level plus 1h and 3h forecast | Professional |

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

Plans

Your rate limit follows your plan. Read it from the response headers instead of hardcoding it.

| Plan | Rate limit | Burst | |---|---|---| | Standard | 100 requests/minute | 200/minute | | Professional | 500 requests/minute | 1,000/minute | | Enterprise | 2,000 requests/minute | 5,000/minute |

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: 'SDQ', 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) {
  if (flight.data_confidence === 'live_feed') schedule(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.

TypeScript narrows that 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: 'SDQ' } });

if (!heat.data?.data?.lidar_available) {
  // This station has no LiDAR coverage, so points is empty.
  console.log('No LiDAR here.');
} else {
  for (const p of heat.data.data.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.

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.

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. |

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,
  DisruptionPrediction,
  Exposure,
  Meta,
} from '@kquika-inc/s-system';

function isActionable(p: DisruptionPrediction): boolean {
  return p.risk_level === 'critical' || p.risk_level === 'elevated';
}

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.