SER™ API Developer Documentation
Everything needed to make the first authenticated SER™ request, understand the response, and avoid the usual developer-console maze.
SER™ is Spatial Evidence Resolution: the process of transforming real-world, ambiguous, partial, or noisy location input into structured, auditable spatial evidence.
It is not commodity geocoding and not a best-match lookup. SER™ returns evidence: candidates, confidence, ambiguity, geometry classes, GIDs, SHA-256 audit keys, and explanations.
Customer calls go to:
https://travelsafepilot.com/api/v1/ser
- 1.Sign in or create one TravelSafePilot account.
- 2.Activate a SER™ plan from the API platform page.
- 3.Create an API key in the developer console.
- 4.Copy the key once when it is shown.
- 5.Make the first request.
curl "https://travelsafepilot.com/api/v1/ser?q=magic%20roundabout%20swindon&country_hint=gb" \ -H "Authorization: Bearer YOUR_API_KEY"
Keep API keys server-side. Do not place keys in browser JavaScript, mobile binaries, public repositories, or client-visible logs.
API requests use bearer API keys:
Authorization: Bearer YOUR_API_KEY
Dashboard sign-in and API request authentication are different surfaces. The dashboard uses your TravelSafePilot account session; the SER™ endpoint uses the API key.
Keys are tied to the canonical account and active entitlement state.
Version: v1
Methods: GET and POST
GET: /api/v1/ser?q=magic%20roundabout%20swindon&country_hint=gb
POST body: JSON with q or query, plus optional country_hint.
Accepted inputs: roads, intersections, traffic circles, roundabouts, route markers, landmarks, single points, and messy incident-style location text.
{
"ok": true,
"product": "SER",
"version": "v1",
"query": {
"raw": "magic roundabout swindon",
"normalized": "magic roundabout swindon",
"country_hint": "gb"
},
"resolution": {
"mode": "forward",
"reason": "candidates_found",
"ambiguous": false,
"candidate_count": 3,
"returned_count": 3
},
"top_candidate": {
"rank": 1,
"decision_role": "selected",
"match_type": "poi_cluster",
"gid": "2bc1a25c-cfe6-541d-a208-a9ba5919b6e5",
"candidate_sha256": "a4661d5c61b28181169521c27e4e01f0a474e6e94b66e34c1888e91d2429e355",
"software_version": "ser-v1",
"location": {
"lat": 51.56283512444738,
"lon": -1.7714570916666663,
"geometry_class": "junction_complex"
},
"context": {
"label": "The Magic Roundabout, gb",
"country_key": "gb",
"feature_kind": "roundabout"
},
"score": {
"value": 20.9626929266307,
"band": "very_high",
"ambiguous": false,
"candidate_count": 3,
"score_spread": 12.6626929266307,
"disqualified": false
},
"explain_human": "Candidates found - high confidence match"
},
"audit": {
"response_sha256": "example-response-hash",
"log_sha256": "example-log-integrity-hash",
"software_version": "ser-v1"
},
"candidates": []
}SHA-256 values are audit identifiers. They allow the candidate, response, log integrity record, and software version to be tied back to the exact decision path used at query time.
GID is the candidate identifier used for traceability.
Candidate SHA-256 binds a returned candidate to the resolved evidence state.
Response/log SHA-256 helps prove the audit record has not been silently altered.
Software version records which SER™ engine version performed the query.
Candidates are ordered interpretations. Alternatives preserve meaningful competing evidence where exposed.
Confidence values and bands are evidence signals, not guarantees.
Ambiguity must be treated as operationally meaningful. A low-confidence or ambiguous result should not be handled like a clean address match.
Geometry class describes the type of evidence: point, segment, corridor, area, junction, or unresolved interpretation.
SER™ requests are authenticated, entitlement-checked, classified, metered, and logged through the TravelSafePilot public gateway.
Usage is counted against Included SER™ queries per billing month for the active plan.
Public responses do not expose internal tables, internal hosts, stack traces, or raw internal model secrets.
Commercial request evidence is audit-oriented and does not log plaintext API keys.
Current public SER™ endpoint version: v1.
Breaking public API changes require documentation updates before release.
Undocumented shadow routes are not part of the public developer contract.