Seamark

Read a trip's ordered legs: list them, or get one by id. A leg's statsSource is 'track' when its stats, coordinates and times are computed from a GPX track, 'manual' otherwise. On a trip someone else shared with the caller, get reads a leg but list does not — its legs are in trip_read's get. The weather fields are hand-entered observations, except the wind pair when weatherSource is 'open_meteo': windSpeedKn is true wind speed in knots, windDirDeg an integer 0-359 in meteorological convention (the direction the wind blows FROM), seaState the Douglas degree of sea 0-9. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change a trip's ordered legs: create, update, delete, reorder (a full leg-id permutation, reassigning seq 1..N), and fill a leg's wind from a weather service (fetch_weather). A leg backed by a track (statsSource: 'track') rejects an update that touches any computed stats/coordinate/time field with a stats_readonly error — its startName/endName/notes stay editable regardless. The weather fields are hand-entered observations, except the wind pair when weatherSource is 'open_meteo': windSpeedKn is true wind speed in knots, windDirDeg an integer 0-359 in meteorological convention (the direction the wind blows FROM), seaState the Douglas degree of sea 0-9. They stay editable on EVERY leg, track-backed or not, because no GPX file records them. fetch_weather fills the leg's WIND (speed and direction, never sea state) from the free Open-Meteo service: it resolves the position and time window from the leg's own data (its track's middle point, else its endpoint midpoint, else its start) and stores the arithmetic mean of the hourly speeds over that window plus their SPEED-WEIGHTED circular mean direction, stamping weatherSource 'open_meteo' and weatherFetchedAt — except when the window was a dead calm, which yields no direction: a hand-entered windDirDeg then survives and the response says weatherSource 'manual' instead, because the stamp must never attribute a hand-typed value to the provider. This is the ONLY action that makes an outbound network call on the caller's behalf, it is rate-limited to 30 per hour per user, and it overwrites whatever wind the leg already had, hand-entered included. A later hand-edit of either WIND field flips weatherSource back to 'manual' and clears weatherFetchedAt; writing seaState does NOT, because the pair records where the wind came from and sea state is never fetched. A leg with no usable coordinates or no usable time window is weather_no_position (422); an upstream failure or a date the provider does not cover is weather_unavailable (503). IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read the caller's private address book of people — crew and contacts: list them all, or get one by id. Personal data (birth date, passport) is never shared across users. linkedAccount reports whether this person has accepted an invitation and is linked to a Seamark account. isSelf marks the ONE person in the caller's book that is the caller, so voyages with them on the crew list count as the caller's own. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change the caller's private address book of people — crew and contacts (create, update, delete, unlink_account, mark_self, unmark_self, invite, accept_invitation). Personal data (birth date, passport) is never shared across users. linkedAccount reports whether this person has accepted an invitation and is linked to a Seamark account. isSelf marks the ONE person in the caller's book that is the caller, so voyages with them on the crew list count as the caller's own. invite mails a Seamark invitation to a person who crews at least one of the caller's trips (409 invitation_no_trips otherwise — the person must be on a trip's crew first); accepting it links their account to this person, which opens EVERY trip of the caller's they crew, past and future, so the mail lists all of them. It is rate-limited to one send per person per minute and 3 sends per recipient address per hour (a budget shared with trip_write's announce, keyed on the address rather than the feature), remembers the address on the person's email (advancing the person's updatedAt version token — the response carries the new value), and re-inviting replaces the previous invitation, so a mistyped address's link stops working. accept_invitation is the other side: it binds the CALLER's own account to the person named by the token, requires the caller's address to match the one invited, and returns every trip it opened. unlink_account revokes a person's account link everywhere at once AND cancels any invitation to that person that has not been accepted yet — a pending invite mail stops working, which is what makes the revocation final rather than something the other party can undo by re-clicking their link. It is idempotent, and on someone who was never linked its only effect is to cancel a pending invitation. mark_self sets isSelf (marking someone new moves the marker off whoever held it — at most one person is the caller), unmark_self clears it. Both are idempotent and unrelated to linkedAccount/invitations — "this is me" is the caller's own identity, not an access grant. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

The caller's sailing résumé — the record a charter company asks for before handing over a boat: one row per voyage the caller sailed with a known role, newest first, each with start and end date, the boat (name, model, length overall in centimeters as loaCm, hull type, or null when the voyage has no boat), the caller's role ('skipper' or 'crew'), ports-of-call countries (ISO 3166-1 alpha-2) and sea areas in voyage order, distance in meters, days at sea and night time in seconds. Totals cover the returned rows, overall and per role. Optional role ('all', 'skipper', 'crew') filters the rows; optional from/to (YYYY-MM-DD, inclusive) bound them by start date. Voyages where the caller is not on the crew have no role, are left out, and are counted as unattributedTripsCount. The figures come from the caller's own log and are not verified by anyone else. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read the caller's boats — a reusable, per-owner registry: list them all, or get one by id. The optional flag field is a ship's flag state as an uppercase ISO 3166-1 alpha-2 country code (e.g. "HR", "CZ"), or null. The optional hullType is 'monohull', 'catamaran' or 'trimaran', or null when unknown. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Create, update or delete one of the caller's boats. The optional flag field is a ship's flag state as an uppercase ISO 3166-1 alpha-2 country code (e.g. "HR", "CZ"), or null. The optional hullType is 'monohull', 'catamaran' or 'trimaran', or null when unknown. Sending null for flag or hullType clears it. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

The caller's lifetime logbook statistics across their whole log — the trips they own AND the trips shared with them as linked crew. Returns totals (distance in meters, moving/total time in seconds, days at sea, distinct shipmates, best sustained 1/5/10-minute speeds in knots, average speed, earliest trip date), a per-year breakdown (by trip start-date year, newest first), and a per-boat breakdown (own and shared boats, each flagged owned; by distance, largest first). The optional role filters every figure by the role the caller held on each trip: 'all' (default) counts every voyage, 'skipper' or 'crew' count only voyages where the caller held that role. Voyages where the caller is not on the crew have no role: they count only under 'all' and are reported as unattributedTripsCount. ownedTripsCount and sharedTripsCount split the whole log into voyages the caller owns and voyages shared with them, whatever the role. All distances are meters and all durations seconds — never nmi/hours; speeds are knots or null. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read a leg's GPX track: get the current track, and audit every kept/dropped point with its drop reason. Audit results are paged with offset/limit; a long track has many points. On a trip someone else shared with the caller, get reads the track; the audit stays the owner's. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change a leg's GPX track: import raw GPX text (inline, capped at 5 Mi UTF-16 code units — that is what the schema counts, so it is roughly 5 MB for plain-ASCII GPX and no less for a file full of non-ASCII names; the server-side pipeline caps are separate: 32 MB of bytes AND at most 75,000 trackpoints per file (#191) — a file over the inline cap goes through the REST upload route instead, and one over the point cap has to be split or simplified first), reprocess the leg's stored raw file at the current pipeline version, and delete the track (the leg reverts to statsSource 'manual', retaining its last computed stats). IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read the caller's voyages: list (the caller's OWN log), list the trips others shared with the caller (list_shared), get one trip, get its combined map, and get its public share link (get_share). get composes trip metadata with its crew, charter, and legs (there is no separate crew or charter read). map returns a GeoJSON FeatureCollection with one feature per mappable leg — track-backed, or manual with both endpoints set; a leg with no geometry is omitted. A trip someone else shared with the caller is readable with get and map and listed by list_shared, never by list; its charter is withheld, and so is the pickupBase summary field. get_share returns the trip's public, read-only, no-login link or null. Charter price/deposit are integer minor units plus an ISO 4217 currency code — never a float. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change the caller's own voyages: create, update, delete, replace the full crew set (set_crew, PUT semantics), set or clear the charter (set_charter — a null charter clears it), announce the trip to its crew by email (announce), and turn its public link on or off (create_share, revoke_share). Charter price/deposit are integer minor units plus an ISO 4217 currency code — never a float. Inviting a crew member to the app is person_write's invite/accept_invitation: an invitation is person-scoped, and accepting one shares every trip of that owner whose crew that person is on, past and future. announce mails the trip's particulars to crew who have a linked account and have not switched that category off in Settings; it reports how many actually went out, and is rate-limited per trip and per recipient address. create_share turns on a public, read-only, no-login link to one of the caller's OWN trips and returns its URL (idempotent — one link per trip, calling it again returns the same URL); revoke_share turns it off. The public view is redacted — no charter, crew shown as initials only, no owner details — but anyone with the link can open it, so the URL is semi-public. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

The authenticated caller's own profile (id, email, name, language). Takes no arguments. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.