@spurreiter/geocoder
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.0 • Public • Published

    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
    TeleportGeocoder Searches only by city names, no addresses
    YandexGeocoder

    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.

    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

    Install

    npm i @spurreiter/geocoder

    DownloadsWeekly Downloads

    16

    Version

    1.4.0

    License

    MIT

    Unpacked Size

    223 kB

    Total Files

    100

    Last publish

    Collaborators

    • spurreiter