paddlesnitch
← Help

API

Free, read-only JSON. No key, no sign-in. Plans, places on the water and public time trials.

The basics

  • Every endpoint is a plain GET that answers JSON, with CORS open to any site.
  • Units are in the field names (distance_km, duration_s). Times are ISO 8601 with an offset. Route lines are GeoJSON ([lng, lat]); everything else is {lat, lng}.
  • Every response lists its sources in attribution. Show those credits wherever you show the data: OpenStreetMap is ODbL, the navigation authorities' data has its own licences.
  • Errors look like {"error": {"code": "not_connected", "message": "…"}}.
  • The full description, for tools: /api/v1/openapi.json (OpenAPI 3.1).
  • For planning only. paddlesnitch is not a navigation authority: check closures, river levels and the tide.

For AI assistants: MCP

The same data as a read-only MCP (Model Context Protocol) server, no sign-in: https://paddlesnitch.com/mcp (Streamable HTTP). Tools: search_places, plan_route, list_trials, get_trial, get_leaderboard. Each returns what the matching endpoint below returns.

Plan a paddle

GET /api/v1/plan

A route between two points on the water, with every lock, weir, portage, access point and facility along it, timed at your pace. The same parameters as a /plan link.

from *
"lat,lng", or a place name such as "Cropredy Lock".
to *
"lat,lng", or a place name.
waterway
Keep named ends to this waterway, e.g. "oxford-canal".
shape
return: out to `to` and back to `from`. One of one_way, return. Default one_way.
pace
Moving pace, km/h. Default 8.
portage
Minutes added at each portage. Default 3.
at
Start time; with it every stop gets an `eta`.

Try: /api/v1/plan?from=cropredy-lock&to=banbury&shape=return&pace=7

Find places on the water

GET /api/v1/places

Locks, wharves, slipways, portages and towns by name, each with its waterway: for choosing a plan's ends.

q *
near
"lat,lng": nearer matches first among equals.
waterway
Only places on this waterway.

Try: /api/v1/places?q=Cropredy

Public time trials

GET /api/v1/trials

status
One of open, closed.

Try: /api/v1/trials?status=open

One public time trial

GET /api/v1/trials/{trialId}

trialId *
In the path.

A public trial's results

GET /api/v1/trials/{trialId}/leaderboard

trialId *
In the path.
boat_class
e.g. K1, 1X, 8+