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.
npm install --save geonames.jsor
yarn add geonames.jsYou 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.
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));
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)- 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
MIT 2017 License Karim Abdelcadir
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent