Newfangled Package Modernizer
    Have ideas to improve npm?Join in the discussion! »

    worldcities
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.7 • Public • Published

    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})$',
    //     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

    Install

    npm i worldcities

    DownloadsWeekly Downloads

    271

    Version

    0.1.7

    License

    Unlicense

    Unpacked Size

    7.64 MB

    Total Files

    528

    Last publish

    Collaborators

    • avatar