okcoker / node-geocoder-ts

nodejs geocoding library

Node Geocoder TS

Node library for geocoding and reverse geocoding.

This is based on the original node-geocoder library and is fully rewritten in TypeScript. The API is not fully backwards compatible with the JS version.

There have been, and will be a few major changes.

• Fully re-written in TypeScipt
• Restructured project
• Callbacks have been removed in favor of promises
• Here provider has been updated with a version option (defaults to v7)
• Sinon and Chai were removed as dependencies in favor of Just Jest™
• add options.formatterOptions to be passed to whatever options.formatter is provided
• Potentially create general option shape that can map to all provider options
• Update reverse() params to use longitude & latitude instead of lon/lat
• Remove instaces of _reverse() in favor of reverse()
• Create provider-specific option types for each geocode and reverse method
• Create integration tests for every provider
• Update APIs (ie SmartyStreets is now Smarty and has a different endpoint)
• Add reverse geocoding to TomTom provider
• Add reverse geocoding to Yandex provider
• Add RapidAPI
• Add Maps.co
• Add Geonames
• Migrate NominatimMapQuestProvider to Nominatim (with mapquest and osm server options)

Installation (nodejs library)

npm install node-geocoder

Usage example

const createGeocoder = require('node-geocoder-ts');
const geocoder = createGeocoder({
  provider: 'google',

  // Optional depending on the providers
  fetch: customFetchImplementation,
  apiKey: 'YOUR_API_KEY', // for Mapquest, OpenCage, Google Premier
  formatter: null // 'gpx', 'string', ...
});

// Using callback
const res = await geocoder.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'
  }
];

Advanced usage (only google, here, mapquest, locationiq, and opencage providers)

const result = await geocoder.geocode({
  address: '29 champs elysée',
  country: 'France',
  zipcode: '75008'
});

// OpenCage advanced usage example
const result = await geocoder.geocode({
  address: '29 champs elysée',
  countryCode: 'fr',
  minConfidence: 0.5,
  limit: 5
});

// Reverse example

const result = await geocoder.reverse({ lat: 45.767, lon: 4.833 });

// Batch geocode

const batchResult = await geocoder.batchGeocode([
  '13 rue sainte catherine',
  'another address'
]);

// Set specific http request headers:
const nodeFetch = require('node-fetch');

const geocoder = createGeocoder({
  provider: 'google',
  fetch: function fetch(url, options) {
    return nodeFetch(url, {
      ...options,
      headers: {
        'user-agent': 'My application <[e-mail]>',
        'X-Specific-Header': 'Specific value'
      }
    });
  }
});

Geocoder Providers (in alphabetical order)

Service	Provider	Forward Geocoding	Reverse Geocoding	Authentication
ArcGis	agol	✅	✅	clientId, clientSecret
Data Science Toolkit	datasciencetoolkit	✅	✅
FreeGeoIP.net	freegeoip	✅ (IP only)
Geocodio	geocodio	✅ (US & CA)	✅ (US & CA)
Google	google	✅	✅	apiKey
Here	here	✅	✅	apiKey
LocationIQ	locationiq	✅	✅	apiKey
Mapbox	mapbox	✅	✅	apiKey
MapQuest	mapquest	✅	✅	apiKey
OpenCage	opencage	✅	✅	apiKey
OpenDataFrance	opendatafrance	✅	✅	apiKey
[OpenStreetMap]	openstreetmap	✅	✅
PickPoint	pickpoint	✅	✅	apiKey
Smarty	smartystreets	✅		authId, authToken
Teleport	teleport	✅	✅
TomTom	tomtom	✅		apiKey
VirtualEarth	virtualearth	✅	✅	apiKey
Yandex	yandex	✅		apiKey

Fetch option

With the options.fetch you can provide your own method to fetch data. This method should be compatible with the Fetch API.

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

Formatter

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

Extending node geocoder

You can add new geocoders by implementing the two methods geocode and reverse:

const geocoder = {
    geocode: function(value, callback) { ... },
    reverse: function(query, callback) { var lat = query.lat; var lon = query.lon; ... }
}

You can also add formatter implementing the following interface

const formatter = {
  format: function(data) {
    return formattedData;
  }
};

Contributing

You can improve this project by adding new geocoders.

To run tests just npm test.

To check code style just run npm run lint.