{"openapi":"3.1.0","info":{"title":"Bearing API","version":"0.1.0","description":"A fully local land-navigation and coordinate-math toolkit: DD/DMS/DDM/UTM/MGRS conversion, great-circle bearing/distance/destination/midpoint/cross-track, magnetic declination, dead reckoning, compass cardinals and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://bearing.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/bearing/docs"},"termsOfService":"https://connectorbay.com/bearing/terms"},"servers":[{"url":"https://bearing.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/bearing/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/convert_coordinates":{"post":{"operationId":"convert_coordinates","summary":"Converts a coordinate between Decimal Degrees (DD), Degrees-Minutes-Seconds (DMS), Degrees-Decimal-Minutes","description":"Converts a coordinate between Decimal Degrees (DD), Degrees-Minutes-Seconds (DMS), Degrees-Decimal-Minutes\n    (DDM), UTM and MGRS. UTM/MGRS math is the ellipsoidal Transverse Mercator projection on WGS84; DD/DMS/DDM are\n    exact arithmetic. Use for \"convert this lat/lon to UTM\", \"what's this MGRS grid ref in decimal degrees\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"input":{"description":"The coordinate to convert. For dd: 'lat,lon' decimal degrees, e.g. '37.7749,-122.4194'. For dms/ddm: two space-separated tokens, e.g. \"37°46'30\\\"N 122°25'12\\\"W\". For utm: 'zone letter easting northing', e.g. '10S 551000 4180000'. For mgrs: a single MGRS string, e.g. '10S ET 51000 80000'.","title":"Input","type":"string"},"from_format":{"description":"dd | dms | ddm | utm | mgrs","title":"From Format","type":"string"},"to_format":{"description":"dd | dms | ddm | utm | mgrs","title":"To Format","type":"string"}},"required":["input","from_format","to_format"],"title":"convert_coordinatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/bearing_and_distance":{"post":{"operationId":"bearing_and_distance","summary":"The initial compass bearing (forward azimuth, degrees true) and great-circle distance between two","description":"The initial compass bearing (forward azimuth, degrees true) and great-circle distance between two\n    points, via the haversine formula on a spherical Earth (accurate to within about 0.3%). Use for \"bearing\n    and distance from London to Paris\", \"how far is it from A to B and which way\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat1":{"description":"Start latitude.","maximum":90,"minimum":-90,"title":"Lat1","type":"number"},"lon1":{"description":"Start longitude.","maximum":180,"minimum":-180,"title":"Lon1","type":"number"},"lat2":{"description":"End latitude.","maximum":90,"minimum":-90,"title":"Lat2","type":"number"},"lon2":{"description":"End longitude.","maximum":180,"minimum":-180,"title":"Lon2","type":"number"},"unit":{"default":"km","description":"km | mi | nm | m | ft","title":"Unit","type":"string"}},"required":["lat1","lon1","lat2","lon2"],"title":"bearing_and_distanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/destination_point":{"post":{"operationId":"destination_point","summary":"Given a start point, an initial bearing and a distance, computes the destination point (the direct","description":"Given a start point, an initial bearing and a distance, computes the destination point (the direct\n    geodesic problem, spherical-Earth approximation). Use for \"where do I end up 10 km on a bearing of 045 from\n    here\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"Start latitude.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lon":{"description":"Start longitude.","maximum":180,"minimum":-180,"title":"Lon","type":"number"},"bearing_deg":{"description":"Initial compass bearing, degrees true, 0-360.","title":"Bearing Deg","type":"number"},"distance":{"description":"Distance to travel.","minimum":0,"title":"Distance","type":"number"},"unit":{"default":"km","description":"km | mi | nm | m | ft","title":"Unit","type":"string"}},"required":["lat","lon","bearing_deg","distance"],"title":"destination_pointArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/midpoint":{"post":{"operationId":"midpoint","summary":"The great-circle midpoint between two coordinates (spherical-Earth approximation) -- not the same as","description":"The great-circle midpoint between two coordinates (spherical-Earth approximation) -- not the same as\n    simply averaging the two lat/lon pairs, especially over long distances or near the poles. Use for \"what's\n    halfway between these two points\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat1":{"maximum":90,"minimum":-90,"title":"Lat1","type":"number"},"lon1":{"maximum":180,"minimum":-180,"title":"Lon1","type":"number"},"lat2":{"maximum":90,"minimum":-90,"title":"Lat2","type":"number"},"lon2":{"maximum":180,"minimum":-180,"title":"Lon2","type":"number"}},"required":["lat1","lon1","lat2","lon2"],"title":"midpointArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/cross_track_distance":{"post":{"operationId":"cross_track_distance","summary":"How far a point is off the great-circle course line between two other points ('am I on course'), and how","description":"How far a point is off the great-circle course line between two other points ('am I on course'), and how\n    far along that course line the point's projection falls. Positive cross-track = right of the course line\n    heading from path_start to path_end; negative = left. Spherical-Earth approximation.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"The point to check.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lon":{"description":"The point to check.","maximum":180,"minimum":-180,"title":"Lon","type":"number"},"path_start":{"description":"[latitude, longitude] of the course's start point.","items":{"type":"number"},"title":"Path Start","type":"array"},"path_end":{"description":"[latitude, longitude] of the course's end point.","items":{"type":"number"},"title":"Path End","type":"array"},"unit":{"default":"km","description":"km | mi | nm | m | ft","title":"Unit","type":"string"}},"required":["lat","lon","path_start","path_end"],"title":"cross_track_distanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/bearing_to_cardinal":{"post":{"operationId":"bearing_to_cardinal","summary":"Converts a numeric bearing to its nearest 16-point compass direction name (N, NNE, NE, ENE, E, ...).","description":"Converts a numeric bearing to its nearest 16-point compass direction name (N, NNE, NE, ENE, E, ...).\n    Use for \"what compass direction is 070 degrees\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bearing_deg":{"description":"A compass bearing in degrees, 0-360 (or any real number; it's normalised).","title":"Bearing Deg","type":"number"}},"required":["bearing_deg"],"title":"bearing_to_cardinalArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/dms_parse":{"post":{"operationId":"dms_parse","summary":"Parses one free-form DMS/DDM/DD coordinate string (a single latitude or longitude value, not a full","description":"Parses one free-form DMS/DDM/DD coordinate string (a single latitude or longitude value, not a full\n    lat/lon pair) into decimal degrees, handling common formatting variants and hemisphere letters. Use for\n    \"what's 37 46 30 N in decimal degrees\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dms_string":{"description":"A free-form DMS/DDM/DD coordinate token, e.g. \"37°46'30\\\"N\", '37 46 30 N', '37d46m30sN', or '-37.775'.","title":"Dms String","type":"string"}},"required":["dms_string"],"title":"dms_parseArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/plot_reckoning":{"post":{"operationId":"plot_reckoning","summary":"Dead-reckoning: given a starting point and a sequence of (bearing, distance) legs, computes the position","description":"Dead-reckoning: given a starting point and a sequence of (bearing, distance) legs, computes the position\n    after each leg and the final position -- the manual navigation technique hikers and sailors use to track\n    position without a fix. Also reports the direct (great-circle) distance from start to final position for\n    comparison against total distance travelled. Use for \"plot my course: 10 km on 045, then 5 km on 090\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_lat":{"maximum":90,"minimum":-90,"title":"Start Lat","type":"number"},"start_lon":{"maximum":180,"minimum":-180,"title":"Start Lon","type":"number"},"legs":{"description":"A list of {'bearing': degrees_true, 'distance': number} legs flown/sailed/walked in sequence.","examples":[[{"bearing":45,"distance":10},{"bearing":90,"distance":5}]],"items":{"additionalProperties":{"type":"number"},"type":"object"},"title":"Legs","type":"array"},"unit":{"default":"km","description":"km | mi | nm | m | ft","title":"Unit","type":"string"}},"required":["start_lat","start_lon","legs"],"title":"plot_reckoningArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/magnetic_declination":{"post":{"operationId":"magnetic_declination","summary":"Estimates magnetic declination (the angle between true north and magnetic north at a location, positive","description":"Estimates magnetic declination (the angle between true north and magnetic north at a location, positive\n    = east) from a coarse, hand-sampled World Magnetic Model-epoch lookup table, inverse-distance interpolated.\n    This is NOT a full spherical-harmonic WMM evaluation -- see the disclaimer field. Use for \"what's the\n    magnetic declination in Denver\", \"how much do I need to correct my compass for true north here\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lon":{"maximum":180,"minimum":-180,"title":"Lon","type":"number"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Informational only; this simplified model does not adjust for secular variation beyond its stated epoch. ISO date, e.g. '2026-06-01'.","title":"Date"}},"required":["lat","lon"],"title":"magnetic_declinationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/land_nav_glossary":{"post":{"operationId":"land_nav_glossary","summary":"Plain-language definitions of common land-navigation terms: azimuth, true vs magnetic north, declination","description":"Plain-language definitions of common land-navigation terms: azimuth, true vs magnetic north, declination\n    vs deviation, grid north, great-circle vs rhumb line, datum, UTM, MGRS, DMS/DDM/DD, dead reckoning,\n    cross-track distance, and isogonic line. Use for \"what's the difference between declination and deviation\",\n    \"what does MGRS stand for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up (e.g. 'declination', 'MGRS', 'rhumb line'); omit to list all.","title":"Term"}},"title":"land_nav_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}