Dokumen ini mencatat tahap implementasi pada versi yang disebutkan. Untuk status akhir seluruh fitur, baca audit implementasi.
Routing providers for the private Android OMOX build
Checked 2026-09-19 for issue #26. This is an implementation recommendation for one owner's development build, not a production service commitment. It supplements online-routing-research.md; provider endpoints must remain replaceable.
Selection and operating boundaries
Use Photon for deliberate free-text destination searches and FOSSGIS Valhalla for motorcycle routes and elevation. These public endpoints required no account, payment or API key in the small probes below. Neither supplies a contractual SLA for OMOX.
Photon's operator welcomes reasonable project usage, may throttle or ban extensive usage, and can change the service without notice. No numeric allowance is published in its README. An operator answer specifically discourages sending business clients to the demo. For our private build, impose one submitted request per second maximum, cache repeated searches, and provide an explicit retry after errors rather than a request loop. These numeric/cache choices are OMOX policy, not a Photon quota. Photon README, maintainer clarification.
FOSSGIS routing terms specify at most one request per second and no availability guarantee. Apply a single queue across route and height requests, spaced at least 1.1 seconds, cache successful responses, honour 429/Retry-After and never fan out charging alternatives concurrently. Identify requests using User-Agent: OMOX-Android/<version> and X-Client-Id: omox-private-android. Before publishing to other users, resolve a production provider/self-hosting decision; Valhalla's maintainers request notification via GitHub Discussions for published clients. No notification has been sent. FOSSGIS terms, Valhalla demo policy. The terms were available through the search index; direct browser access encountered an anti-bot page during this check.
Do not use public nominatim.openstreetmap.org as an implicit fallback. Its policy restricts generic geocoding generated/offered through vibe-coding platforms and requires an informed developer decision. Photon using Nominatim-derived data does not mean OMOX calls that public API. Nominatim policy.
Forward search contract
GET https://photon.komoot.io/api/?q=Telomoyo&countrycode=ID&limit=5
URL-encode user input. Optional lat/lon bias results toward the chosen origin; this is not a geographic restriction. countrycode=ID restricts country. bbox is minLon,minLat,maxLon,maxLat. Parse features[], Point geometry.coordinates as longitude, latitude, and optional properties name, street, city, state, countrycode, osm_type, osm_id. Use OSM type plus ID as identity when present. A successful response can contain no results. Photon API contract.
Live probe: HTTP 200, Access-Control-Allow-Origin: *, five results. The first “Telomoyo” was in Sumatra, followed by two Gunung Telomoyo points in Central Java (about 110.400, -7.361). Therefore never automatically choose the first result: show locality and point preview, then require selection. A summit coordinate does not establish a motor-accessible entrance; support moving the destination pin or choosing the entrance instead.
Motorcycle route contract
POST https://valhalla1.openstreetmap.de/route
Content-Type: application/json
{
"locations": [
{"lat": -6.981, "lon": 109.14, "type": "break"},
{"lat": -6.895, "lon": 109.379, "type": "break"}
],
"costing": "motorcycle",
"costing_options": {
"motorcycle": {"use_highways": 1, "use_tolls": 0, "use_trails": 0}
},
"units": "kilometers",
"shape_format": "polyline6"
}
Parse trip.status, summary length (km)/time (seconds), ordered legs[], six-decimal encoded shape, maneuvers with shape indices, and warnings. OMOX chooses use_highways:1 to avoid penalizing ordinary main-road travel; motorway/toll flags are rejected separately after routing. Preference values zero are not hard prohibitions. Experimental exclude_highways/exclude_tolls need server support and may produce warnings; do not treat sending them as proof of exclusion. Motorcycle is a documented beta costing. Motor-scooter uses different access/speed assumptions and must not silently substitute for a road motorcycle. Route API, polyline encoding.
Restriction interpretation: current upstream TripLegBuilder sets summary has_highway when an edge is RoadClass::kMotorway, not for all trunk roads. EnhancedTripLeg_Edge::IsHighway() also checks motorway and excludes ramps/turn channels. Motorcycle costing uses kMotorcycleAccess, checks access and turn restrictions and evaluates restrictions. Trip-leg source, maneuver helper source, motorcycle costing source.
OMOX should reject motorway/toll candidates for this private Indonesian route policy, but must not reject ordinary trunk/Pantura solely because its class is trunk. Missing restriction flags are unknown, not false. These source semantics explain flags, not proof that the hosted deployment uses that exact commit or that all OSM access tags match current ground rules. Keep explicit warnings and do not claim legal/physical access verification.
The initial comparison probe used use_highways:0 at these approximate public citypoints: HTTP 200, status 0, 58.737 km, 6,664.673 seconds, no warnings, toll/highway/ferry false. Straight-line separation is about 28 km: the detour needs route review and should not be advertised as an optimal Pantura route. Connectivity/schema were verified; route quality was not. Do not replace a failed motor route with a car route.
Elevation and Android transport
POST https://valhalla1.openstreetmap.de/height
Content-Type: application/json
{"shape":[{"lat":-6.981,"lon":109.14},{"lat":-6.895,"lon":109.379}],"range":true}
Live response: HTTP 200, range_height: [[0,45],[28092,12]]. Distances/heights are metres. For actual profiles submit samples from the returned road geometry, not a straight line between stops. Missing heights are null. Encoded geometry with shape_format: polyline6 and optional resample_distance is documented; the above explicit-point form was probed. Elevation API.
All three successful probes returned CORS * for an appassets origin. That proves simple response headers only, not support for every browser preflight/custom header. Prefer native Android HTTPS networking behind the existing narrowly scoped app bridge: INTERNET permission, background I/O, deadlines, cancellation/stale-result protection and bounded response sizes; browser CORS does not govern native requests. Do not weaken WebView origin restrictions or enable arbitrary URL fetching. None of these endpoints requires a PC backend.
Display © OpenStreetMap contributors linking to the OSM copyright page and provider names/links. OSM database licensing is ODbL; software licences and a free endpoint do not erase data attribution obligations. OSM copyright and licence. Search terms and route/elevation coordinates leave the device: disclose the providers in the app's data-use information, and send no account credentials or unrelated trip logs.
Acceptance implications
- Demo a typed Indonesian place search, ambiguous-result selection, motor route, maneuver preview and actual-road elevation on TECNO without USB reverse/backend PC.
- Exercise empty search, timeout/429, unsupported or malformed route, missing elevation and stale request cancellation without a crash or misleading successful plan.
- Unit-test longitude/latitude order, polyline6, distance units and motorway-versus-trunk handling; retain recorded fixtures so tests do not hammer demo servers.
- Provider travel time and terrain are inputs. They do not validate OMOX battery estimates, current road closures or charging availability.