Ryanair SDK

Inspired by the punchy docs of 2bad — this package wraps Ryanair's public endpoints with sane defaults, blazing-fast validation, and test-friendly ergonomics.

Fork notice: This repository is a maintained fork of 2BAD/ryanair with rewritten JavaScript output, expanded testing, and additional documentation.

Highlights

• Typed by design via Zod schemas without TypeScript runtime overhead.
• Drop-in HTTP client powered by got with smart, globally queued debouncing.
• Rich helpers for airports, fares, flights, routing, and geo math.
• Ready for prod: dual CJS/ESM bundles, full test coverage, MIT licensed.

Installation

npm install @f3rr1gn0/ryanair-sdk
# or
pnpm add @f3rr1gn0/ryanair-sdk

The package ships compiled artifacts under dist/; no build step is required after installation.

Quick start

ES module

import { airports, fares, flights } from '@f3rr1gn0/ryanair-sdk';

const run = async () => {
  const active = await airports.getActive();
  const cheapest = await fares.findCheapestRoundTrip('DUB', 'KRK', '2024-05-01', '2024-05-31');
  const availability = await flights.getAvailable({ Origin: 'DUB', Destination: 'KRK' });

  console.log(active.length, cheapest[0], availability.trips[0].dates[0].flights.length);
  // Example output: 253 { departure: {...}, return: {...}, price: 45 } 6
};

run();

CommonJS

const { airports, fares, flights } = require('@f3rr1gn0/ryanair-sdk');

async function run() {
  const active = await airports.getActive();
  const cheapest = await fares.findCheapestRoundTrip('DUB', 'KRK', '2024-05-01', '2024-05-31');
  const availability = await flights.getAvailable({ Origin: 'DUB', Destination: 'KRK' });

  console.log(active.length, cheapest[0], availability.trips[0].dates[0].flights.length);
  // Example output: 253 { departure: {...}, return: {...}, price: 45 } 6
}

run();

Custom HTTP client

ES module override

import { setHttpClient, resetHttpClient } from '@f3rr1gn0/ryanair-sdk/client';
import got from 'got';

setHttpClient(
  got.extend({
    hooks: {
      beforeRequest: [({ url }) => console.info('->', url.toString())],
    },
  }),
);

// ... make SDK calls here

resetHttpClient();

CommonJS override

const { setHttpClient, resetHttpClient } = require('@f3rr1gn0/ryanair-sdk/client');
const got = require('got');

setHttpClient(
  got.extend({
    hooks: {
      beforeRequest: [({ url }) => console.info('->', url.toString())],
    },
  }),
);

// ... make SDK calls here

resetHttpClient();

Modules at a glance

• airports: active airports, geo search, route discovery, schedules, and Zod schemas.
• fares: fare calendars, round-trip combinatorics (via fast-cartesian), and price helpers.
• flights: booking availability + date lookup with strongly validated payloads.
• helpers: dates, coordinates, pricing utilities, and haversine distance calculations.
• client: lazy got factory with global debouncing and injectable overrides.
• endpoints: frozen base URLs for Ryanair public APIs.

Every response is validated on the fly; invalid data throws early with precise error messages.

Testing and coverage

The suite is powered by Vitest (v8 engine coverage). Run it locally:

npm test

Coverage thresholds are enforced at ≥90 percent for statements/lines/functions and ≥85 percent for branches. HTML and JSON summaries are emitted in coverage/.

Want to iterate? npm run test:watch keeps the feedback loop tight.

Build and publish

npm run build   # bundles to dist/index.{js,cjs}
npm pack        # optional: preview the tarball destined for npm

A prepare lifecycle hook rebuilds automatically so the packaged tarball always ships fresh artifacts. Add a remote and push to make it public:

git init
git remote add origin [email protected]:f3rr1gn0/ryanair-sdk.git
npm version patch
npm publish --access public

API Overview

Airports API

• Get active airports list
• Find nearest airports
• Discover available destinations
• View airport details
• Search flight routes

View Airports Documentation →

Fares API

• Find cheapest daily fares
• Compare prices across date ranges
• Discover best round-trip deals
• Search by currency preference

View Fares Documentation →

Flights API

• Check flight availability
• View flight schedules
• Search available dates
• Access flight details

View Flights Documentation →

Understanding IATA Codes

IATA codes are three-letter identifiers used in aviation for airports worldwide. For example:

• DUB - Dublin Airport
• BER - Berlin Brandenburg Airport
• STN - London Stansted Airport

Find the complete list on IATA's official website.

Disclaimer

This is an unofficial package and is not affiliated with Ryanair. Usage is subject to Ryanair's API terms and conditions.

Contributing

Contributions are welcome. Here's how you can help:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Please ensure your code passes all tests and follows our coding standards.

License

MIT © f3rr1gn0

Need help? Open an issue or check our Postman collection.