Skip to content

Commit 98eaeb3

Browse files
TheCryptoDonkeyTheCryptoDonkey
committed
docs: add missing computeRoute, VenueType values, and strategy option
RoutingEngine.computeRoute() was missing from docs, 9 VenueType values were undocumented, and the strategy option and metadata fields were not mentioned. Added RouteGeometry/RouteLeg types and engine comparison.
1 parent 2fef404 commit 98eaeb3

3 files changed

Lines changed: 111 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -94,12 +94,12 @@ for (const s of suggestions) {
9494

9595
## Engine Support
9696

97-
| Engine | Isochrone | Route Matrix | Auth |
98-
|--------|:---------:|:------------:|------|
99-
| Valhalla | Yes | Yes | None (self-hosted) |
100-
| OpenRouteService | Yes | Yes | API key |
101-
| GraphHopper | Yes | Yes | API key (optional) |
102-
| OSRM | No | Yes | None (self-hosted) |
97+
| Engine | Isochrone | Route Matrix | Route | Auth |
98+
|--------|:---------:|:------------:|:-----:|------|
99+
| Valhalla | Yes | Yes | Yes | None (self-hosted) |
100+
| OpenRouteService | Yes | Yes | No | API key |
101+
| GraphHopper | Yes | Yes | No | API key (optional) |
102+
| OSRM | No | Yes | No | None (self-hosted) |
103103

104104
OSRM does not support isochrone computation — use it only when you need a fast route matrix and are supplying your own intersection polygon.
105105

@@ -154,14 +154,17 @@ OSRM does not support isochrone computation — use it only when you need a fast
154154
| `GeoJSONPolygon` | Standard GeoJSON polygon geometry |
155155
| `TransportMode` | `'drive' \| 'cycle' \| 'walk' \| 'public_transit'` |
156156
| `FairnessStrategy` | `'min_max' \| 'min_total' \| 'min_variance'` |
157-
| `VenueType` | `'park' \| 'cafe' \| 'restaurant' \| 'service_station' \| 'library' \| 'pub' \| 'playground' \| 'community_centre' \| string` |
158-
| `RoutingEngine` | Interface — `computeIsochrone` + `computeRouteMatrix` |
157+
| `VenueType` | `'park' \| 'cafe' \| 'restaurant' \| 'service_station' \| 'library' \| 'pub' \| 'playground' \| 'community_centre' \| 'bar' \| 'fast_food' \| 'garden' \| 'theatre' \| 'arts_centre' \| 'fitness_centre' \| 'sports_centre' \| 'escape_game' \| 'swimming_pool' \| string` |
158+
| `RoutingEngine` | Interface — `computeIsochrone` + `computeRouteMatrix` + `computeRoute` |
159159
| `Isochrone` | `{ origin, mode, timeMinutes, polygon }` |
160160
| `MatrixEntry` | `{ originIndex, destinationIndex, durationMinutes, distanceKm }` |
161161
| `RouteMatrix` | `{ origins, destinations, entries }` |
162162
| `Venue` | `{ name, lat, lon, venueType, osmId? }` |
163-
| `RendezvousOptions` | `{ participants, mode, maxTimeMinutes, venueTypes, fairness?, limit? }` |
164-
| `RendezvousSuggestion` | `{ venue, travelTimes, fairnessScore }` |
163+
| `RendezvousOptions` | `{ participants, mode, maxTimeMinutes, venueTypes, fairness?, limit?, strategy? }` |
164+
| `RendezvousSuggestion` | `{ venue, travelTimes, fairnessScore, metadata? }` |
165+
| `RouteGeometry` | `{ origin, destination, mode, durationMinutes, distanceKm, geometry, legs? }` |
166+
| `RouteLeg` | `{ instruction, distanceKm, durationMinutes, type?, streetNames?, ... }` |
167+
| `GeoJSONLineString` | `{ type: 'LineString', coordinates: number[][] }` |
165168
| `BBox` | `{ minLon, minLat, maxLon, maxLat }` |
166169
| `Coordinate` | `{ lat, lon }` |
167170

@@ -196,7 +199,7 @@ If the isochrones do not overlap, `findRendezvous` returns an empty array. If no
196199
## Implementing a Custom Engine
197200
198201
```typescript
199-
import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix } from 'rendezvous-kit'
202+
import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix, RouteGeometry } from 'rendezvous-kit'
200203

201204
class MyEngine implements RoutingEngine {
202205
readonly name = 'MyEngine'
@@ -208,6 +211,10 @@ class MyEngine implements RoutingEngine {
208211
async computeRouteMatrix(origins: LatLon[], destinations: LatLon[], mode: TransportMode): Promise<RouteMatrix> {
209212
// call your API and return a RouteMatrix
210213
}
214+
215+
async computeRoute(origin: LatLon, destination: LatLon, mode: TransportMode): Promise<RouteGeometry> {
216+
// call your API and return a RouteGeometry with optional turn-by-turn legs
217+
}
211218
}
212219
```
213220

‎llms-full.txt‎

Lines changed: 86 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,15 @@ type VenueType =
6363
| 'pub'
6464
| 'playground'
6565
| 'community_centre'
66+
| 'bar'
67+
| 'fast_food'
68+
| 'garden'
69+
| 'theatre'
70+
| 'arts_centre'
71+
| 'fitness_centre'
72+
| 'sports_centre'
73+
| 'escape_game'
74+
| 'swimming_pool'
6675
| string
6776

6877
/** Result of an isochrone computation. */
@@ -97,6 +106,43 @@ interface Venue {
97106
osmId?: string // e.g. 'node/123456'
98107
}
99108

109+
/** GeoJSON LineString geometry. */
110+
interface GeoJSONLineString {
111+
type: 'LineString'
112+
coordinates: number[][]
113+
}
114+
115+
/** A single manoeuvre in a route. */
116+
interface RouteLeg {
117+
instruction: string
118+
distanceKm: number
119+
durationMinutes: number
120+
type?: number // Valhalla manoeuvre type (0-38)
121+
streetNames?: string[]
122+
beginStreetNames?: string[]
123+
verbalInstruction?: string
124+
toll?: boolean
125+
highway?: boolean
126+
ferry?: boolean
127+
rough?: boolean
128+
gate?: boolean
129+
bearingBefore?: number
130+
bearingAfter?: number
131+
beginShapeIndex?: number
132+
endShapeIndex?: number
133+
}
134+
135+
/** Result of a single route computation. */
136+
interface RouteGeometry {
137+
origin: LatLon
138+
destination: LatLon
139+
mode: TransportMode
140+
durationMinutes: number
141+
distanceKm: number
142+
geometry: GeoJSONLineString
143+
legs?: RouteLeg[]
144+
}
145+
100146
/** Options for rendezvous calculation. */
101147
interface RendezvousOptions {
102148
participants: LatLon[] // at least 2 required
@@ -105,20 +151,23 @@ interface RendezvousOptions {
105151
venueTypes: VenueType[]
106152
fairness?: FairnessStrategy // default: 'min_max'
107153
limit?: number // max suggestions to return, default: 5
154+
strategy?: 'auto' | 'hull' | 'isochrone' // pipeline strategy, default: 'auto'
108155
}
109156

110157
/** A ranked rendezvous suggestion. */
111158
interface RendezvousSuggestion {
112159
venue: Venue
113160
travelTimes: Record<string, number> // keyed by participant label or 'participant_N'
114161
fairnessScore: number // lower is better
162+
metadata?: { strategy: 'hull' | 'isochrone' } // which pipeline was used
115163
}
116164

117165
/** Engine-agnostic routing interface. Implement this to add a custom engine. */
118166
interface RoutingEngine {
119167
readonly name: string
120168
computeIsochrone(origin: LatLon, mode: TransportMode, timeMinutes: number): Promise<Isochrone>
121169
computeRouteMatrix(origins: LatLon[], destinations: LatLon[], mode: TransportMode): Promise<RouteMatrix>
170+
computeRoute(origin: LatLon, destination: LatLon, mode: TransportMode): Promise<RouteGeometry>
122171
}
123172

124173
/** Bounding box (from rendezvous-kit/geo). */
@@ -413,6 +462,15 @@ Built-in `VenueType` to Overpass tag mapping:
413462
| `pub` | `amenity=pub` |
414463
| `playground` | `leisure=playground` |
415464
| `community_centre` | `amenity=community_centre` |
465+
| `bar` | `amenity=bar` |
466+
| `fast_food` | `amenity=fast_food` |
467+
| `garden` | `leisure=garden` |
468+
| `theatre` | `amenity=theatre` |
469+
| `arts_centre` | `amenity=arts_centre` |
470+
| `fitness_centre` | `leisure=fitness_centre` |
471+
| `sports_centre` | `leisure=sports_centre` |
472+
| `escape_game` | `leisure=escape_game` |
473+
| `swimming_pool` | `leisure=swimming_pool` |
416474

417475
Unknown strings are passed through as `amenity=<value>`.
418476

@@ -421,7 +479,7 @@ Unknown strings are passed through as `amenity=<value>`.
421479
## Implementing a Custom Engine
422480

423481
```typescript
424-
import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix } from 'rendezvous-kit'
482+
import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix, RouteGeometry } from 'rendezvous-kit'
425483

426484
class MyRoutingEngine implements RoutingEngine {
427485
readonly name = 'MyEngine'
@@ -454,6 +512,27 @@ class MyRoutingEngine implements RoutingEngine {
454512
}
455513
return { origins, destinations, entries }
456514
}
515+
516+
async computeRoute(
517+
origin: LatLon,
518+
destination: LatLon,
519+
mode: TransportMode,
520+
): Promise<RouteGeometry> {
521+
const raw = await myApi.getRoute(origin, destination, mode)
522+
return {
523+
origin,
524+
destination,
525+
mode,
526+
durationMinutes: raw.seconds / 60,
527+
distanceKm: raw.metres / 1000,
528+
geometry: { type: 'LineString', coordinates: raw.polyline },
529+
legs: raw.steps.map((s: any) => ({
530+
instruction: s.text,
531+
distanceKm: s.metres / 1000,
532+
durationMinutes: s.seconds / 60,
533+
})),
534+
}
535+
}
457536
}
458537

459538
// Use it with findRendezvous
@@ -464,12 +543,12 @@ const suggestions = await findRendezvous(new MyRoutingEngine(), options)
464543

465544
## Engine Comparison
466545

467-
| Engine | Isochrone | Matrix | Auth | Notes |
468-
|--------|:---------:|:------:|------|-------|
469-
| Valhalla | Yes | Yes | None | Best self-hosted option; supports public transit |
470-
| OpenRouteService | Yes | Yes | API key | Free tier available; no public transit |
471-
| GraphHopper | Yes | Yes | Optional | API key only for cloud; optional self-hosted |
472-
| OSRM | No | Yes | None | Fastest matrix; no isochrone support |
546+
| Engine | Isochrone | Matrix | Route | Auth | Notes |
547+
|--------|:---------:|:------:|:-----:|------|-------|
548+
| Valhalla | Yes | Yes | Yes | None | Best self-hosted option; supports public transit |
549+
| OpenRouteService | Yes | Yes | No | API key | Free tier available; no public transit |
550+
| GraphHopper | Yes | Yes | No | Optional | API key only for cloud; optional self-hosted |
551+
| OSRM | No | Yes | No | None | Fastest matrix; no isochrone support |
473552

474553
---
475554

‎llms.txt‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,13 @@ Pure-TypeScript polygon geometry.
5252
- GeoJSONPolygon: { type: 'Polygon', coordinates: number[][][] }
5353
- TransportMode: 'drive' | 'cycle' | 'walk' | 'public_transit'
5454
- FairnessStrategy: 'min_max' | 'min_total' | 'min_variance'
55-
- VenueType: 'park' | 'cafe' | 'restaurant' | 'service_station' | 'library' | 'pub' | 'playground' | 'community_centre' | string
56-
- RendezvousOptions: { participants, mode, maxTimeMinutes, venueTypes, fairness?, limit? }
57-
- RendezvousSuggestion: { venue, travelTimes: Record<string, number>, fairnessScore }
58-
- RoutingEngine: interface { name, computeIsochrone, computeRouteMatrix }
55+
- VenueType: 'park' | 'cafe' | 'restaurant' | 'service_station' | 'library' | 'pub' | 'playground' | 'community_centre' | 'bar' | 'fast_food' | 'garden' | 'theatre' | 'arts_centre' | 'fitness_centre' | 'sports_centre' | 'escape_game' | 'swimming_pool' | string
56+
- RendezvousOptions: { participants, mode, maxTimeMinutes, venueTypes, fairness?, limit?, strategy? }
57+
- RendezvousSuggestion: { venue, travelTimes: Record<string, number>, fairnessScore, metadata? }
58+
- RoutingEngine: interface { name, computeIsochrone, computeRouteMatrix, computeRoute }
59+
- RouteGeometry: { origin, destination, mode, durationMinutes, distanceKm, geometry: GeoJSONLineString, legs?: RouteLeg[] }
60+
- RouteLeg: { instruction, distanceKm, durationMinutes, type?, streetNames?, verbalInstruction?, ... }
61+
- GeoJSONLineString: { type: 'LineString', coordinates: number[][] }
5962

6063
## Fairness Strategies
6164

0 commit comments

Comments
 (0)