Trips

Trips are named date ranges, such as a vacation, with their own timeline, map path, summary, and plan. A trip can be linked to a timeline label and shared with friends as collaborators. Not to be confused with trips on the timeline, which are movements between stays.

📄️ List trips

Returns the trips the signed-in user owns and the trips shared with them as a collaborator.

📄️ Create a trip

Creates a trip for a date range. The status follows the dates (upcoming, active, completed) unless set otherwise.

📄️ Create a trip from a timeline label

Creates a trip with the name, dates, and color of an existing timeline label and links the two. Later changes to the label update the trip.

📄️ Update a trip

Changes the name, dates, status, color, or notes of a trip.

📄️ Get a trip

Returns a trip with its name, dates, status, color, and the timeline label it is linked to, if any.

📄️ Delete a trip

Deletes a trip. If the trip is linked to a timeline label, `mode` decides what happens to the label.

📄️ List trip collaborators

Returns the friends a trip is shared with and their access level (`VIEW` or `EDIT`).

📄️ Share a trip with a friend

Adds a friend as a collaborator on a trip, or changes their access level: `VIEW` lets them see the trip, `EDIT` also lets them change the plan.

📄️ Stop sharing a trip with a friend

Removes a collaborator from a trip.

📄️ Unlink a trip from its timeline label

Removes the link between a trip and its timeline label. Both are kept; changes to one no longer affect the other.

📄️ Get the GPS path of a trip

Returns the trip owner's GPS path during the trip for drawing on a map. Optionally narrow the range within the trip dates.

📄️ Get a trip summary

Returns totals for a trip: plan items visited out of planned, number of stays and movements, distance, and time spent moving.

📄️ Get the timeline of a trip

Returns the stays, trips, and data gaps of the trip owner during the trip. Collaborators see the owner's timeline. Optionally narrow the range within the trip dates.

📄️ Get visit suggestions

Returns stays that GeoPulse matched to the trip's plan items, with distance, confidence, and whether each match was applied. Confirm or override a match with `PUT /api/v1/trips/{tripId}/plan-items/{itemId}/visit-override`.