world-borders

Country borders and shapes as GeoJSON and TopoJSON. Get geographic boundaries for any country by ISO code.

Features

• 🌍 240+ countries and territories - Complete global coverage
• 📦 Bundled data - Works offline, no API calls needed
• 🗺️ GeoJSON & TopoJSON - Simplified boundaries optimized for visualization
• 🔍 Flexible lookup - Search by ISO2, ISO3, or country name
• 📝 TypeScript - Full type definitions included
• 🌳 Tree-shakeable - Only bundle what you use

Installation

npm install world-borders

Quick Start

import { getGeoJSON, getTopoJSON, findCountry } from 'world-borders';

// Get country boundary as GeoJSON
const germany = await getGeoJSON('DE');
console.log(germany.name);     // "Germany"
console.log(germany.geometry); // FeatureCollection

// Get as TopoJSON (more compact)
const france = await getTopoJSON('FR');

// Search by name
const results = await findCountry('united');
// Returns: [{ iso2: 'US', name: 'United States' }, { iso2: 'GB', name: 'United Kingdom' }, ...]

API

getGeoJSON(code)

Get simplified GeoJSON boundary for a country.

const result = await getGeoJSON('US');
// Returns: {
//   iso2: 'US',
//   iso3: 'USA',
//   name: 'United States of America',
//   geometry: FeatureCollection,
//   bbox: [minLon, minLat, maxLon, maxLat]
// }

getTopoJSON(code)

Get simplified TopoJSON boundary for a country (more compact).

const result = await getTopoJSON('JP');
// Returns: {
//   iso2: 'JP',
//   iso3: 'JPN',
//   name: 'Japan',
//   geometry: Topology,
//   bbox: [minLon, minLat, maxLon, maxLat]
// }

getCountry(code, options)

Universal function to get country data in any format.

const geojson = await getCountry('DE', { format: 'geojson' });
const topojson = await getCountry('DE', { format: 'topojson' });

findCountry(query)

Search for countries by name, ISO2, or ISO3 code.

const results = await findCountry('germany');
// Returns: [{ iso2: 'DE', iso3: 'DEU', name: 'Germany', ... }]

const results = await findCountry('UK'); // Supports common aliases
// Returns: [{ iso2: 'GB', iso3: 'GBR', name: 'United Kingdom', ... }]

Country Utilities

import { 
  countries,      // Array of all countries
  toISO2,         // Convert ISO3 to ISO2
  toISO3,         // Convert ISO2 to ISO3
  isValidCode,    // Check if a code is valid
  getCountryByCode // Get country info by code
} from 'world-borders';

// Get all countries
console.log(countries.length); // 250+

// Convert codes
toISO2('USA'); // 'US'
toISO3('DE');  // 'DEU'

// Validate codes
isValidCode('US');  // true
isValidCode('XX');  // false

Data Source

Geographic data is sourced from geoBoundaries - an open license, open data boundary dataset.

• License: CC-BY 4.0
• Resolution: Simplified boundaries optimized for visualization
• Level: ADM0 (country-level boundaries)

TypeScript

Full type definitions are included:

import type {
  CountryBoundary,
  GeoJSONBoundary,
  TopoJSONBoundary,
  Country,
  OutputFormat,
} from 'world-borders';

License

• Code: MIT
• Data: CC-BY 4.0 (geoBoundaries)

When using this package, please attribute geoBoundaries as the data source.