Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including worldcities with all npm packages installed. Try it out:

var worldcities = require("worldcities")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

worldcities v0.1.6

Convenience library for looking up city and country data using GPS coordinates and by name.

World Cities

Coverage Status

24,343 world cities and 252 countries.

A convenient wrapper for the GeoNames database of world cities data.

The data from the GeoNames tab seperated values files are parsed and normalized into a JSON object for quick lookup and distance calculations. The data for each city's country is also normalized, indexed by ISO_3166-1 country code, paired with the country's flag's SVG, GeoJSON of its boundaries, and relative URL to Wikipedia page.

Usage

Query for a city by GPS

const WorldCities = require('worldcities');
const city = WorldCities.getNearestCity(5.42282298420212, 100.33753796627954);

// City {
//   latitude: 5.41123,
//   longitude: 100.33543,
//   name: 'George Town',
//   population: 300000,
//   timezone: 'Asia/Kuala_Lumpur',
//   country: Country {
//     areaSquareMeters: 329750,
//     callingCode: '60',
//     capital: 'Kuala Lumpur',
//     continent: 'AS',
//     countryCode: 'MY',
//     countryCode3: 'MYS',
//     currencyCode: 'MYR',
//     currencyName: 'Ringgit',
//     languages: [
//       'ms-MY', 'en',
//       'zh',    'ta',
//       'te',    'ml',
//       'pa',    'th'
//     ],
//     name: 'Malaysia',
//     neighbors: [ 'BN', 'TH', 'ID' ],
//     population: 31528585,
//     postalCodeRegExp: '^(\\d{5})apos;,
//     tld: '.my',
//     wikipedia: 'Malaysia',
//     geoJSON: undefined,
//     flagSVG: undefined
//   }
// }

Query for a large city by GPS

const WorldCities = require('worldcities');
const city = WorldCities.getNearestLargeCity(17.076480407330514, -101.3674415353851);

Query for a single city by name

const city = WorldCities.getByName('Tokyo');

Query all cities matching a name

const cities = WorldCities.getByName('nEw yOrK');
assert.equal(cities.length, 3);

Get a Country by Country Code

Retrieve the country data by querying for it by the 2 letter country code. The second argument returns the Country with full data, including geoJSON and flag SVG.

const country = WorldCities.getCountry('NZ', true);
fs.writeFileSync('nz.flag.svg', country.flagSVG);

Timezones

The city data includes the IANA timezone ID in string format; ie. "America/Los_Angeles". To use these to localize dates and times to the city, it's highly recommended to use the Moment Timezone library.

For example, to convert a UNIX timestamp to a localized date time string:

const moment = require('moment-timezone');

moment(Math.floor(Date.now() / 1000), 'X')
  .tz('America/Los_Angeles')
  .format('dddd, MMMM Do YYYY, h:mm:ss a z');

// "Friday, May 1st 2020, 5:52:11 am PDT"

GeoJSON

GeoJSON objects can be visualized nicely in the http://geojson.io/ UI.

Google Maps also supports using GeoJSON as a "Data Layer" via the API.

SQLite

All of the data is also available in a compact SQLite file. It is in the source repository, but not included in the package to keep size reasonable.

[https://raw.githubusercontent.com/OpenDataFormats/worldcities/master/data/worldcities.sqlite]

Data Sources

City and country data:

GeoNames

Flag SVG data

flag-icon-css

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free