geocoder

This project is derived from node-geocoder with focus on modern code with esm modules.

Features:

multiple providers
similar results for all providers
modern code based on esm modules and native Promises with async/ await
Typescript types
http(s) agent by default for reusing tcp connections
fetch based http adapter with timeout
cascade providers and stop on first successful result
combine search results from multiple providers
configurable circuit breaker which stops calling geocoder e.g. if request limit is exhausted.
extensive test-suite with examples for getting started
GeoJSON, GPX formatters

supported providers

| Provider | forward | reverse | ip | Notes | | ----------------------------------------------------------------------------------------------- | :-----: | :-----: | :-: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ArcGisGeocoder | ✅ | ✅ | ❌ | | | AzureMapsGeocoder | ✅ | ✅ | ❌ | | | ~~BingMapsGeocoder~~ DEPRECATED | ✅ | ✅ | ❌ | results are in English only | | GoogleGeocoder | ✅ | ✅ | ❌ | | | GeocodioGeocoder | ✅ | ✅ | ❌ | results are in English only; Country must be part of query, otherwise fallback to US; Only US and major cities in CA supported | | HereGeocoder | ✅ | ✅ | ❌ | | | IpStackGeocoder | ❌ | ❌ | ✅ | | | LocationIqGeocoder | ✅ | ✅ | ❌ | | | GeoLite2Geocoder | ❌ | ❌ | ✅ | Local GeoLite2 provider or MaxMind API. Output as of @maxmind/geoip2-node | | MapBoxGeocoder | ✅ | ✅ | ❌ | | | MapQuestGeocoder | ✅ | ✅ | ❌ | open-data and licensed versions are supported | | OpenCageGeocoder | ✅ | ✅ | ❌ | | | OpendataFranceGeocoder | ✅ | ✅ | ❌ | France only | | OpenMapQuest | ✅ | ✅ | ❌ | Search Results based on OSM | | OsmGeocoder | ✅ | ✅ | ❌ | Searches nominatim.org | | PeliasGeocoder | ✅ | ✅ | ❌ | Local or Geocode.earth | | PickpointGeocoder | ✅ | ✅ | ❌ | Search Results based on OSM | | TomTomGeocoder | ✅ | ✅ | ❌ | | | YandexGeocoder | ✅ | ✅ | ❌ | |

usage

forward geocoding

import { fetchAdapter, OsmGeocoder } from '@spurreiter/geocoder'

const adapter = fetchAdapter()
const geocoder = new OsmGeocoder(adapter, 
  { language: 'en', limit: 5, referer: 'https://mysite' })

const results = await geocoder.forward('135 pilkington avenue, birmingham')
// [
//   {
//     formattedAddress: '135, Pilkington Avenue, Maney, Sutton Coldfield, Wylde Green, Birmingham, West Midlands Combined Authority, West Midlands, England, B72 1LH, United Kingdom',
//     latitude: 52.5487921,
//     longitude: -1.8164308339635031,
//     country: 'United Kingdom',
//     countryCode: 'GB',
//     state: 'England',
//     county: 'West Midlands Combined Authority',
//     city: 'Birmingham',
//     zipcode: 'B72 1LH',
//     district: 'West Midlands',
//     streetName: 'Pilkington Avenue',
//     streetNumber: '135',
//     neighbourhood: undefined,
//     extra: {
//       id: 90394480,
//       confidence: 0.411,
//       bbox: [ -1.816513, 52.5487473, -1.8163464, 52.5488481 ]
//     }
//   }
// ]

reverse geocoding

const results = await geocoder.reverse({ lat: 40.714232, lng: -73.9612889 })
// [
//   {
//     formattedAddress: '279, Bedford Avenue, Williamsburg, Brooklyn, Kings County, New York, 11211, United States',
//     latitude: 40.714205,
//     longitude: -73.96131519274765,
//     country: 'United States',
//     countryCode: 'US',
//     state: 'New York',
//     county: undefined,
//     city: 'New York',
//     zipcode: '11211',
//     district: undefined,
//     streetName: 'Bedford Avenue',
//     streetNumber: '279',
//     neighbourhood: undefined,
//     extra: {
//       id: 279767984,
//       confidence: 0,
//       bbox: [ -73.9613744, 40.7141617, -73.961256, 40.7142482 ]
//     }
//   }
// ]

cascade

Allows to sequentially ask various geocoders for results. Successful results from the first geocoder are returned.

Works with forward and reverse geocoding.

import { Cascade, fetchAdapter, HereGeocoder, OsmGeocoder } from '@spurreiter/geocoder'

const language = "es"
const geocoders = [
  new HereGeocoder(adapter, { apiKey: 'your-api-key', language }),
  new OsmGeocoder(adapter, { language, referer: 'https://mysite' })
]
const cascade = new Cascade(geocoders)

const results = await cascade.forward('135 pilkington avenue, birmingham')

// results contains data from 1st geocoder which responds without error.

combine

Combine results from various geocoders into one result set.