Repository files navigation

Node library for geocoding and reverse geocoding. Can be used as a nodejs library

npm install node-geocoder

constNodeGeocoder=require('node-geocoder');constoptions={provider:'google',// Optional depending on the providersfetch:customFetchImplementation,apiKey:'YOUR_API_KEY',// for Mapquest, OpenCage, APlace, Google Premierformatter:null// 'gpx', 'string', ...};constgeocoder=NodeGeocoder(options);// Using callbackconstres=awaitgeocoder.geocode('29 champs elysée paris');// output :[{latitude:48.8698679,longitude:2.3072976,country:'France',countryCode:'FR',city:'Paris',zipcode:'75008',streetName:'Champs-Élysées',streetNumber:'29',administrativeLevels:{level1long:'Île-de-France',level1short:'IDF',level2long:'Paris',level2short:'75'},provider:'google'}];

constres=awaitgeocoder.geocode({address:'29 champs elysée',country:'France',zipcode:'75008'});// OpenCage advanced usage exampleconstres=awaitgeocoder.geocode({address:'29 champs elysée',countryCode:'fr',minConfidence:0.5,limit:5});// Reverse exampleconstres=awaitgeocoder.reverse({lat:45.767,lon:4.833});// Batch geocodeconstresults=awaitgeocoder.batchGeocode(['13 rue sainte catherine','another address']);// Set specific http request headers:constnodeFetch=require('node-fetch');constgeocoder=NodeGeocoder({provider:'google',fetch:functionfetch(url,options){returnnodeFetch(url,{      ...options,headers:{'user-agent':'My application <email@domain.com>','X-Specific-Header':'Specific value'}});}});

• agol : ArcGis Online Geocoding service. Supports geocoding and reverse. Requires a client_id & client_secret
• aplace : APlace.io Geocoding service. Supports geocoding and reverse. Requires an access token (read about access tokens here) usingoptions.apiKey
  • Forgeocode you can use simple string parameter or an object containing the different parameters (type,address,zip,city,country,countryCode andcountries). See available values fortype andcountries parametershere
  • Forreverse, you can pass over{lat, lon}
  • For both methods, useoptions.language (eitherfr oren) to specify the language of the results
• datasciencetoolkit : DataScienceToolkitGeocoder. Supports IPv4 geocoding and address geocoding. Useoptions.host to specify a local instance
• freegeoip : FreegeoipGeocoder. Supports IP geocoding
• geocodio: Geocodio, Supports address geocoding and reverse geocoding (US only)
• google : GoogleGeocoder. Supports address geocoding and reverse geocoding. Useoptions.clientIdandoptions.apiKey(privateKey) for business licence. You can also useoptions.language andoptions.region to specify language and region, respectively.
• here : HereGeocoder. Supports address geocoding and reverse geocoding. You must specifyoptions.apiKey with your Here API key. You can also useoptions.language,options.politicalView (read about political views here),options.country, andoptions.state.
• locationiq : LocationIQGeocoder. Supports address geocoding and reverse geocoding just like openstreetmap but does require only a locationiq api key to be set.
  • Forgeocode you can use simpleq parameter or an object containing the different parameters defined here:http://locationiq.org/#docs
  • Forreverse, you can pass over{lat, lon} and additional parameters defined inhttp://locationiq.org/#docs
  • No need to specify referer or email addresses, just locationiq api key, note that there are rate limits!
• mapbox : MapBoxGeocoder. Supports address geocoding and reverse geocoding. Needs an apiKey
• mapquest : MapQuestGeocoder. Supports address geocoding and reverse geocoding. Needs an apiKey
• nominatimmapquest: Same geocoder asopenstreetmap, but queries the MapQuest servers. You need to specifyoptions.apiKey
• opencage: OpenCage Geocoder. Aggregates many different open geocoder. Supports address and reverse geocoding withmany optional parameters. You need to specifyoptions.apiKey which can be obtained atOpenCage.
• opendatafrance: OpendataFranceGeocoder supports forward and reverse geocoding in France; for more information, seeOpendataFrance API documentation
• openmapquest : Open MapQuestGeocoder (based on OpenStreetMapGeocoder). Supports address geocoding and reverse geocoding. Needs an apiKey
• openstreetmap : OpenStreetMapGeocoder. Supports address geocoding and reverse geocoding. You can useoptions.language andoptions.email to specify a language and a contact email address.
  • Forgeocode, you can use an object as value, specifyingone or several parameters
  • Forreverse, you can useadditional parameters
  • You should specify a specificuser-agent orreferrer header field as required by theOpenStreetMap Usage Policy
  • Setoptions.osmServer to use custom nominatim server. Example: you can setup local nominatim server by followingthese instructions and setoptions.osmServer: http://localhost:8000 to use local server.
• pickpoint: PickPoint Geocoder. Supports address geocoding and reverse geocoding. You need to specifyoptions.apiKey obtained atPickPoint.
  • As parameter forgeocode function you can use a string representing an address like "13 rue sainte catherine" or an object with parameters described inForward Geocoding Reference.
  • Forgeocode function you should use an object where{lat, lon} are required parameters. Additional parameters likezoom are available, see details inReverse Geocoding Reference.
• smartyStreet: Smarty street geocoder (US only), you need to specifyoptions.auth_id andoptions.auth_token
• teleport: Teleport supports city and urban area forward and reverse geocoding; for more information, seeTeleport API documentation
• tomtom: TomTomGeocoder. Supports address geocoding. You need to specifyoptions.apiKey and can useoptions.language to specify a language
• virtualearth: VirtualEarthGeocoder (Bing maps). Supports address geocoding. You need to specifyoptions.apiKey
• yandex: Yandex support address geocoding, you can useoptions.language to specify language

With theoptions.fetch you can provide your own method to fetch data. This method should be compatible with theFetch API.

This allow you to specify a proxy to use, a custom timeout, specific headers, ...

• gpx : format result using GPX format
• string : format result to an String array (you need to specifyoptions.formatterPattern key)
  • %P country
  • %p country code
  • %n street number
  • %S street name
  • %z zip code
  • %T State
  • %t state code
  • %c City

You can try node-geocoder herehttp://node-geocoder.herokuapp.com/

node-geocoder-cli You can use node-geocoder-cli to geocode in shell

You can add new geocoders by implementing the two methodsgeocode andreverse:

constgeocoder={geocode:function(value,callback){ ...},reverse:function(query,callback){varlat=query.lat;varlon=query.lon; ...}}

You can also add formatter implementing the following interface

constformatter={format:function(data){returnformattedData;}};

You can improve this project by adding new geocoders.

To run tests justnpm test.

To check code style just runnpm run lint.