@spurreiter/geocoder

geocoder

This project is derived on 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

supported providers

Provider	forward	reverse	ip	Notes
ArcGisGeocoder	✅	✅	❌
BingMapsGeocoder	✅	✅	❌	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	✅	✅	❌
LocalGeoip2Geocoder	❌	❌	✅	Local geoip2 provider. Output as of @maxmind/geoip2-node
MapBoxGeocoder	✅	✅	❌
MapQuestGeocoder	✅	✅	❌	open-data and licensed versions are supported
OpenCageGeocoder	✅	✅	❌
OsmGeocoder	✅	✅	❌	Searches nominatim.org
PeliasGeocoder	✅	✅	❌	Local or Geocode.earth
TeleportGeocoder	✅	✅	❌	Searches only by city names, no addresses

usage

forward geocoding

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

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

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 })
]
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.

Works with forward and reverse geocoding.

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

const geocoders = [
  new HereGeocoder(adapter, { apiKey_ 'your-api-key' }),
  new OsmGeocoder(adapter)
]
const combine = new Combine(geocoders)

const results = await combine.forward({ address: '135 pilkington avenue, birmingham', language: 'es' })

// results contains data from all reachable geocoders.

contributing

If you are missing a provider, which should be part of this project, please consider forking this project and filing a pull-request.

license

MIT licensed