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 | ✅ | ✅ | ❌ | | | 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 | ✅ | ✅ | ❌ | | | 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.

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, { referer: 'https://mysite' })
]
const combine = new Combine(geocoders)

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

// results contains data from all reachable geocoders.

formatters

Formatters allow to format the geocoder result object to various formats like geoJson or gpx.

geoJsonFormatter

The output of the GeoJSON formatter is according to RFC-7946 and geocodejson-spec.

import { geoJsonFormatter } from '@spurreiter/geocoder'

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

const geoJson = geoJsonFormatter(results, {query})
// {
//   type: 'FeatureCollection',
//   geocoding: {
//     version: '0.1.0',
//     license: null,
//     attribution: null,
//     query: '135 pilkington avenue, birmingham'
//   },
//   features: [{...}, ...]
// }

gpxFormatter

import { gpxFormatter } from '@spurreiter/geocoder'

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

const gpx = gpxFormatter(results)
// <?xml version="1.0" encoding="UTF-8"?>
// <gpx version="1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.topografix.com/GPX/1/0" xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
// <wpt lat="52.5487921" lon="-1.8164308339635031"><name>135, Pilkington Avenue, Maney, Sutton Coldfield, Wylde Green, Birmingham, West Midlands Combined Authority, West Midlands, England, B72 1LH, United Kingdom</name></wpt>
// </gpx>

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