Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@spurreiter/geocoder

Package Overview
Dependencies
Maintainers
0
Versions
16
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@spurreiter/geocoder

Node geocoding library, google maps, bing maps, mapquest, mapbox, here maps, arcgis, nominatim, ...

  • 2.1.1
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
0
Created
Source

CI npm version Downloads per month

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

ProviderforwardreverseipNotes
ArcGisGeocoder
BingMapsGeocoderresults are in English only
GoogleGeocoder
GeocodioGeocoderresults 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
GeoLite2GeocoderLocal GeoLite2 provider or MaxMind API. Output as of @maxmind/geoip2-node
MapBoxGeocoder
MapQuestGeocoderopen-data and licensed versions are supported
OpenCageGeocoder
OpendataFranceGeocoderFrance only
OpenMapQuestSearch Results based on OSM
OsmGeocoderSearches nominatim.org
PeliasGeocoderLocal or Geocode.earth
PickpointGeocoderSearch 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

Keywords

FAQs

Package last updated on 04 Nov 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc