geonames.js
v3.0.6
Published
REST api to fetch countries, regions, cities etc. A flexible library for browser and node.js usage built on top http://www.geonames.org/
Downloads
7,263
Readme
geonames.js v3.0.3 NEW (see changelog)
geonames.js
is a flexible library for browser and Nodejs
built on top geonames.org webservices.
It provides a simple API to dynamically fetch countries, states, regions, cities and other milion geographical names.
1. Installation
npm install --save geonames.js
or
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 advantage 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') /* commonJS */
- browser usage (React, Angular, Vue etc.)
import Geonames from 'geonames.js'; /* es module */
Usage:
Initialize the Geoames using your settings:
free WS
const geonames = Geonames({ username: 'myusername', lan: 'en', encoding: 'JSON' });
commercial WS
To use the commercial tier just define your
token
:const geonames = 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 v3.0.3:
- Added support for latest Geonames api (address, geoCodeAddress, streetNameLookup)
- Added typescript autocomplete for all the api's
- change function constructor to plain function
- updated dependencies
6. License:
MIT 2017 License Karim Abdelcadir