{"id":19381795,"url":"https://github.com/spurreiter/geocoder","last_synced_at":"2025-04-23T20:32:02.112Z","repository":{"id":44116054,"uuid":"370482170","full_name":"spurreiter/geocoder","owner":"spurreiter","description":"Node geocoding library, google maps, bing maps, mapquest, mapbox, here maps, arcgis, ...","archived":false,"fork":false,"pushed_at":"2024-11-04T20:17:16.000Z","size":238,"stargazers_count":5,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-14T21:18:19.395Z","etag":null,"topics":["arcgis-js-api","bing-maps-api","forward-geocoding","geocoder","geocoding","geocoding-api","geocodio","google-maps-api","here-maps-api","ipstack-api","locationiq-api","mapbox-api","mapquest-api","nominatim-api","reverse-geocoding"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spurreiter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-24T20:53:52.000Z","updated_at":"2024-12-21T17:48:13.000Z","dependencies_parsed_at":"2024-07-13T12:05:57.651Z","dependency_job_id":null,"html_url":"https://github.com/spurreiter/geocoder","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spurreiter%2Fgeocoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spurreiter%2Fgeocoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spurreiter%2Fgeocoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spurreiter%2Fgeocoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spurreiter","download_url":"https://codeload.github.com/spurreiter/geocoder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250509735,"owners_count":21442486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arcgis-js-api","bing-maps-api","forward-geocoding","geocoder","geocoding","geocoding-api","geocodio","google-maps-api","here-maps-api","ipstack-api","locationiq-api","mapbox-api","mapquest-api","nominatim-api","reverse-geocoding"],"created_at":"2024-11-10T09:18:24.847Z","updated_at":"2025-04-23T20:32:01.473Z","avatar_url":"https://github.com/spurreiter.png","language":"JavaScript","readme":"[![CI](https://github.com/spurreiter/geocoder/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/spurreiter/geocoder/actions/workflows/ci.yml)\n[![npm version](https://badge.fury.io/js/@spurreiter%2Fgeocoder.svg)](https://www.npmjs.com/package/@spurreiter/geocoder)\n[![Downloads per month](https://img.shields.io/npm/dm/@spurreiter/geocoder)](https://www.npmjs.com/package/@spurreiter/geocoder)\n\n# geocoder  \n\nThis project is derived from\n[node-geocoder](https://github.com/nchaulet/node-geocoder) with focus on modern\ncode with esm modules.\n\nFeatures:\n- multiple providers\n- similar results for all providers\n- modern code based on esm modules and native Promises with async/ await\n- Typescript types\n- http(s) agent by default for reusing tcp connections\n- fetch based http adapter with timeout\n- cascade providers and stop on first successful result\n- combine search results from multiple providers\n- configurable circuit breaker which stops calling geocoder e.g. if request\n  limit is exhausted.\n- extensive test-suite with examples for getting started\n- GeoJSON, GPX formatters\n\n## supported providers\n\n| Provider                                                                                        | forward | reverse | ip | Notes                                                                                                                                                             |\n| ----------------------------------------------------------------------------------------------- | :-----: | :-----: | :-: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [ArcGisGeocoder](https://developers.arcgis.com/documentation/mapping-apis-and-services/search/) |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [BingMapsGeocoder](https://docs.microsoft.com/en-us/bingmaps/rest-services/locations)           |    ✅    |    ✅    | ❌  | results are in English only                                                                                                                                       |\n| [GoogleGeocoder](https://developers.google.com/maps/documentation/geocoding/overview)           |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [GeocodioGeocoder](https://www.geocod.io/docs/)                                                 |    ✅    |    ✅    | ❌  | results are in English only; Country must be part of query, otherwise fallback to US; [Only US and major cities in CA supported](https://www.geocod.io/coverage/) |\n| [HereGeocoder](https://developer.here.com/)                                                     |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [IpStackGeocoder](https://ipstack.com/)                                                         |    ❌    |    ❌    | ✅  |                                                                                                                                                                   |\n| [LocationIqGeocoder](https://locationiq.com/docs)                                               |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [GeoLite2Geocoder](https://dev.maxmind.com/geoip/geoip2/geolite2/)                              |    ❌    |    ❌    | ✅  | Local GeoLite2 provider or MaxMind API. Output as of [@maxmind/geoip2-node](https://www.npmjs.com/package/@maxmind/geoip2-node)                                   |\n| [MapBoxGeocoder](https://docs.mapbox.com/)                                                      |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [MapQuestGeocoder](https://developer.mapquest.com/documentation/geocoding-api)                  |    ✅    |    ✅    | ❌  | open-data and licensed versions are supported                                                                                                                     |\n| [OpenCageGeocoder](https://opencagedata.com/)                                                   |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [OpendataFranceGeocoder](https://geo.api.gouv.fr/adresse)                                       |    ✅    |    ✅    | ❌  | France only                                                                                                                                                       |\n| [OpenMapQuest](https://developer.mapquest.com/documentation/open/nominatim-search/)             |    ✅    |    ✅    | ❌  | Search Results based on OSM                                                                                                                                       |\n| [OsmGeocoder](https://nominatim.org/release-docs/develop/)                                      |    ✅    |    ✅    | ❌  | Searches nominatim.org                                                                                                                                            |\n| [PeliasGeocoder](https://github.com/pelias/documentation/blob/master/README.md)                 |    ✅    |    ✅    | ❌  | Local or [Geocode.earth](https://geocode.earth/docs)                                                                                                              |\n| [PickpointGeocoder](https://pickpoint.io/api-reference)                                         |    ✅    |    ✅    | ❌  | Search Results based on OSM                                                                                                                                       |\n| [TomTomGeocoder](https://developer.tomtom.com/)                                                 |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n| [YandexGeocoder](https://yandex.com/dev/maps/geocoder/)                                         |    ✅    |    ✅    | ❌  |                                                                                                                                                                   |\n\n## usage\n\n### forward geocoding\n\n```js\nimport { fetchAdapter, OsmGeocoder } from '@spurreiter/geocoder'\n\nconst adapter = fetchAdapter()\nconst geocoder = new OsmGeocoder(adapter, \n  { language: 'en', limit: 5, referer: 'https://mysite' })\n\nconst results = await geocoder.forward('135 pilkington avenue, birmingham')\n// [\n//   {\n//     formattedAddress: '135, Pilkington Avenue, Maney, Sutton Coldfield, Wylde Green, Birmingham, West Midlands Combined Authority, West Midlands, England, B72 1LH, United Kingdom',\n//     latitude: 52.5487921,\n//     longitude: -1.8164308339635031,\n//     country: 'United Kingdom',\n//     countryCode: 'GB',\n//     state: 'England',\n//     county: 'West Midlands Combined Authority',\n//     city: 'Birmingham',\n//     zipcode: 'B72 1LH',\n//     district: 'West Midlands',\n//     streetName: 'Pilkington Avenue',\n//     streetNumber: '135',\n//     neighbourhood: undefined,\n//     extra: {\n//       id: 90394480,\n//       confidence: 0.411,\n//       bbox: [ -1.816513, 52.5487473, -1.8163464, 52.5488481 ]\n//     }\n//   }\n// ]\n```\n\n### reverse geocoding\n\n```js\nconst results = await geocoder.reverse({ lat: 40.714232, lng: -73.9612889 })\n// [\n//   {\n//     formattedAddress: '279, Bedford Avenue, Williamsburg, Brooklyn, Kings County, New York, 11211, United States',\n//     latitude: 40.714205,\n//     longitude: -73.96131519274765,\n//     country: 'United States',\n//     countryCode: 'US',\n//     state: 'New York',\n//     county: undefined,\n//     city: 'New York',\n//     zipcode: '11211',\n//     district: undefined,\n//     streetName: 'Bedford Avenue',\n//     streetNumber: '279',\n//     neighbourhood: undefined,\n//     extra: {\n//       id: 279767984,\n//       confidence: 0,\n//       bbox: [ -73.9613744, 40.7141617, -73.961256, 40.7142482 ]\n//     }\n//   }\n// ]\n```\n\n### cascade\n\nAllows to sequentially ask various geocoders for results. Successful results\nfrom the first geocoder are returned.\n\nWorks with forward and reverse geocoding.\n\n```js\nimport { Cascade, fetchAdapter, HereGeocoder, OsmGeocoder } from '@spurreiter/geocoder'\n\nconst language = \"es\"\nconst geocoders = [\n  new HereGeocoder(adapter, { apiKey: 'your-api-key', language }),\n  new OsmGeocoder(adapter, { language, referer: 'https://mysite' })\n]\nconst cascade = new Cascade(geocoders)\n\nconst results = await cascade.forward('135 pilkington avenue, birmingham')\n\n// results contains data from 1st geocoder which responds without error.\n```\n\n### combine\n\nCombine results from various geocoders into one result set.\n\nWorks with forward and reverse geocoding.\n\n```js\nimport { Combine, fetchAdapter, HereGeocoder, OsmGeocoder } from '@spurreiter/geocoder'\n\nconst geocoders = [\n  new HereGeocoder(adapter, { apiKey: 'your-api-key' }),\n  new OsmGeocoder(adapter, { referer: 'https://mysite' })\n]\nconst combine = new Combine(geocoders)\n\nconst results = await combine.forward(\n    { address: '135 pilkington avenue, birmingham', language: 'es' })\n\n// results contains data from all reachable geocoders.\n```\n\n## formatters\n\nFormatters allow to format the geocoder result object to various formats like\ngeoJson or gpx.\n\n### geoJsonFormatter\n\nThe output of the GeoJSON formatter is according to\n[RFC-7946](https://datatracker.ietf.org/doc/html/rfc7946) and\n[geocodejson-spec](https://github.com/geocoders/geocodejson-spec).\n\n```js\nimport { geoJsonFormatter } from '@spurreiter/geocoder'\n\nconst query = '135 pilkington avenue, birmingham'\nconst results = await geocoder.forward(query)\n\nconst geoJson = geoJsonFormatter(results, {query})\n// {\n//   type: 'FeatureCollection',\n//   geocoding: {\n//     version: '0.1.0',\n//     license: null,\n//     attribution: null,\n//     query: '135 pilkington avenue, birmingham'\n//   },\n//   features: [{...}, ...]\n// }\n```\n\n### gpxFormatter\n\n```js\nimport { gpxFormatter } from '@spurreiter/geocoder'\n\nconst query = '135 pilkington avenue, birmingham'\nconst results = await geocoder.forward(query)\n\nconst gpx = gpxFormatter(results)\n// \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n// \u003cgpx 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\"\u003e\n// \u003cwpt lat=\"52.5487921\" lon=\"-1.8164308339635031\"\u003e\u003cname\u003e135, Pilkington Avenue, Maney, Sutton Coldfield, Wylde Green, Birmingham, West Midlands Combined Authority, West Midlands, England, B72 1LH, United Kingdom\u003c/name\u003e\u003c/wpt\u003e\n// \u003c/gpx\u003e\n```\n\n## contributing\n\nIf you are missing a provider, which should be part of this project, please\nconsider forking this project and filing a pull-request.\n\n## license\n\n[MIT licensed](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspurreiter%2Fgeocoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspurreiter%2Fgeocoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspurreiter%2Fgeocoder/lists"}