# 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](https://github.com/komoot/photon#demo-server), [maintainer clarification](https://github.com/komoot/photon/discussions/598).

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](https://www.fossgis.de/arbeitsgruppen/osm-server/nutzungsbedingungen/), [Valhalla demo policy](https://github.com/valhalla/valhalla#demo-server). 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](https://operations.osmfoundation.org/policies/nominatim/).

## Forward search contract

```http
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](https://github.com/komoot/photon/blob/master/docs/api-v1.md).

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

```http
POST https://valhalla1.openstreetmap.de/route
Content-Type: application/json
```

```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](https://valhalla.github.io/valhalla/api/route/api-reference/), [polyline encoding](https://valhalla.github.io/valhalla/decoding/).

**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](https://github.com/valhalla/valhalla/blob/master/src/thor/triplegbuilder.cc), [maneuver helper source](https://github.com/valhalla/valhalla/blob/master/src/odin/enhancedtrippath.cc), [motorcycle costing source](https://github.com/valhalla/valhalla/blob/master/src/sif/motorcyclecost.cc).

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

```http
POST https://valhalla1.openstreetmap.de/height
Content-Type: application/json
```

```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](https://valhalla.github.io/valhalla/api/elevation/).

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](https://www.openstreetmap.org/copyright). 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.
