true-coord

A powerful, zero-config JavaScript library for working with geographic data. Get instant offline access to comprehensive country information and free geocoding capabilities, no API keys required.

Features

• 250+ Countries & Territories - Complete offline database with rich metadata
• Free Geocoding - Forward and reverse geocoding powered by OpenStreetMap
• No API Keys - Start coding immediately with zero configuration
• Universal - Works in Node.js and browser environments
• Smart Caching - Automatic performance optimization
• Distance Calculation - Calculate distances between any two locations
• Region-Based Search - Filter countries by geographic regions
• Lightweight - Minimal dependencies, maximum efficiency

Installation

npm install true-coord

Quick Start

import trueCoord from 'true-coord';

// Country information
const country = trueCoord.country('Pakistan');
console.log(country.capital); // "Islamabad"

// Forward geocoding 
const coords = await trueCoord.geocode('Eiffel Tower, Paris');
console.log(coords); // { lat: 48.858844, lng: 2.294351 }

// Reverse geocoding 
const location = await trueCoord.reverse(40.7128, -74.0060);

//Distance Calculation
const distance = await trueCoord.distance('France', 'Germany');
console.log(distance); // Distance in kilometers

API Reference

Country Data

country(name)

Retrieve comprehensive data for a specific country by name or ISO code.

const country = trueCoord.country('United States');
console.log(country.capital);    
console.log(country.population); 
console.log(country.currencies); 

Returns: Object containing name, capital, region, population, area, languages, currencies, flags, coordinates, and more.

getAllCountries()

Get an array of all 250+ countries in the database.

getByRegion(region)

Filter countries by geographic region: Africa, Americas, Asia, Europe, Oceania, Antarctic

const asianCountries = trueCoord.getByRegion('Asia');

getNeighbors(countryIdentifier)

Get all countries that share a border with the specified country.

Geocoding

geocode(address, options?)

Convert an address string to geographic coordinates.

Parameters:

• address (string): The address to geocode
• options (object, optional): { limit, countrycodes, language }

Returns: Coordinates object { lat, lng } or array of results if limit > 1

reverse(latitude, longitude, options?)

Convert coordinates to a human-readable address.

Parameters:

• latitude (number): Latitude coordinate
• longitude (number): Longitude coordinate
• options (object, optional): { zoom, language }

Returns: Object with display_name, address, lat, lon

Distance Calculation

distance(from, to, unit?)

Calculate distance between two locations using the Haversine formula.

Parameters:

• from: Country name, address, or coordinates {lat, lng}
• to: Country name, address, or coordinates {lat, lng}
• unit: 'km' (default) or 'miles'

Returns: Distance as a number

Utilities

clearCache()

Clear the internal geocoding cache.

Data Sources

• Country Data: mledoze/countries
• Geocoding: OpenStreetMap Nominatim

Fair Use Policy

trueCoord uses OpenStreetMap's Nominatim service. Please respect their usage policy:

• Maximum 1 request per second
• Cache results when possible (handled automatically)
• For high-volume applications, consider hosting your own Nominatim instance

Browser Support

• Node.js: v12.0.0+
• Modern browsers (Chrome, Firefox, Safari, Edge)
• Mobile browsers

Use Cases

• Location-based web applications
• Data visualization and mapping
• Business intelligence and analytics
• Mobile app development
• Educational projects and research

Contributing

Contributions are welcome! Please open an issue first to discuss major changes.

License

MIT © Chaudary Hammad

Links

• Documentation
• GitHub Repository
• Issue Tracker
• npm Package