{"id":43083148,"url":"https://github.com/mapzen/on-the-road_android","last_synced_at":"2026-01-31T15:04:10.124Z","repository":{"id":15258299,"uuid":"17987394","full_name":"mapzen/on-the-road_android","owner":"mapzen","description":"Android client for the Valhalla routing service plus mobile nav utilities","archived":false,"fork":false,"pushed_at":"2020-07-07T03:19:21.000Z","size":2049,"stargazers_count":50,"open_issues_count":9,"forks_count":24,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-08-21T04:36:47.061Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"schnee/tweetgeister","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapzen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-21T17:04:54.000Z","updated_at":"2025-01-10T13:12:50.000Z","dependencies_parsed_at":"2022-08-03T08:00:25.649Z","dependency_job_id":null,"html_url":"https://github.com/mapzen/on-the-road_android","commit_stats":null,"previous_names":["mapzen/on-the-road"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/mapzen/on-the-road_android","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapzen%2Fon-the-road_android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapzen%2Fon-the-road_android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapzen%2Fon-the-road_android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapzen%2Fon-the-road_android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapzen","download_url":"https://codeload.github.com/mapzen/on-the-road_android/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapzen%2Fon-the-road_android/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28946088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T14:26:55.697Z","status":"ssl_error","status_checked_at":"2026-01-31T14:26:52.545Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-31T15:04:10.004Z","updated_at":"2026-01-31T15:04:10.118Z","avatar_url":"https://github.com/mapzen.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# On The Road\n\nAndroid client for the Valhalla routing service plus mobile nav tools\n\n[![CircleCI](https://circleci.com/gh/mapzen/on-the-road_android.svg?style=svg\u0026circle-token=654423209f8f63b35432f450450069ce44bb5729)](https://circleci.com/gh/mapzen/on-the-road_android)\n\nThis library has two main responsibilities, it acts as an Android client for [Mapzen Turn-by-Turn][2] (powered by [Valhalla][5]) and it handles client-side location correction, specifically snapping the client’s location along road.\n\nWe accept feature requests as suggestions or patches.\n\n## Usage\n\n#### The Router\n\nTo construct a Route object from two or more locations you obtain a Router object and specify your options.\n\n```java\nnew ValhallaRouter()\n\t.setDriving() // Driving is default (setBiking, setWalking also available)\n\t.setLocation(new double[]{lat, lng}) // required\n\t.setLocation(new double[]{lat, lng}) // required\n\t.setZoomLevel(17) // defaults to 17\n\t.setCallback(new Callback() {\n\t\t@Override\n\t\tpublic void success(Route route) {\n\t\t\t// do stuff\n\t\t}\n\n\t\t@Override\n\t\tpublic void failure(int statusCode) {\n\t\t\t// do stuff\n\t\t}\n\t}).fetch(); // this executes the http call in a thread and calls methods on the callback\n```\n\n#### Route\n\nWhen Route is found between your two locations your Callback::success method will be called with the Route instance as argument.\nFrom the Route instance you can get attributes such as time and distance. Route also provides the route geometry and instructions.\n\n```java\nint totalDistance = route.getTotalDistance(); // see DistanceFormatter for options\nint totalTime = route.getTotalTime();\nList\u003cInstructions\u003e instructions = route.getRouteInstructions();\nList\u003cNode\u003e nodes = route.getGeometry();\n```\n\n#### Instruction\n\nRoute has a Instruction collection which represents an actionable point along the route this will have\ncoordinates of the action that needs taken plus some other useful properties.\n\n```java\n// quick sample of available methods\nInstruction instruction = route.getRouteInstructions().get(0);\ninstruction.getTurnInstruction();\ninstruction.getHumanTurnInstruction();\ninstruction.getDistance();\ninstruction.getDirection();\ninstruction.getBearing();\n\n// or get a formatted instruction\ninstruction.getFullInstruction();\n```\n\nThe best way to learn the api while documentation is scarce is to look at the tests. We aim to keep thorough coverage for\nincreased stability and self documentation.\n\n#### Client side magic\n\nDevice GPS accuracy is almost never perfect, especially in cities. Being off by several feet becomes a very apparent problem in routing. Your user could be driving their car in a straight line down the street but your app could be displaying them 20 feet off the road. To combat this we mathematically manipulate the\nlocation we receive from the location service and snap it to the road. You can use our project [Lost][3] if you would like an open source alternative to the `FusedLocationProvider`.\n\nThe best way to describe the problem is by looking at two illustrations:\n\nThis is what happens before correction, you'll have a road (- and \\)  and your location the (x);\n\n```\nx    x\n  x\n             x\n---------------- x\n   x            \\\n        x     x  \\\n                  \\    x\n                   \\  x\n```\n\nWhen you are showing a location on a map and you have high-lighted a route but the location consistently\nfails to persist on the route it might be confusing for the user. Ideally the user will see the location\nrepresented along the route. To accomplish this we fix the location by snapping it on the road with corrected\nlocation (o).\n```\n\nx    x\n  x\n             x\no-oo-o--o-o--o-- x\n   x            o\n        x     x  o\n                  o    x\n                   o  x\n```\n\nThis is done by finding the intersection of two beams, one the beginning of the route leg and the other the location with +90 or -90\nbearing compared to the bearing of the route leg. The math formulas we use were translated from [Chris Veness scripts][4]\nhis examples are written in javascript and we translated the formulas we needed to java.\n\n```java\n\n// if this returns null it means we are probably\n// off course and it's time to obtain new route from current position\ndouble[] onTheRoad = route.snapToRoute(new double[] { lat, lng });\n\n```\n\n#### To test this and reply route scenarios we have built a simple web app that communicates with the library\n\nsee https://github.com/mapzen/on-the-road_web-tester\n\n\n## Install\n\n#### Download AAR\n\nDownload the [latest AAR][1].\n\n#### Maven\n\nInclude dependency using Maven.\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.mapzen\u003c/groupId\u003e\n  \u003cartifactId\u003eon-the-road\u003c/artifactId\u003e\n  \u003cversion\u003e1.3.2\u003c/version\u003e\n  \u003ctype\u003eaar\u003c/type\u003e\n\u003c/dependency\u003e\n```\n\n#### Gradle\n\nInclude dependency using Gradle.\n\n```groovy\ncompile 'com.mapzen:on-the-road:1.3.2'\n```\n\n## Sample app\nThis project includes a sample app which can be used to easily test the library.\n\n#### API key\nTo run the app you will need to sign up and [obtain an API key](https://mapzen.com/dashboard). After you have your API key, create a `gradle.properties` file in `~/.gradle/gradle.properties` and add your api key `apiKey=YOUR_API_KEY`.\n\nInstall the app from your IDE or from the command line with `./gradlew :sample:installDebug`\n\n\n[1]: http://search.maven.org/remotecontent?filepath=com/mapzen/on-the-road/1.2.1/on-the-road-1.2.1.aar\n[2]: https://mapzen.com/projects/valhalla/\n[3]: https://github.com/mapzen/lost\n[4]: http://www.movable-type.co.uk/scripts/latlong.html\n[5]: https://github.com/valhalla\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapzen%2Fon-the-road_android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapzen%2Fon-the-road_android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapzen%2Fon-the-road_android/lists"}