Running a field test cycle

1. Freeze the pairs

• Build a route in the demo (click start, click end), then "Save for field" and name it — e.g. "HB → Lindenhof". One save freezes a pair-doc: the same O/D answered by all three product profiles (fast / calm / safe) in one facade call, sharing one resolved time bucket. Tag each pair with a route type and area when saving — the plan table shows both.
• Pair-docs are frozen snapshots: every tester walks the exact same geometry, and feedback stays comparable across days and engine changes. Each doc records the full request, the resolved time-of-day bucket ("auto" resolved at save time), and per-edge path details (road class, trees, lights, accident/crime/presence) — so review can separate weight problems from data problems. Edits require re-saving (each pair links back to the demo via its permalink).
• Mix route types across the pool: simple, water/green, complex (station, bridges), elevation, POI-entrance. Aim for 8–20 minute walks. Keep one known-similar pair per tester as a perception control.

2. Assign and distribute

• On the field plan: enter tester names (one per line), pick a pair, walked mode, and walk window per tester per day, save. The mode dropdown pre-fills a fast/calm/safe rotation; the window defaults to the afternoon preset (13:00–17:00) — adjust to match your group rotation.
• Assigning the same pair to several testers (same mode, same window) is deliberate: aim for ~10 multi-walked pairs to measure inter-rater agreement. The grid marks them with a ×N badge — N testers on that pair.
• Saving generates the personal links (/field?t=name&day=N) — send each tester their links plus the tester guide.
• Reassigning mid-cycle is safe: testers see the plan as it is when they open their link. Deleting a pair never touches collected feedback.

3. Collect and analyze

• Review collected feedback on the field review page: an overview per pair (walks, ratings, top issues), a triage queue pre-sorted by fix surface, and a map view where flagged nodes carry the testers' annotations next to street-level imagery.
• Raw export anytime: curl https://<host>/api/v1/field/feedback > feedback.jsonl — one JSON row per annotation.
• Node rows carry tester, day, mode, pairId, nodeIndex, issues[], note, photos, gps, gpsDistanceM; compare rows (submitted at the pre-walk compare step) carry the choice-value rating plus compare chips; end-of-walk rows carry the route_correctness and mode_alignment ratings. pairId joins every row to the exact frozen geometry and request — rows double as replayable regression cases for engine work.
• Photos: testers shoot with their native camera and tick "I took photos here". Collect photos at the end of the week (AirDrop / shared album) and match them to rows by EXIF timestamp + GPS.
• Export before any redeploy: field data lives on the container filesystem unless a volume is mounted (ask whoever deploys).

4. Desk review (bench evaluation)

Flagged nodes rarely need a second field visit. In the demo, recreate or open the route permalink, click any numbered node or the route line, and review the spot in street-level imagery.

• Mapillary tab (recommended first): free token from mapillary.com/dashboard/developers. Community imagery covers footpaths and plazas where Street View has nothing. The map cone rotates live as you look around.
• Street View tab: each reviewer uses a key from their own Google account (own free quota). Enable Maps Embed API + Street View Static API (both free) and optionally Maps JavaScript API for the live panorama — 5,000 free dynamic loads per month per account; the panel shows a local ~N / 5000 free this month counter, and the tool falls back to the free embed automatically if the key can't serve the dynamic viewer.
• Panos are vetted to outdoor imagery (no indoor or rooftop photospheres); pink dots on the map are alternate viewpoints; footers show capture date and distance — judge evidence age accordingly.
• Share findings as URLs: the session permalink encodes route, settings, and the open node, so a colleague lands on the exact situation.
• Token setup travels in links too: append ?mly=<token> and/or ?gsv=<key> once — values persist in that reviewer's browser.

Scope notes

• The field API has no authentication — internal deployment only.
• Tester location is recorded only as one GPS snapshot per annotation (evidence), never as a continuous track — say so when recruiting testers.
• "My location looked wrong" rows are client/GPS issues, not routing-engine bugs — triage them to the app team.