@sharpapi/sharpapi-node-airports 1.0.0

package/README.md

@@ -0,0 +1,464 @@
+![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Node.js Client")
+
+# Airports Database & Flight Duration Calculator API for Node.js
+
+## ✈️ Access global airports database 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 comprehensive filtering, search capabilities, and flight duration calculations. Perfect for travel applications, booking systems, and aviation tools.
+
+---
+
+## 📋 Table of Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [API Documentation](#api-documentation)
+5. [Response Format](#response-format)
+6. [Examples](#examples)
+7. [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;
+const service = new SharpApiAirportsService(apiKey);
+
+async function searchAirports() {
+  try {
+    // Search airports by city
+    const airports = await service.getAirports({
+      city: 'New York',
+      per_page: 10,
+      iata_assigned: true
+    });
+
+    console.log(`Found ${airports.data.length} airports:`);
+    airports.data.forEach(airport => {
+      console.log(`${airport.name} (${airport.iata}) - ${airport.city}, ${airport.country}`);
+    });
+
+    // Get specific airport by IATA code
+    const jfk = await service.getAirportByIata('JFK');
+    console.log('\nJFK Airport:', jfk);
+
+    // Calculate flight duration
+    const duration = await service.calculateFlightDuration('JFK', 'LAX');
+    console.log('\nFlight JFK → LAX:', duration);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+searchAirports();
+```
+
+---
+
+## API Documentation
+
+### Methods
+
+#### `getAirports(filters?: object): Promise<object>`
+
+Get paginated list of airports with optional filters.
+
+**Filters:**
+- `per_page` (number): Results per page (max 100, default: 25)
+- `iata_assigned` (boolean): Only airports with IATA codes
+- `icao_assigned` (boolean): Only airports with ICAO codes
+- `lid_assigned` (boolean): Only airports with LID codes
+- `country` (string): Filter by 2-letter country code
+- `timezone` (string): Filter by timezone
+- `name` (string): Filter by airport name (partial match)
+- `city` (string): Filter by city name (partial match)
+
+**Returns:**
+- Paginated list of airports with metadata
+
+#### `getAirportByIata(iataCode: string): Promise<object>`
+
+Get airport information by IATA code.
+
+**Parameters:**
+- `iataCode` (string): Three-letter IATA code (e.g., 'JFK')
+
+#### `getAirportByIcao(icaoCode: string): Promise<object>`
+
+Get airport information by ICAO code.
+
+**Parameters:**
+- `icaoCode` (string): Four-letter ICAO code (e.g., 'KJFK')
+
+#### `getAirportByUuid(uuid: string): Promise<object>`
+
+Get airport information by UUID.
+
+#### `getNearbyAirports(latitude: number, longitude: number, radius?: number, limit?: number): Promise<object>`
+
+Find airports near a location.
+
+**Parameters:**
+- `latitude` (number): Latitude coordinate
+- `longitude` (number): Longitude coordinate
+- `radius` (number, optional): Search radius in kilometers (default: 100)
+- `limit` (number, optional): Maximum results (default: 10)
+
+#### `calculateFlightDuration(fromIata: string, toIata: string): Promise<object>`
+
+Calculate flight duration between two airports.
+
+**Parameters:**
+- `fromIata` (string): Departure airport IATA code
+- `toIata` (string): Arrival airport IATA code
+
+#### `getCountries(): Promise<object>`
+
+Get list of all countries with airports.
+
+#### `getCitiesByCountry(countryCode: string): Promise<object>`
+
+Get cities with airports in a specific country.
+
+---
+
+## Response Format
+
+### Airport List Response
+
+```json
+{
+  "data": [
+    {
+      "id": "1ef266de-5a6c-67d6-86a1-06bb2780ed98",
+      "icao": "KJFK",
+      "iata": "JFK",
+      "lid": "",
+      "name": "John F Kennedy International Airport",
+      "city": "New York",
+      "subdivision": "New York",
+      "country": "US",
+      "timezone": "America/New_York",
+      "elevation": 13,
+      "latitude": 40.6398,
+      "longitude": -73.7789
+    }
+  ],
+  "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
+  }
+}
+```
+
+### Single Airport Response
+
+```json
+{
+  "id": "1ef266de-5a6c-67d6-86a1-06bb2780ed98",
+  "icao": "KJFK",
+  "iata": "JFK",
+  "lid": "",
+  "name": "John F Kennedy International Airport",
+  "city": "New York",
+  "subdivision": "New York",
+  "country": "US",
+  "timezone": "America/New_York",
+  "elevation": 13,
+  "latitude": 40.6398,
+  "longitude": -73.7789
+}
+```
+
+---
+
+## Examples
+
+### Search Airports by Country
+
+```javascript
+const { SharpApiAirportsService } = require('@sharpapi/sharpapi-node-airports');
+
+const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);
+
+async function getUKAirports() {
+  const airports = await service.getAirports({
+    country: 'GB',
+    iata_assigned: true,
+    per_page: 50
+  });
+
+  console.log(`Found ${airports.meta.total} UK airports`);
+
+  airports.data.forEach(airport => {
+    console.log(`${airport.iata} - ${airport.name}, ${airport.city}`);
+  });
+}
+
+getUKAirports();
+```
+
+### Flight Search Application
+
+```javascript
+const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);
+
+async function searchFlights(departure, arrival) {
+  // Get departure airport
+  const depAirport = await service.getAirportByIata(departure);
+  console.log(`Departure: ${depAirport.name}, ${depAirport.city}`);
+
+  // Get arrival airport
+  const arrAirport = await service.getAirportByIata(arrival);
+  console.log(`Arrival: ${arrAirport.name}, ${arrAirport.city}`);
+
+  // Calculate flight duration
+  const duration = await service.calculateFlightDuration(departure, arrival);
+  console.log(`Estimated Duration: ${duration.hours}h ${duration.minutes}m`);
+  console.log(`Distance: ${duration.distance} km`);
+
+  return {
+    from: depAirport,
+    to: arrAirport,
+    duration: duration
+  };
+}
+
+searchFlights('LHR', 'JFK').then(result => {
+  console.log('Flight Details:', result);
+});
+```
+
+### Travel App Integration
+
+```javascript
+const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);
+
+async function buildDestinationSelector(countryCode) {
+  // Get all cities with airports in the country
+  const cities = await service.getCitiesByCountry(countryCode);
+
+  const destinations = await Promise.all(
+    cities.map(async (city) => {
+      const airports = await service.getAirports({
+        country: countryCode,
+        city: city,
+        iata_assigned: true,
+        per_page: 10
+      });
+
+      return {
+        city: city,
+        airports: airports.data.map(a => ({
+          code: a.iata,
+          name: a.name,
+          timezone: a.timezone
+        }))
+      };
+    })
+  );
+
+  return destinations;
+}
+
+const usDestinations = await buildDestinationSelector('US');
+console.log('US Destinations:', usDestinations);
+```
+
+### Nearby Airports Finder
+
+```javascript
+const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);
+
+async function findNearestAirport(latitude, longitude) {
+  const nearby = await service.getNearbyAirports(latitude, longitude, 50, 5);
+
+  console.log(`Airports within 50km of (${latitude}, ${longitude}):`);
+
+  nearby.forEach((airport, index) => {
+    console.log(`${index + 1}. ${airport.name} (${airport.iata})`);
+    console.log(`   Distance: ${airport.distance} km`);
+    console.log(`   City: ${airport.city}, ${airport.country}`);
+  });
+
+  return nearby[0]; // Return closest airport
+}
+
+// Find airports near San Francisco
+findNearestAirport(37.7749, -122.4194);
+```
+
+### Multi-City Trip Planner
+
+```javascript
+const service = new SharpApiAirportsService(process.env.SHARP_API_KEY);
+
+async function planMultiCityTrip(cities) {
+  const itinerary = [];
+
+  for (let i = 0; i < cities.length - 1; i++) {
+    const fromCity = cities[i];
+    const toCity = cities[i + 1];
+
+    // Find airports in each city
+    const fromAirports = await service.getAirports({
+      city: fromCity,
+      iata_assigned: true,
+      per_page: 1
+    });
+
+    const toAirports = await service.getAirports({
+      city: toCity,
+      iata_assigned: true,
+      per_page: 1
+    });
+
+    if (fromAirports.data.length === 0 || toAirports.data.length === 0) {
+      console.log(`No airports found for ${fromCity} or ${toCity}`);
+      continue;
+    }
+
+    const fromAirport = fromAirports.data[0];
+    const toAirport = toAirports.data[0];
+
+    // Calculate duration
+    const duration = await service.calculateFlightDuration(
+      fromAirport.iata,
+      toAirport.iata
+    );
+
+    itinerary.push({
+      leg: i + 1,
+      from: {
+        city: fromCity,
+        airport: fromAirport.name,
+        code: fromAirport.iata
+      },
+      to: {
+        city: toCity,
+        airport: toAirport.name,
+        code: toAirport.iata
+      },
+      duration: duration
+    });
+  }
+
+  return itinerary;
+}
+
+const cities = ['London', 'Paris', 'Rome', 'Barcelona'];
+const trip = await planMultiCityTrip(cities);
+
+console.log('Multi-City Itinerary:');
+trip.forEach(leg => {
+  console.log(`\nLeg ${leg.leg}: ${leg.from.city} → ${leg.to.city}`);
+  console.log(`  ${leg.from.code} to ${leg.to.code}`);
+  console.log(`  Duration: ${leg.duration.hours}h ${leg.duration.minutes}m`);
+});
+```
+
+---
+
+## Use Cases
+
+- **Travel Booking Platforms**: Airport search and selection
+- **Flight Search Engines**: Calculate durations and distances
+- **Travel Itinerary Planners**: Multi-city trip planning
+- **Mobile Travel Apps**: Nearby airport finder
+- **Aviation Analytics**: Airport database analysis
+- **Route Planning**: Optimize flight routes
+- **Travel Comparison Sites**: Compare flight options
+- **Tourism Applications**: Destination discovery
+
+---
+
+## Database Coverage
+
+- **Total Airports**: ~30,000 worldwide
+- **Coverage**: All continents and major aviation hubs
+- **Code Systems**: IATA, ICAO, and LID codes
+- **Data Fields**: Name, city, country, timezone, elevation, coordinates
+- **Updates**: Regular database maintenance
+
+---
+
+## API Features
+
+- **Synchronous**: Instant responses, no polling required
+- **Paginated Results**: Efficient data retrieval
+- **Flexible Filtering**: Multiple filter options
+- **Geographic Search**: Find airports by location
+- **Duration Calculation**: Estimate flight times
+- **Global Coverage**: Worldwide airport database
+
+---
+
+## API Endpoint
+
+**GET** `/airports`
+
+For detailed API specifications, refer to:
+- [Postman Documentation](https://documenter.getpostman.com/view/31106842/2sBXVeGsW2)
+- [Product Page](https://sharpapi.com/en/catalog/utility/airports-database-flight-duration-calculator)
+
+---
+
+## Related Packages
+
+- [@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**

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sharpapi/sharpapi-node-airports",
+  "version": "1.0.0",
+  "description": "SharpAPI.com Node.js SDK for Airports Database & Flight Duration Calculator",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "sharpapi",
+    "api",
+    "api integration",
+    "restful api",
+    "nodejs",
+    "software development",
+    "airports",
+    "flight duration",
+    "travel",
+    "tourism"
+  ],
+  "author": "Dawid Makowski <contact@sharpapi.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@sharpapi/sharpapi-node-core": "file:../sharpapi-node-core"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sharpapi/sharpapi-node-airports.git"
+  }
+}

package/src/SharpApiAirportsService.js

@@ -0,0 +1,106 @@
+const { SharpApiCoreService } = require('@sharpapi/sharpapi-node-core');
+
+/**
+ * Service for accessing Airports Database & Flight Duration Calculator API using SharpAPI.com
+ */
+class SharpApiAirportsService extends SharpApiCoreService {
+  /**
+   * Get list of airports with optional filters
+   *
+   * @param {object} [filters={}] - Filter options
+   * @param {number} [filters.per_page=25] - Results per page (max 100)
+   * @param {boolean} [filters.iata_assigned] - Filter by IATA code assignment
+   * @param {boolean} [filters.icao_assigned] - Filter by ICAO code assignment
+   * @param {string} [filters.country] - Filter by country
+   * @param {string} [filters.name] - Filter by airport name
+   * @param {string} [filters.city] - Filter by city
+   * @returns {Promise<object>} - List of airports
+   */
+  async getAirports(filters = {}) {
+    const response = await this.makeRequest('GET', '/airports', filters);
+    return response.data;
+  }
+
+  /**
+   * Get airport information by IATA code
+   *
+   * @param {string} iataCode - The IATA code of the airport
+   * @returns {Promise<object>} - Airport information
+   */
+  async getAirportByIata(iataCode) {
+    const response = await this.makeRequest('GET', `/airports/iata/${iataCode}`);
+    return response.data;
+  }
+
+  /**
+   * Get airport information by ICAO code
+   *
+   * @param {string} icaoCode - The ICAO code of the airport
+   * @returns {Promise<object>} - Airport information
+   */
+  async getAirportByIcao(icaoCode) {
+    const response = await this.makeRequest('GET', `/airports/icao/${icaoCode}`);
+    return response.data;
+  }
+
+  /**
+   * Get airport information by UUID
+   *
+   * @param {string} uuid - The UUID of the airport
+   * @returns {Promise<object>} - Airport information
+   */
+  async getAirportByUuid(uuid) {
+    const response = await this.makeRequest('GET', `/airports/${uuid}`);
+    return response.data;
+  }
+
+  /**
+   * Get airports near a specific location
+   *
+   * @param {number} latitude - Latitude of the location
+   * @param {number} longitude - Longitude of the location
+   * @param {number} [radius=100] - Radius in kilometers
+   * @param {number} [limit=10] - Maximum number of results to return
+   * @returns {Promise<object>} - Nearby airports
+   */
+  async getNearbyAirports(latitude, longitude, radius = 100, limit = 10) {
+    const data = { latitude, longitude, radius, limit };
+    const response = await this.makeRequest('GET', '/utility/airports/nearby', data);
+    return response.data;
+  }
+
+  /**
+   * Calculate flight duration between two airports
+   *
+   * @param {string} fromIata - IATA code of departure airport
+   * @param {string} toIata - IATA code of arrival airport
+   * @returns {Promise<object>} - Flight duration information
+   */
+  async calculateFlightDuration(fromIata, toIata) {
+    const response = await this.makeRequest('GET', `/utility/flight-duration/${fromIata}/${toIata}`);
+    return response.data;
+  }
+
+  /**
+   * Get all countries with airports
+   *
+   * @returns {Promise<object>} - List of countries
+   */
+  async getCountries() {
+    const response = await this.makeRequest('GET', '/utility/airports/countries');
+    return response.data;
+  }
+
+  /**
+   * Get all cities with airports in a specific country
+   *
+   * @param {string} countryCode - ISO country code
+   * @returns {Promise<object>} - List of cities
+   */
+  async getCitiesByCountry(countryCode) {
+    const response = await this.makeRequest('GET', `/utility/airports/cities/${countryCode}`);
+    return response.data;
+  }
+}
+
+module.exports = { SharpApiAirportsService };

package/src/index.js

@@ -0,0 +1,6 @@
+// sharpapi-node-airports/src/index.js
+const { SharpApiAirportsService } = require('./SharpApiAirportsService');
+
+module.exports = {
+  SharpApiAirportsService,
+};