geonames.js v2.3.0 NEW (see changelog)

If you need an API to dynamically fetch countries, states, regions, cities here's the library you're looking for!

geonames.js is a flexible library for browser and Nodejs built on top geonames.org REST API.

1. Installation

npm install --save geonames.js

yarn add geonames.js

2. Requirements

You have to register (it's free) on Geonames.org in order to get the username that will be necessary for the API to work.

geonames.js depends on a native ES6 Promise implementation to be supported. If your environment doesn't support ES6 Promises, you can use a polyfill.

3. Usage:

You can fetch almost anything by taking advandage of the huge amount of information provided by geonames.org. It contains over 10 million geographical names and consists of over 9 million unique features whereof 2.8 million populated places and 5.5 million alternate names.

The list of available options in the API is in here under the webservice column.

Import the library:

server usage (NodeJS)

   const Geonames = require('geonames.js')

browser usage (React, Angular, Vue etc.)

   import Geonames from 'geonames.js'; /* es module */
   const Geonames = require('geonames.js'); /* umd */

alternative for browser

  <script type="text/javascript" src="node_modules/geonames.js/dist/geonames.min.js"></script>

Usage:

Initialize the Geoames using your settings:

free WS

const geonames = new Geonames({
  username: 'myusername',
  lan: 'en',
  encoding: 'JSON'
});

commercial WS

To use the commercial tier just define your token:

const geonames = new Geonames({
  username: 'myusername',
  token: 'mytoken',
  lan: 'en',
  encoding: 'JSON'
});

Since the library return promises, you can use either async/await or promise-based syntax

plain call

// async/await
try{
  const continents = await geonames.search({q: 'CONT'}) //get continents
}catch(err){
  console.error(err);
}

// promise
geonames.search({q: 'CONT'}) //get continents
.then(resp => {
  console.log(resp.geonames);
})
.catch(err => console.error(err));

chaining calls

// async/await
try{
  const countries = await geonames.countryInfo({}) //get continents
  const states = await geonames.children({geonameId: countries.geonames[0].geonameId})
  const regions = await geonames.children({geonameId: states.geonames[0].geonameId});
  const cities = await geonames.children({geonameId: regions.geonames[0].geonameId});
  console.log(cities.geonames);
}catch(err){
  console.error(err);
}

// promise
geonames.countryInfo({}) 
.then(countries => {
  return geonames.children({geonameId: countries.geonames[0].geonameId})
})
.then(states => {
  return geonames.children({geonameId: states.geonames[0].geonameId});
})
.then(regions => {
  return geonames.children({geonameId: regions.geonames[0].geonameId});
})
.then(cities => {
  console.log(cities.geonames);
})
.catch(err => console.log(err));

4. Contribution:

Feel free to contribute; any help is really appreciated :)

run with:

yarn build-dev (dev bundle)
yarn build (prod bundle)
yarn build:all (both - for packaging)
USERNAME=myusername yarn test (unit testing)

5. Changelog v2.3.0:

Added support to Commercial Tier

6. License:

MIT 2017 License Karim Abdelcadir

7. Troubleshooting

If using TSX and see the

Could not find a declaration file for module 'geonames.js'. ... implicitly has an 'any' type.

error, try adding

// index.ts
declare module "geonames.js";

matomesc / geonames.js