IATA Flight Number Validation in Node.js — Airline Lookup & Parsing

1. What is an IATA flight number?

An IATA flight number (also called a flight designator) is a code assigned to a scheduled airline service. It consists of a 2-character airline code followed by a 1- to 4-digit number and an optional single-letter suffix. These identifiers appear on boarding passes, airport departure boards, flight-tracking apps, and GDS booking systems.

Some well-known examples: AA100 (American Airlines), LH438 (Lufthansa), BA15 (British Airways), EK1 (Emirates).

2. Structure breakdown

An IATA flight number has three parts. Understanding this structure helps when parsing user input, validating API payloads, or building flight search interfaces.

Combined, a flight number like LH438B breaks down as: airline code LH (Lufthansa), flight number 438, suffix B.

3. Why flight number validation matters

4. The right solution: one API call

The IsValid IATA Flight API validates the flight number format, parses it into its component parts, and enriches it with airline metadata — airline name, country, ICAO callsign, and more — all from a single GET request.

Get your free API key at isvalid.dev — 100 calls per day, no credit card required.

Full parameter reference and response schema: IATA Flight Validation API docs →

5. Node.js code example

Using the @isvalid-dev/sdk package or the native fetch API (Node 18+).

// flightValidator.js
import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Example usage ────────────────────────────────────────────────────────────

const result = await iv.iata.flight('AA100');

console.log(result.valid);        // true
console.log(result.airlineCode);  // 'AA'
console.log(result.flightNumber); // 100
console.log(result.airlineName);  // 'American Airlines'
console.log(result.suffix);       // null

if (result.valid) {
  console.log(`Flight ${result.airlineCode}${result.flightNumber} — ${result.airlineName}`);
  // → Flight AA100 — American Airlines
}

// flightBatch.js — validate multiple flight numbers sequentially
async function validateFlights(flightList) {
  const results = [];

  for (const flight of flightList) {
    try {
      const data = await validateFlight(flight);
      results.push({ flight, ...data });
    } catch (err) {
      results.push({ flight, valid: false, error: err.message });
    }
  }

  return results;
}

// ── Example ──────────────────────────────────────────────────────────────────

const flights = ['AA100', 'LH438B', 'BA15', 'INVALID', '123'];
const results = await validateFlights(flights);

for (const r of results) {
  const status = r.valid ? '✓' : '✗';
  const airline = r.airlineName ?? 'unknown';
  console.log(`  ${status}  ${r.flight.padEnd(10)}  ${airline}`);
}

6. cURL example

American Airlines flight 100:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/iata/flight?value=AA100"

Lufthansa flight with suffix:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/iata/flight?value=LH438B"

Invalid format:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/iata/flight?value=INVALID"

7. Understanding the response

Response for AA100 (American Airlines):

{
  "valid": true,
  "airlineCode": "AA",
  "flightNumber": 100,
  "suffix": null,
  "airlineName": "American Airlines",
  "countryCode": "US",
  "countryName": "United States",
  "callsign": "AMERICAN",
  "icao": "AAL"
}

Response for an invalid flight number:

{
  "valid": false
}

8. Edge cases to handle

// Both codeshare partners have valid flight numbers
const marketing = await iv.iata.flight('BA1525');
const operating = await iv.iata.flight('AA100');

console.log(marketing.valid);      // true
console.log(marketing.airlineName); // 'British Airways'
console.log(operating.airlineName); // 'American Airlines'

const result = await iv.iata.flight('LH438B');

console.log(result.airlineCode);  // 'LH'
console.log(result.flightNumber); // 438
console.log(result.suffix);       // 'B'
console.log(result.airlineName);  // 'Lufthansa'

const r1 = await iv.iata.flight('AA0100');
const r2 = await iv.iata.flight('AA100');

console.log(r1.flightNumber); // 100
console.log(r2.flightNumber); // 100

const r1 = await iv.iata.flight('aa100');
const r2 = await iv.iata.flight('AA100');

console.log(r1.airlineCode); // 'AA'
console.log(r2.airlineCode); // 'AA'

Node.js integration notes

In a TypeScript project, represent a validated IATA flight number as a branded type so the compiler enforces that only checked values flow through your pipeline: type IataFlightNumber = string & { readonly __brand: 'IataFlightNumber' }. The IsValid SDK ships with complete TypeScript definitions for all response fields, which means your editor provides autocomplete on the parsed result — country codes, category names, registry data — without writing manual type declarations.

IATA flight number validation often appears inside data ingestion pipelines: EDI feeds, supply-chain APIs, catalog imports, or financial data streams. In these contexts, validation happens at the boundary where external data enters your system. Model this as a transformation step: raw string in, validated branded type out. Use Promise.allSettled() to process batches and collect both valid and invalid results — invalid items can be quarantined for manual review without blocking the rest of the batch.

When IATA flight number values arrive from user input or partner systems, normalise them before validation: trim surrounding whitespace, remove optional hyphens or spaces that some sources include for readability, and convert to the canonical case used by the relevant standard. Apply the same normalisation logic consistently across your codebase to prevent cache misses caused by formatting differences rather than value differences.

• Read process.env.ISVALID_API_KEY once at startup and store it in a module-level constant
• Use jest.mock() to stub the IsValid client in unit tests; CI pipelines should never make real API calls
• Log the full validation response at debug level — it often contains fields useful for debugging data quality issues
• For very high throughput, consider a local pre-filter that checks format with a regex before calling the API, reducing calls for obviously malformed inputs

When making HTTP calls to the IsValid API directly (without the SDK), the choice between fetch and axios is largely a matter of preference. The native fetch API is available in Node.js 18+ without any additional dependency and is sufficient for simple request/response flows. axios adds automatic JSON parsing, request/response interceptors, and a cleaner timeout API (axios.create({ timeout: 5000 })), which makes it easier to centralise the Authorization header and retry logic in one place. For high-throughput services that make many concurrent API calls, consider undici — the HTTP client underlying Node.js fetch — used directly for its connection pooling and lower overhead.