@mattywhite/skyscanner-api 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 @irrisolto (original Python version)
+Copyright (c) 2025 Node.js port contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,407 @@
+# SkyScanner API Client (Node.js)
+
+A Node.js library for querying the reverse-engineered SkyScanner Android app API for flights, airports, locations, and car rentals, with built-in retries and error handling.
+
+> **Note**: This is a Node.js port of the original Python library. Original credit goes to @irrisolto.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Class Reference](#class-reference)
+- [Methods](#methods)
+- [Types and Enums](#types-and-enums)
+- [Error Handling](#error-handling)
+- [Examples](#examples)
+
+## Installation
+
+```bash
+npm install skyscanner-api
+```
+
+Or if you're installing from source:
+
+```bash
+npm install
+```
+
+## Quick Start
+
+```javascript
+const { SkyScanner, CabinClass, SpecialTypes } = require('skyscanner-api');
+
+async function main() {
+    // Initialize the client
+    const scanner = new SkyScanner({
+        locale: "en-US",
+        currency: "USD",
+        market: "US"
+    });
+
+    // Search for airports
+    const airports = await scanner.searchAirports("London");
+    const origin = airports[0];
+
+    const destinationAirports = await scanner.searchAirports("New York");
+    const destination = destinationAirports[0];
+
+    // Search for flights
+    const departDate = new Date('2025-08-15');
+    const returnDate = new Date('2025-08-22');
+
+    const response = await scanner.getFlightPrices({
+        origin: origin,
+        destination: destination,
+        departDate: departDate,
+        returnDate: returnDate,
+        cabinClass: CabinClass.ECONOMY,
+        adults: 2
+    });
+
+    console.log(response.json);
+}
+
+main().catch(console.error);
+```
+
+## Class Reference
+
+### SkyScanner
+
+The main client class for interacting with Skyscanner APIs.
+
+#### Constructor
+
+```javascript
+const scanner = new SkyScanner({
+    locale: "en-US",       // Locale code for results
+    currency: "USD",       // Currency code for pricing
+    market: "US",          // Market region code
+    retryDelay: 2,         // Seconds to wait between polling retries
+    maxRetries: 15,        // Maximum number of polling retries
+    proxy: "",             // Proxy URL for HTTP requests
+    pxAuthorization: null, // Optional pre-generated PX authorization token
+    verify: true           // Whether to verify SSL certificates
+});
+```
+
+**Parameters:**
+- `locale` (string): Locale code for results (e.g., "en-US", "fr-FR")
+- `currency` (string): Currency code for pricing (e.g., "USD", "EUR", "GBP")
+- `market` (string): Market region code (e.g., "US", "UK", "DE")
+- `retryDelay` (number): Seconds to wait between polling retries
+- `maxRetries` (number): Maximum number of polling retries before giving up
+- `proxy` (string): Proxy URL configuration for HTTP requests
+- `pxAuthorization` (string | null): Optional pre-generated PX authorization token
+- `verify` (boolean): Whether to verify SSL certificates
+
+## Methods
+
+### getFlightPrices()
+
+Search for flight prices between two locations.
+
+```javascript
+await scanner.getFlightPrices({
+    origin,              // Airport object
+    destination,         // Airport | SpecialTypes
+    departDate,          // Date | SpecialTypes | null
+    returnDate,          // Date | SpecialTypes | null
+    cabinClass,          // CabinClass (default: ECONOMY)
+    adults,              // number (default: 1)
+    childAges            // number[] (default: [])
+});
+```
+
+**Parameters:**
+- `origin` (Airport): Origin airport object
+- `destination` (Airport | SpecialTypes): Destination airport or special search type (e.g., SpecialTypes.EVERYWHERE)
+- `departDate` (Date | SpecialTypes | null): Departure date or SpecialTypes.ANYTIME
+- `returnDate` (Date | SpecialTypes | null): Return date (optional for one-way trips)
+- `cabinClass` (string): Cabin class preference (from CabinClass enum)
+- `adults` (number): Number of adult passengers (1-8)
+- `childAges` (number[]): Ages of child passengers (0-17 years, max 8 children)
+
+**Returns:** `SkyscannerResponse` object containing flight options and pricing data
+
+**Throws:**
+- `Error`: Invalid dates, passenger counts, or search parameters
+- `BannedWithCaptcha`: When blocked by Skyscanner's anti-bot measures
+- `AttemptsExhaustedIncompleteResponse`: When max retries exceeded
+
+### searchAirports()
+
+Auto-suggest airports based on a search query.
+
+```javascript
+await scanner.searchAirports(query, departDate, returnDate);
+```
+
+**Parameters:**
+- `query` (string): Search text (airport name, city, or IATA code)
+- `departDate` (Date | null): Optional departure date for context
+- `returnDate` (Date | null): Optional return date for context
+
+**Returns:** Array of `Airport` objects matching the query
+
+### searchLocations()
+
+Auto-suggest locations for car rentals and other services.
+
+```javascript
+await scanner.searchLocations(query);
+```
+
+**Parameters:**
+- `query` (string): Location search text
+
+**Returns:** Array of `Location` objects
+
+### getAirportByCode()
+
+Retrieve a specific airport by its IATA code.
+
+```javascript
+await scanner.getAirportByCode(airportCode);
+```
+
+**Parameters:**
+- `airportCode` (string): Three-letter IATA airport code (e.g., "JFK", "LHR")
+
+**Returns:** `Airport` object for the specified code
+
+**Throws:**
+- `GenericError`: If airport code not found
+
+### getItineraryDetails()
+
+Get detailed information for a specific flight itinerary.
+
+```javascript
+await scanner.getItineraryDetails(itineraryId, response);
+```
+
+**Parameters:**
+- `itineraryId` (string): Unique itinerary identifier from search results
+- `response` (SkyscannerResponse): Original search response containing session data
+
+**Returns:** Object with detailed itinerary information including flight legs and preferences
+
+### getCarRental()
+
+Search for car rental options between locations and times.
+
+```javascript
+await scanner.getCarRental({
+    origin,           // Location | Coordinates | Airport
+    departTime,       // Date
+    returnTime,       // Date
+    destination,      // Location | Coordinates | Airport | null
+    isDriverOver25    // boolean (default: true)
+});
+```
+
+**Parameters:**
+- `origin` (Location | Coordinates | Airport): Pickup location
+- `departTime` (Date): Pickup date and time
+- `returnTime` (Date): Drop-off date and time  
+- `destination` (Location | Coordinates | Airport | null): Drop-off location (defaults to origin)
+- `isDriverOver25` (boolean): Driver age flag affecting pricing
+
+**Returns:** Object containing car rental options and pricing
+
+### getCarRentalFromUrl()
+
+Parse a Skyscanner car rental URL and fetch rental options.
+
+```javascript
+await scanner.getCarRentalFromUrl(url);
+```
+
+**Parameters:**
+- `url` (string): Skyscanner car hire URL
+
+**Returns:** Car rental search results
+
+**Example URL format:**
+```
+https://www.skyscanner.net/g/carhire-quotes/GB/en-GB/GBP/30/27544008/27544008/2025-07-01T10:00/2025-08-01T10:00/
+```
+
+## Types and Enums
+
+### Airport
+```javascript
+const airport = new Airport(
+    "London Heathrow",  // title
+    "27544008",         // entityId
+    "LHR"               // skyId (IATA code)
+);
+```
+
+### Location
+```javascript
+const location = new Location(
+    "London",           // entityName
+    "27544008",         // entityId
+    "51.5074,-0.1278"   // coordinates (lat,lng)
+);
+```
+
+### CabinClass
+- `CabinClass.ECONOMY`
+- `CabinClass.PREMIUM_ECONOMY`  
+- `CabinClass.BUSINESS`
+- `CabinClass.FIRST`
+
+### SpecialTypes
+- `SpecialTypes.ANYTIME` - Flexible date search
+- `SpecialTypes.EVERYWHERE` - Open destination search
+
+## Error Handling
+
+The library defines several custom exceptions:
+
+### BannedWithCaptcha
+Raised when Skyscanner blocks requests with CAPTCHA challenges.
+
+```javascript
+try {
+    const response = await scanner.getFlightPrices({...});
+} catch (error) {
+    if (error instanceof BannedWithCaptcha) {
+        console.log(`Blocked by anti-bot measures: ${error.captchaUrl}`);
+        // Consider using proxies or reducing request frequency
+    }
+}
+```
+
+### AttemptsExhaustedIncompleteResponse
+Raised when polling retries are exhausted without getting complete results.
+
+```javascript
+try {
+    const response = await scanner.getFlightPrices({...});
+} catch (error) {
+    if (error instanceof AttemptsExhaustedIncompleteResponse) {
+        console.log("Search timed out - try again later");
+    }
+}
+```
+
+### GenericError
+General API errors with status codes and response details.
+
+## Examples
+
+### Basic Flight Search
+
+```javascript
+const { SkyScanner } = require('skyscanner-api');
+
+async function searchFlights() {
+    const scanner = new SkyScanner();
+
+    // Find airports
+    const londonAirports = await scanner.searchAirports("London");
+    const heathrow = londonAirports[0];
+
+    const nycAirports = await scanner.searchAirports("New York");
+    const jfk = nycAirports[0];
+
+    // Search flights
+    const response = await scanner.getFlightPrices({
+        origin: heathrow,
+        destination: jfk,
+        departDate: new Date('2025-09-01'),
+        returnDate: new Date('2025-09-08'),
+        adults: 1
+    });
+
+    console.log(response.json);
+}
+
+searchFlights().catch(console.error);
+```
+
+### Flexible Search (Anywhere, Anytime)
+
+```javascript
+const { SkyScanner, SpecialTypes } = require('skyscanner-api');
+
+async function flexibleSearch() {
+    const scanner = new SkyScanner();
+    const londonAirports = await scanner.searchAirports("London");
+    const heathrow = londonAirports[0];
+
+    // Search from London to anywhere
+    const response = await scanner.getFlightPrices({
+        origin: heathrow,
+        destination: SpecialTypes.EVERYWHERE,
+        departDate: SpecialTypes.ANYTIME
+    });
+
+    console.log(response.json);
+}
+
+flexibleSearch().catch(console.error);
+```
+
+### Car Rental Search
+
+```javascript
+const { SkyScanner } = require('skyscanner-api');
+
+async function searchCarRentals() {
+    const scanner = new SkyScanner();
+
+    // Search locations
+    const locations = await scanner.searchLocations("London");
+    const pickupLocation = locations[0];
+
+    // Set dates
+    const pickupDate = new Date('2025-07-01');
+    pickupDate.setHours(10, 0);
+    
+    const returnDate = new Date('2025-07-08');
+    returnDate.setHours(10, 0);
+
+    // Search car rentals
+    const rentals = await scanner.getCarRental({
+        origin: pickupLocation,
+        departTime: pickupDate,
+        returnTime: returnDate,
+        isDriverOver25: true
+    });
+
+    console.log(rentals);
+}
+
+searchCarRentals().catch(console.error);
+```
+
+## Rate Limiting and Best Practices
+
+1. **Use Proxies**: Consider proxy rotation for high-volume usage  
+2. **Cache Results**: Store airport/location searches to reduce API calls
+3. **Validate Inputs**: Check dates and passenger counts before API calls
+4. **Reuse PX Authorization**: X-Px-Authorization header isn't single use. Once you've made one you can use it for multiple requests, but once you get captcha you need to switch IP and authorization
+
+## Dependencies
+
+- `axios`: HTTP client for making API requests
+- `https-proxy-agent`: Proxy support for HTTPS requests
+
+## License
+
+MIT
+
+## Credits
+
+Original Python library by @irrisolto on Discord.
+Node.js port created for broader accessibility.
+
+## Disclaimer
+
+This library uses reverse-engineered Skyscanner Android app endpoints. Use at your own risk. The library is not affiliated with, endorsed by, or sponsored by Skyscanner.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mattywhite/skyscanner-api",
+  "version": "1.0.0",
+  "description": "A Node.js library for querying the reverse-engineered SkyScanner Android app API for flights, airports, locations, and car rentals, with built-in retries and error handling",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "node examples/flight_prices.js"
+  },
+  "keywords": [
+    "skyscanner",
+    "flight",
+    "api",
+    "travel",
+    "booking",
+    "car-rental",
+    "airport",
+    "flights"
+  ],
+  "author": "@irrisolto (ported to Node.js)",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "https-proxy-agent": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/irrisolto/skyscanner"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,41 @@
+const path = require('path');
+
+// TLS fingerprint
+const JA3 = '771,4865-4866-4867-49195-49196-52393-49199-49200-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-51-45-43-21,29-23-24,0';
+
+const AKAMAI = "4:16777216|16711681|0|m,p,a,s";
+
+const EXTRA_FP = {
+    tls_signature_algorithms: [
+        "ecdsa_secp256r1_sha256",
+        "rsa_pss_rsae_sha256",
+        "rsa_pkcs1_sha256",
+        "ecdsa_secp384r1_sha384",
+        "rsa_pss_rsae_sha384",
+        "rsa_pkcs1_sha384",
+        "rsa_pss_rsae_sha512",
+        "rsa_pkcs1_sha512",
+        "rsa_pkcs1_sha1"
+    ]
+};
+
+// Endpoints
+const UNIFIED_SEARCH_ENDPOINT = "https://www.skyscanner.net/g/radar/api/v2/unified-search/";
+const SEARCH_ORIGIN_ENDPOINT = "https://www.skyscanner.net/g/fenryr/v1/inputorigin";
+const ITINERARY_DETAILS_ENDPOINT = 'https://www.skyscanner.net/g/sonar/v3/itinerary/details';
+const LOCATION_SEARCH_ENDPOINT = 'https://www.skyscanner.net/g/autosuggest-search/api/v1/search-car/{market}/{locale}/';
+const CAR_RENTAL_ENDPOINT = 'https://www.skyscanner.net/g/carhire-quotes/{market}/{locale}/{currency}/{driver_age}/{first_location}/{second_location}/{first_date}/{second_date}';
+
+const PX_DEVICE_DATA_PATH = path.join(__dirname, 'devicedata.json');
+
+module.exports = {
+    JA3,
+    AKAMAI,
+    EXTRA_FP,
+    UNIFIED_SEARCH_ENDPOINT,
+    SEARCH_ORIGIN_ENDPOINT,
+    ITINERARY_DETAILS_ENDPOINT,
+    LOCATION_SEARCH_ENDPOINT,
+    CAR_RENTAL_ENDPOINT,
+    PX_DEVICE_DATA_PATH
+};

package/src/devicedata.json

@@ -0,0 +1,123 @@
+[
+    {
+        "height": 2400,
+        "width": 1080,
+        "pixel_density": 428,
+        "model": "Pixel 8",
+        "brand": "google",
+        "build_device": "shiba",
+        "os_version": "15-AP1A.240505.005",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 3120,
+        "width": 1440,
+        "pixel_density": 501,
+        "model": "SM-S928B",
+        "brand": "samsung",
+        "build_device": "gts8uq",
+        "os_version": "15-UP1A.231005.007.S928BXXU1AXCB",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 3168,
+        "width": 1440,
+        "pixel_density": 510,
+        "model": "CPH2573",
+        "brand": "oneplus",
+        "build_device": "pandan",
+        "os_version": "15-UKQ1.230804.001",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2412,
+        "width": 1080,
+        "pixel_density": 394,
+        "model": "A065",
+        "brand": "nothing",
+        "build_device": "spacewar",
+        "os_version": "15-TKQ1.221013.002",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2488,
+        "width": 1116,
+        "pixel_density": 395,
+        "model": "AI2401_A",
+        "brand": "asus",
+        "build_device": "AI2401",
+        "os_version": "15-UP1A.231005.007.33.0820.0820.172",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2780,
+        "width": 1264,
+        "pixel_density": 450,
+        "model": "RMX3851",
+        "brand": "realme",
+        "build_device": "mandrill",
+        "os_version": "15-UP1A.231005.007",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2400,
+        "width": 1080,
+        "pixel_density": 402,
+        "model": "XT2307-1",
+        "brand": "motorola",
+        "build_device": "manaus",
+        "os_version": "15-UP1A.231005.007",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2712,
+        "width": 1220,
+        "pixel_density": 446,
+        "model": "2306EPN60G",
+        "brand": "xiaomi",
+        "build_device": "aristotle",
+        "os_version": "15-UP1A.231005.007",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2664,
+        "width": 1200,
+        "pixel_density": 435,
+        "model": "REA-NX9",
+        "brand": "honor",
+        "build_device": "reehan",
+        "os_version": "15-UP1A.231005.007",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 2412,
+        "width": 1080,
+        "pixel_density": 394,
+        "model": "CPH2521",
+        "brand": "oppo",
+        "build_device": "PHU110",
+        "os_version": "15-UP1A.231005.007",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    },
+    {
+        "height": 3200,
+        "width": 1440,
+        "pixel_density": 515,
+        "model": "Pixel 8 Pro",
+        "brand": "google",
+        "build_device": "husky",
+        "os_version": "15-UP1A.231005.007.100345",
+        "cpu_cores": 8,
+        "sdk_int": 35
+    }    
+]

package/src/errors.js

@@ -0,0 +1,36 @@
+class AttemptsExhaustedIncompleteResponse extends Error {
+    constructor(message = "All attempts exhausted and response is still incomplete.") {
+        super(message);
+        this.name = "AttemptsExhaustedIncompleteResponse";
+    }
+}
+
+class BannedWithCaptcha extends Error {
+    constructor(captchaUrl, message = null) {
+        const msg = message || `Access banned. CAPTCHA challenge encountered: ${captchaUrl}`;
+        super(msg);
+        this.name = "BannedWithCaptcha";
+        this.captchaUrl = captchaUrl;
+    }
+}
+
+class PerimeterXError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PerimeterXError";
+    }
+}
+
+class GenericError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GenericError";
+    }
+}
+
+module.exports = {
+    AttemptsExhaustedIncompleteResponse,
+    BannedWithCaptcha,
+    PerimeterXError,
+    GenericError
+};

package/src/index.js

@@ -0,0 +1,20 @@
+const SkyScanner = require('./skyscanner');
+const { Location, Airport, SkyscannerResponse, Coordinates, CabinClass, SpecialTypes } = require('./types');
+const { AttemptsExhaustedIncompleteResponse, BannedWithCaptcha, PerimeterXError, GenericError } = require('./errors');
+
+module.exports = {
+    SkyScanner,
+    Location,
+    Airport,
+    SkyscannerResponse,
+    Coordinates,
+    CabinClass,
+    SpecialTypes,
+    AttemptsExhaustedIncompleteResponse,
+    BannedWithCaptcha,
+    PerimeterXError,
+    GenericError
+};
+
+// Default export
+module.exports.default = SkyScanner;