https://github.com/alice39s/ourairports-data-js
A TypeScript library for working with OurAirports Data data.
https://github.com/alice39s/ourairports-data-js
airports bun iata-codes iata-lookup icao-codes icao-lookup typescript
Last synced: 5 months ago
JSON representation
A TypeScript library for working with OurAirports Data data.
- Host: GitHub
- URL: https://github.com/alice39s/ourairports-data-js
- Owner: Alice39s
- License: mit
- Created: 2025-02-09T05:07:29.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-01T00:16:19.000Z (6 months ago)
- Last Synced: 2026-01-05T13:42:21.655Z (6 months ago)
- Topics: airports, bun, iata-codes, iata-lookup, icao-codes, icao-lookup, typescript
- Language: TypeScript
- Homepage:
- Size: 153 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OurAirports Data - JS Library
A TypeScript library for working with [OurAirports Data](https://github.com/davidmegginson/ourairports-data) data. This library provides easy access to airport information, including IATA/ICAO codes, geographical coordinates, and more.
> [!WARNING]
> 🔧 This library is not yet ready for production use. It is still under development.
>
> This project uses only clean data containing IATA Code airports in order to reduce the size of the package.
> [!IMPORTANT]
> This is not an official project of OurAirports.com!
## Features
- 🌐 Universal package that works in both Node.js and browser environments
- 🔍 Search airports by IATA/ICAO codes
- 🗺️ Find airports by country or within a radius
- ✨ TypeScript support with full type definitions
- 🚀 Modern ESM package with tree-shaking support
- ⚡ Efficient data loading with sharding
- 🔒 Data validation using Zod schemas
- 📦 Automatic environment detection and optimization
## Installation
### Package Manager
```bash
npm install ourairports-data-js
# or
yarn add ourairports-data-js
# or
pnpm add ourairports-data-js
# or
bun add ourairports-data-js
```
### CDN
```html
import OurAirports from 'https://unpkg.com/ourairports-data-js/dist/browser/index.js';
const airports = new OurAirports();
await airports.init();
import OurAirports from 'https://cdn.jsdelivr.net/npm/ourairports-data-js/dist/browser/index.js';
const airports = new OurAirports();
await airports.init();
```
## Usage
### Basic Usage
The library automatically detects your environment (Node.js or browser) and uses the appropriate implementation:
```typescript
import OurAirports from 'ourairports-data-js';
async function main() {
// Create instance
const airports = new OurAirports();
// Initialize (auto-detects environment)
await airports.init();
// Find airport by IATA code
const pek = airports.findByIataCode('PEK');
console.log(pek?.name); // "Beijing Capital International Airport"
console.log(pek?.type); // "large_airport"
// Find airport by ICAO code
const zbaa = airports.findByIcaoCode('ZBAA');
console.log(zbaa?.name); // "Beijing Capital International Airport"
// Find airports in China
const chineseAirports = airports.findByCountry('CN');
console.log(`Found ${chineseAirports.length} airports in China`);
// Find airports within 100km radius of Beijing Capital Airport
const nearbyAirports = airports.findAirportsInRadius(40.0799, 116.6031, 100);
console.log(
'Nearby airports:',
nearbyAirports.map(a => a.name)
);
// Search airports with filters
const largeAirports = airports.searchAirports({
type: 'large_airport',
hasIataCode: true,
hasScheduledService: true,
country: 'CN',
continent: 'AS',
});
}
main().catch(console.error);
```
### Advanced Usage
#### Environment-Specific Imports
You can explicitly import the environment-specific version if needed:
```typescript
// Browser-specific import
import OurAirports from 'ourairports-data-js/browser';
// Node.js-specific import
import OurAirports from 'ourairports-data-js/node';
```
#### Type Imports
```typescript
// Import types
import type {
BasicInfo, // Airport basic information
AirportFilter, // Search filter interface
AirportType, // Airport type enum
Coordinates, // Airport coordinates
Region, // Airport region information
} from 'ourairports-data-js';
// Import validation schemas
import { BasicInfoSchema, CoordinatesSchema, RegionSchema } from 'ourairports-data-js';
```
### Search Examples
#### Find by IATA/ICAO Code
```typescript
// Find by IATA code
const pek = airports.findByIataCode('PEK');
console.log(pek?.name); // "Beijing Capital International Airport"
// Find by ICAO code
const zbaa = airports.findByIcaoCode('ZBAA');
console.log(zbaa?.name); // "Beijing Capital International Airport"
```
#### Search with Filters
```typescript
// Search for major airports in China
const majorAirports = airports.searchAirports({
type: 'large_airport',
country: 'CN',
hasIataCode: true,
hasScheduledService: true,
continent: 'AS',
});
// Find airports within radius
const nearbyAirports = airports.findAirportsInRadius(
40.0799, // latitude
116.6031, // longitude
100 // radius in kilometers
);
```
### Advanced Features
#### Raw Data Access
```typescript
// Get access to raw data for advanced usage
const { basicInfo, codes, coordinates, region, references } = airports.data;
```
#### Environment Detection
```typescript
// Check current environment
if (airports.isInBrowser) {
console.log('Running in browser');
} else {
console.log('Running in Node.js');
}
```
## API Reference
### Constructor
- `new OurAirports()` - Create a new instance
### Initialization Methods
- `init()` - Auto-detect environment and initialize (recommended)
- `initialize()` - Explicit Node.js initialization
- `initializeAsync()` - Explicit browser initialization
### Search Methods
- `findByIataCode(code: string): BasicInfo | undefined` - Find airport by IATA code
- `findByIcaoCode(code: string): BasicInfo | undefined` - Find airport by ICAO code
- `findByCountry(countryCode: string): BasicInfo[]` - Find airports by country code
- `findAirportsInRadius(lat: number, lon: number, radiusKm: number): BasicInfo[]` - Find airports within radius
- `searchAirports(filter: AirportFilter): BasicInfo[]` - Search airports with filters
### Properties
- `isInitialized: boolean` - Check if the instance is initialized
- `isInBrowser: boolean` - Check if running in browser environment
- `data: AirportData` - Get raw data for advanced usage
### Types
```typescript
interface AirportFilter {
type?: string; // e.g., 'large_airport', 'medium_airport', 'small_airport'
country?: string; // ISO country code, e.g., 'US', 'CN'
continent?: string; // Continent code, e.g., 'NA', 'AS'
hasIataCode?: boolean; // Whether the airport has an IATA code
hasScheduledService?: boolean; // Whether the airport has scheduled service
}
interface BasicInfo {
id: number; // Unique identifier
ident: string; // Airport identifier (usually ICAO code)
type: string; // Airport type
name: string; // Airport name
// ... more fields available in ./src/types.ts
}
```
## Data Updates
The library uses data from OurAirports, which is updated periodically:
- Node.js: Data is bundled with the package
- Browser: Data is automatically fetched from CDN
- Updates are delivered with each package release
## Environment-Specific Features
### Node.js
- Synchronous data loading available
- File system access for data files
- Better performance with local data
- CommonJS and ESM support
### Browser
- Automatic CDN data loading
- No file system dependencies
- Optimized bundle size
- Modern ESM format
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Data provided by [OurAirports](https://ourairports.com/)
- Built with TypeScript and Zod
- Powered by jsDelivr CDN for browser environments