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.
- 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
npm install true-coordimport 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 kilometersRetrieve 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.
Get an array of all 250+ countries in the database.
Filter countries by geographic region: Africa, Americas, Asia, Europe, Oceania, Antarctic
const asianCountries = trueCoord.getByRegion('Asia');Get all countries that share a border with the specified country.
Convert an address string to geographic coordinates.
Parameters:
address(string): The address to geocodeoptions(object, optional):{ limit, countrycodes, language }
Returns: Coordinates object { lat, lng } or array of results if limit > 1
Convert coordinates to a human-readable address.
Parameters:
latitude(number): Latitude coordinatelongitude(number): Longitude coordinateoptions(object, optional):{ zoom, language }
Returns: Object with display_name, address, lat, lon
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
Clear the internal geocoding cache.
- Country Data: mledoze/countries
- Geocoding: OpenStreetMap Nominatim
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
- Node.js: v12.0.0+
- Modern browsers (Chrome, Firefox, Safari, Edge)
- Mobile browsers
- Location-based web applications
- Data visualization and mapping
- Business intelligence and analytics
- Mobile app development
- Educational projects and research
Contributions are welcome! Please open an issue first to discuss major changes.
MIT © Chaudary Hammad