npm package: @sharpapi/sharpapi-node-airports
Description: SharpAPI.com Node.js SDK for Airports Database & Flight Duration Calculator
Author: Dawid Makowski
Latest version: 1.0.3

![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Node.js Client")

# Airports Database & Flight Duration API for Node.js

## ✈️ Access 30k+ airports and calculate flight durations — powered by SharpAPI.

[![npm version](https://img.shields.io/npm/v/@sharpapi/sharpapi-node-airports.svg)](https://www.npmjs.com/package/@sharpapi/sharpapi-node-airports)
[![License](https://img.shields.io/npm/l/@sharpapi/sharpapi-node-airports.svg)](https://github.com/sharpapi/sharpapi-node-client/blob/master/LICENSE.md)

**SharpAPI Airports Database** provides access to nearly 30,000 airports worldwide with detailed information including ICAO, IATA, LID codes, and geographical data. Also calculates precise flight durations between airports.

---

## 📋 Table of Contents

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Usage](#usage)
4. [API Documentation](#api-documentation)
5. [Examples](#examples)
6. [Use Cases](#use-cases)
7. [API Endpoints](#api-endpoints)
8. [Related Packages](#related-packages)
9. [License](#license)

---

## Requirements

- Node.js >= 16.x
- npm or yarn

---

## Installation

### Step 1. Install the package via npm:

\`\`\`bash
npm install @sharpapi/sharpapi-node-airports
\`\`\`

### Step 2. Get your API key

Visit [SharpAPI.com](https://sharpapi.com/) to get your API key.

---

## Usage

\`\`\`javascript
const { SharpApiAirportsService } = require('@sharpapi/sharpapi-node-airports');

const apiKey = process.env.SHARP_API_KEY; // Store your API key in environment variables
const service = new SharpApiAirportsService(apiKey);

async function searchAirports() {
  try {
    // Get airports in a specific country
    const airports = await service.getAirports({
      country: 'US',
      iata_assigned: true,
      per_page: 10
    });

    console.log('Found airports:', airports.data);
    console.log('Total:', airports.meta.total);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

searchAirports();
\`\`\`

---

## API Documentation

All endpoints are **synchronous** and return data immediately (no polling required).

### Methods

#### `getAirports(filters)`

Get a paginated list of airports with optional filters.

**Parameters:**
- `filters` (object, optional):
  - `per_page` (number, optional): Results per page (max 100, default 25)
  - `iata_assigned` (boolean, optional): Filter for airports with IATA codes
  - `icao_assigned` (boolean, optional): Filter for airports with ICAO codes
  - `lid_assigned` (boolean, optional): Filter for airports with LID codes
  - `country` (string, optional): Filter by 2-letter country code (e.g., 'US')
  - `timezone` (string, optional): Filter by timezone (e.g., 'America/New_York')
  - `name` (string, optional): Filter by airport name (partial match)
  - `city` (string, optional): Filter by city name (partial match)

**Returns:** Promise<object> - Paginated list with data, links, and meta information

**Example:**
\`\`\`javascript
const airports = await service.getAirports({
  country: 'GB',
  iata_assigned: true,
  per_page: 50
});
\`\`\`

#### `getAirportByUuid(uuid)`

Get detailed airport information by UUID.

**Parameters:**
- `uuid` (string, required): Airport UUID

**Returns:** Promise<object> - Airport details

**Example:**
\`\`\`javascript
const airport = await service.getAirportByUuid('1ef266de-5a6c-67d6-86a1-06bb2780ed98');
\`\`\`

#### `getAirportByIata(iataCode)`

Get airport information by IATA code.

**Parameters:**
- `iataCode` (string, required): IATA airport code (e.g., 'LAX', 'JFK', 'LHR')

**Returns:** Promise<object> - Airport details

**Example:**
\`\`\`javascript
const airport = await service.getAirportByIata('LAX');
console.log(airport.name); // "Los Angeles International Airport"
\`\`\`

#### `getAirportByIcao(icaoCode)`

Get airport information by ICAO code.

**Parameters:**
- `icaoCode` (string, required): ICAO airport code (e.g., 'KLAX', 'KJFK', 'EGLL')

**Returns:** Promise<object> - Airport details

**Example:**
\`\`\`javascript
const airport = await service.getAirportByIcao('KLAX');
\`\`\`

#### `getAirportByLid(lidCode)`

Get airport information by LID code.

**Parameters:**
- `lidCode` (string, required): LID airport code

**Returns:** Promise<object> - Airport details

**Example:**
\`\`\`javascript
const airport = await service.getAirportByLid('00AA');
\`\`\`

#### `calculateFlightDuration(...)`

Calculate flight duration between two airports.

**Parameters:**
- `departureCodeType` (string, required): 'iata', 'icao', or 'lid'
- `departureCode` (string, required): Departure airport code
- `departureDate` (string, required): Departure date in YYYY-MM-DD format
- `departureTime` (string, required): Departure time in HH:MM format (24-hour)
- `arrivalCodeType` (string, required): 'iata', 'icao', or 'lid'
- `arrivalCode` (string, required): Arrival airport code
- `arrivalDate` (string, required): Arrival date in YYYY-MM-DD format
- `arrivalTime` (string, required): Arrival time in HH:MM format (24-hour)

**Returns:** Promise<object> - Flight duration with detailed breakdown

**Example:**
\`\`\`javascript
const duration = await service.calculateFlightDuration(
  'iata', 'LAX', '2026-02-15', '08:00',
  'iata', 'JFK', '2026-02-15', '16:30'
);
console.log(duration.total_duration); // Total flight time
console.log(duration.duration_breakdown); // Hours, minutes breakdown
\`\`\`

---

## Examples

### Search Airports by Country

\`\`\`javascript
const { SharpApiAirportsService } = require('@sharpapi/sharpapi-node-airports');

const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);

async function getUSAirports() {
  const result = await service.getAirports({
    country: 'US',
    iata_assigned: true,
    per_page: 100
  });

  console.log(\`Found \${result.meta.total} US airports with IATA codes\`);

  result.data.forEach(airport => {
    console.log(\`\${airport.iata} - \${airport.name} (\${airport.city})\`);
  });
}

getUSAirports();
\`\`\`

### Get Specific Airport Details

\`\`\`javascript
const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);

async function getAirportDetails() {
  const lax = await service.getAirportByIata('LAX');

  console.log('Airport:', lax.name);
  console.log('City:', lax.city);
  console.log('Country:', lax.country);
  console.log('Timezone:', lax.timezone);
  console.log('Elevation:', lax.elevation, 'ft');
  console.log('Coordinates:', lax.latitude, lax.longitude);
  console.log('Codes: IATA:', lax.iata, 'ICAO:', lax.icao);
}

getAirportDetails();
\`\`\`

### Calculate Flight Duration

\`\`\`javascript
const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);

async function calculateFlight() {
  // Flight from Los Angeles to New York
  const duration = await service.calculateFlightDuration(
    'iata', 'LAX',
    '2026-02-15', '08:00',
    'iata', 'JFK',
    '2026-02-15', '16:30'
  );

  console.log('Flight Duration:', duration.human_readable);
  console.log('Hours:', duration.duration_breakdown.hours);
  console.log('Minutes:', duration.duration_breakdown.minutes);
  console.log('Departure:', duration.departure_airport.name);
  console.log('Arrival:', duration.arrival_airport.name);
}

calculateFlight();
\`\`\`

### Paginate Through Results

\`\`\`javascript
const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);

async function browseAirports() {
  let currentPage = 1;
  let hasMore = true;

  while (hasMore && currentPage <= 5) {
    const result = await service.getAirports({
      per_page: 25,
      page: currentPage
    });

    console.log(\`Page \${currentPage}:\`);
    result.data.forEach(airport => {
      console.log(\`  - \${airport.name}\`);
    });

    hasMore = result.links.next !== null;
    currentPage++;
  }
}

browseAirports();
\`\`\`

---

## Use Cases

- **Travel Booking**: Display airport information in booking systems
- **Flight Search**: Enable airport code lookups and autocomplete
- **Trip Planning**: Calculate flight times for itinerary planning
- **Mobile Apps**: Integrate airport data into travel applications
- **Route Planning**: Determine travel times for multi-leg journeys
- **Logistics**: Calculate shipping times via air freight

---

## API Endpoints

All endpoints are **synchronous** (return 200 OK immediately):

- **GET** `/airports` - List airports with filters
- **GET** `/airports/{uuid}` - Get airport by UUID
- **GET** `/airports/iata/{iata}` - Get airport by IATA code
- **GET** `/airports/icao/{icao}` - Get airport by ICAO code
- **GET** `/airports/lid/{lid}` - Get airport by LID code
- **GET** `/airports/flight_duration/{departureCodeType}/{departureCode}/{departureDate}/{departureTime}/{arrivalCodeType}/{arrivalCode}/{arrivalDate}/{arrivalTime}` - Calculate flight duration

For detailed API specifications, refer to:
- [Postman Documentation](https://documenter.getpostman.com/view/31106842/2sBXVeGsVj)
- [Product Page](https://sharpapi.com/en/catalog/utility/airports-database-flight-duration-calculator)

---

## Response Format

### Airport Object

\`\`\`json
{
  "id": "1ef266de-5a6c-67d6-86a1-06bb2780ed98",
  "icao": "00AA",
  "iata": "",
  "lid": "00AA",
  "name": "Aero B Ranch Airport",
  "city": "Leoti",
  "subdivision": "Kansas",
  "country": "US",
  "timezone": "America/Chicago",
  "elevation": 3435,
  "latitude": 38.7,
  "longitude": -101.47
}
\`\`\`

### Paginated Response

\`\`\`json
{
  "data": [ /* array of airport objects */ ],
  "links": {
    "first": "https://sharpapi.com/api/v1/airports?page=1",
    "last": "https://sharpapi.com/api/v1/airports?page=1128",
    "prev": null,
    "next": "https://sharpapi.com/api/v1/airports?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1128,
    "per_page": 25,
    "to": 25,
    "total": 28186
  }
}
\`\`\`

---

## Related Packages

- [@sharpapi/sharpapi-node-travel-review-sentiment](https://www.npmjs.com/package/@sharpapi/sharpapi-node-travel-review-sentiment)
- [@sharpapi/sharpapi-node-web-scraping](https://www.npmjs.com/package/@sharpapi/sharpapi-node-web-scraping)
- [@sharpapi/sharpapi-node-client](https://www.npmjs.com/package/@sharpapi/sharpapi-node-client) - Full SharpAPI SDK

---

## License

This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.

---

## Support

- **Documentation**: [SharpAPI.com Documentation](https://sharpapi.com/documentation)
- **Issues**: [GitHub Issues](https://github.com/sharpapi/sharpapi-node-client/issues)
- **Email**: contact@sharpapi.com

---

**Powered by [SharpAPI](https://sharpapi.com/) - AI-Powered API Workflow Automation**