{"id":22486043,"url":"https://github.com/GIScience/openrouteservice-js","last_synced_at":"2025-08-02T19:30:36.340Z","repository":{"id":32375823,"uuid":"151106695","full_name":"GIScience/openrouteservice-js","owner":"GIScience","description":":pushpin: The JavaScript API to consume openrouteservice(s) painlessly!","archived":false,"fork":false,"pushed_at":"2025-04-30T18:04:13.000Z","size":1980,"stargazers_count":223,"open_issues_count":3,"forks_count":34,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-07-11T08:55:34.534Z","etag":null,"topics":["api","nodejs","npm","npm-package","openrouteservice","routing-engine","sdk"],"latest_commit_sha":null,"homepage":"https://openrouteservice.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.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,"zenodo":null}},"created_at":"2018-10-01T14:56:07.000Z","updated_at":"2025-07-08T16:40:35.000Z","dependencies_parsed_at":"2024-01-12T01:14:56.210Z","dependency_job_id":"f2f92996-ef22-4a3a-b4f6-f557e30b78ed","html_url":"https://github.com/GIScience/openrouteservice-js","commit_stats":{"total_commits":197,"total_committers":14,"mean_commits":"14.071428571428571","dds":0.6802030456852792,"last_synced_commit":"102c151f6bd7e4f2a082a8b647426b4f768de9f1"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/GIScience/openrouteservice-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/openrouteservice-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268440116,"owners_count":24250722,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api","nodejs","npm","npm-package","openrouteservice","routing-engine","sdk"],"created_at":"2024-12-06T17:13:46.661Z","updated_at":"2025-08-02T19:30:35.992Z","avatar_url":"https://github.com/GIScience.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# The JavaScript API to consume openrouteservice(s) painlessly!\n\n[![Build and test](https://github.com/GIScience/openrouteservice-js/actions/workflows/github-actions-build-and-test.yml/badge.svg)](https://github.com/GIScience/openrouteservice-js/actions/workflows/github-actions-build-and-test.yml)\n[![codecov](https://codecov.io/gh/GIScience/openrouteservice-js/branch/main/graph/badge.svg?token=WCLd69Jqbp)](https://codecov.io/gh/GIScience/openrouteservice-js)\n\nThis library lets you consume the openrouteservice API in *JavaScript* applications. It allows you to painlessly consume the following services:\n\n- Directions (routing)\n- Geocoding | Reverse Geocoding | Structured Geocoding (powered by Pelias)\n- Isochrones (accessibility)\n- Time-distance matrix\n- Snap (Get the closest point on road network)\n- POIs (points of interest)\n- Elevation (linestring or point)\n- Optimization\n\nSee the examples in the [examples folder](examples)\n\n*Note:* In order to use this client, you have to register for a token at [openrouteservice](https://openrouteservice.org). To understand the features of openrouteservice, please don't forget to read the docs. For visualization purposes on the map please use [openrouteservice maps](https://maps.openrouteservice.org).\n\n## Documentation\n\nThis library uses the ORS API for request validation. To understand the input of each API specifically, please check [API Playground](https://openrouteservice.org/dev/#/api-docs) that provides an interactive documentation.\n\n## Installation and Usage\n\nRequirements\n\n- git\n- nodeJS\n- *if not included in nodeJS:* npm\n\nInstall the library with npm:\n\n```shell\nnpm install openrouteservice-js --save\n```\n\n### Use es module import\n```js\nimport Openrouteservice from 'openrouteservice-js'\nlet orsDirections = new Openrouteservice.Directions({ api_key: \"XYZ\"});\n// ...\n```\n\n### Use requirejs\n```js\nconst Openrouteservice = require(\"openrouteservice-js\");\nlet orsDirections = new Openrouteservice.Directions({ api_key: \"XYZ\"});\n// ...\n```\n\n### Use the distribution file directly in html\n```html\n\u003cscript type=\"module\" src=\"../openrouteservice-js/dist/ors-js-client.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  let orsDirections = new Openrouteservice.Directions({ api_key: \"XYZ\"});\n  // ...\n\u003c/script\u003e\n```\n\n### Pair with local openrouteservice instance\n```js\n// Note: The API key is currently still passed as a parameter but not needed by the local instance\nimport Openrouteservice from 'openrouteservice-js'\nlet orsDirections = new Openrouteservice.Directions(\n  { host: \"http://localhost:8082/ors\" }\n);\n// ...\n```\n\n## Integrate the APIs in your application\n\n### Isochrones Example\n\n```javascript\n// Add your api_key here\nconst Isochrones = new Openrouteservice.Isochrones({ api_key: \"XYZ\"})\ntry {\n  let response = await Isochrones.calculate({\n    locations: [[8.690958, 49.404662], [8.687868, 49.390139]],\n    profile: 'driving-car',\n    range: [600],\n    units: 'km',\n    range_type: 'distance',\n    attributes: ['area'],\n    smoothing: 0.9,\n    avoidables: ['highways'],\n    avoid_polygons: {\n      type: 'Polygon',\n      coordinates: [\n        [\n          [8.683533668518066, 49.41987949639816],\n          [8.680272102355957, 49.41812070066643],\n          [8.683919906616211, 49.4132348262363],\n          [8.689756393432617, 49.41806486484901],\n          [8.683533668518066, 49.41987949639816]\n        ]\n      ]\n    },\n    area_units: 'km'\n  })\n  // Add your own result handling here\n  console.log(\"response: \", response)\n    \n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n```\n\n### Directions HGV example (browser)\n\u003e Note: Nested parameters from the options object are easier accessible like  `restrictions`, `avoidables`\n\u003e and `avoid_polygons` (cf. [API docs](https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/post)) \n```html\n\u003cscript\u003e\n  window.onload = async function() {\n    // Add your api_key here\n    let orsDirections = new Openrouteservice.Directions({ api_key: \"XYZ\"});\n\n    try {\n      let response = await orsDirections.calculate({\n        coordinates: [[8.690958, 49.404662], [8.687868, 49.390139]],\n        profile: 'driving-hgv',\n        restrictions: {\n          height: 10,\n          weight: 5\n        },\n        extra_info: ['waytype', 'steepness'],\n        avoidables: ['highways', 'tollways', 'ferries', 'fords'],\n        avoid_polygons: {\n          type: 'Polygon',\n          coordinates: [\n            [\n              [8.683533668518066, 49.41987949639816],\n              [8.680272102355957, 49.41812070066643],\n              [8.683919906616211, 49.4132348262363],\n              [8.689756393432617, 49.41806486484901],\n              [8.683533668518066, 49.41987949639816]\n            ]\n          ]\n        },\n        format: 'json'\n      })\n      // Add your own result handling here\n      console.log(\"response: \", response)\n\n    } catch (err) {\n      console.log(\"An error occurred: \" + err.status)\n      console.error(await err.response.json())\n    }\n  };\n\u003c/script\u003e\n```\n\n### Geocode examples\n\n```javascript\n// Add your api_key here\nconst Geocode = new Openrouteservice.Geocode({ api_key: \"XYZ\"})\n\ntry {\n  let response = await Geocode.geocode({\n    text: \"Heidelberg\",\n    boundary_circle: { lat_lng: [49.412388, 8.681247], radius: 50 },\n    boundary_bbox: [[49.260929, 8.40063], [49.504102, 8.941707]],\n    boundary_country: [\"DE\"]\n  })\n  // Add your own result handling here\n  console.log(\"response: \", response)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n\ntry {\n  let response_reverse = await Geocode.reverseGeocode({\n  point: { lat_lng: [49.412388, 8.681247], radius: 50 },\n  boundary_country: [\"DE\"]\n})\n  // Add your own result handling here\n  console.log(\"response: \", response_reverse)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n\n\ntry {\n  let response_structured = await Geocode.structuredGeocode({\n  locality: \"Heidelberg\"\n})\n  // Add your own result handling here\n  console.log(\"response: \", response_structured)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n```\n\n### Matrix example\n```javascript\n// Add your api_key here\nconst Matrix = new Openrouteservice.Matrix({ api_key: \"XYZ\"})\n\ntry {\n  let response = await Matrix.calculate({\n  locations: [[8.690958, 49.404662], [8.687868, 49.390139], [8.687868, 49.390133]],\n  profile: \"driving-car\",\n  sources: ['all'],\n  destinations: ['all']\n})\n  // Add your own result handling here\n  console.log(\"response: \", response)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n```\n\n### Elevation example\n```js\n// Add your api_key here\nconst Elevation = new Openrouteservice.Elevation({api_key: \"XYZ\"})\n\ntry {\n  let response = await Elevation.lineElevation({\n  format_in: 'geojson',\n  format_out: 'geojson',\n  geometry: {\n    coordinates: [[13.349762, 38.11295], [12.638397, 37.645772]],\n    type: 'LineString'\n  }\n})\n  // Add your own result handling here\n  console.log(\"response: \", response)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n```\n\n### Snap example\n\n```js\n// Add your api_key here\nconst Snap = new Openrouteservice.Snap({api_key: \"XYZ\"})\n\ntry {\n  let response = await Snap.calculate({\n    locations: [[8.681495,49.51461],[8.686507,49.41943]],\n    radius: 300,\n    profile: 'driving-car',\n    format: 'json'\n  })\n  // Add your own result handling here\n  console.log(\"response: \", response)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n```\n\n### Optimization example\nOr consume Optimization API to solve [vehicle routing problems](https://en.wikipedia.org/wiki/Vehicle_routing_problem)\n\n```javascript\n// Add your api_key here\nlet Optimization = new openrouteservice.Optimization({api_key: \"XYZ\"});\n\ntry {\n  let response = await Optimization.optimize({\n  jobs: [\n    {\n      id: 1,\n      service: 300,\n      amount: [1],\n      location: [2.03655, 48.61128],\n      skills: [1]\n    },\n    {\n      id: 2,\n      service: 300,\n      amount: [1],\n      location: [2.03655, 48.61128],\n      skills: [2]\n    },\n  ],\n  vehicles: [\n    {\n      id: 1,\n      profile: 'driving-car',\n      start: [2.35044, 48.71764],\n      end: [2.35044, 48.71764],\n      capacity: [3],\n      skills: [1, 2],\n    }\n  ],\n})\n  // Add your own result handling here\n  console.log(\"response: \", response)\n\n} catch (err) {\n  console.log(\"An error occurred: \" + err.status)\n  console.error(await err.response.json())\n}\n```\n\n## Development Setup\n\nClone the openrouteservice-js repository from GitHub into a development environment of your choice.\n\n```shell\ngit clone https://github.com/GIScience/openrouteservice-js.git\ncd openrouteservice-js\n\n# Install the dependencies\nnpm install\n\n# Make your openrouteservice API key available for tests, examples and dev_app\nsh setup.sh \u003cyour-api-key\u003e\n```\n\nStart the dev_app for debugging when working with source files:\n```shell\n# runs the app at http://localhost:5173\nvite\n```\n\nNow you can either use the devtools of your browser to set breakpoints (e.g. in `OrsGeocode`)\nor create a `JavaScript Debug` configuration to debug with WebStorm:\n![debug_config](https://user-images.githubusercontent.com/23240110/195876234-4a0ad923-1c5c-4cfe-976a-d39dd23a50d8.png)\n\nRun the config in debug mode to open the Chrome browser and reload the page after changes for them to take\neffect immediately.\n\n## Running Tests\n\nTo run specific unit test files in `src/__tests__` on demand during development, run\n```shell\nnpm run test:e2e\n```\nChoose one of your installed browsers in the cypress UI you want to test in and select the test file you want to run.\n\nComponent tests for the web app can be run by switching to component testing.\n\nTo run tests without ui use the npm scripts ending with `:ci` e.g. for unit, component and e2e tests:\n```shell\nnpm run test:ci\n```\n## Commits and versioning\n\n- This app uses the `commitizen` plugin to generate standardized commit types/messages. After applying any change in a feature branch, use `git add .` and then `npm run commit` (instead of `git commit ...`)\n- The plugin `standard-version` is used to generate changelog entries, version tag and to bump the app version in package.json.\n\nDeployment flow:\n\n- Apply the changes in a feature branch and test it locally\n- Once the feature is ready, merge it to `develop`, deploy it to the testing environment\n- Checkout in `main`, merge from develop and use `npm run release` to generate a release. This will generate a new release commit as well as a git tag and an entry in [CHANGELOG.md](CHANGELOG.md).\n\n*For more details about `commitizen` and `standard-version` see [this article](https://medium.com/tunaiku-tech/automate-javascript-project-versioning-with-commitizen-and-standard-version-6a967afae7)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGIScience%2Fopenrouteservice-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGIScience%2Fopenrouteservice-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGIScience%2Fopenrouteservice-js/lists"}