The Trip Update API allows you to post location updates, battery status, and messages during a trip. These updates track your journey in real-time.

Base URL: http://localhost:8081/api/1/trips

Authentication: Required (USER or ADMIN role)

Post a location update for a trip.

Endpoint: POST /api/1/trips/{tripId}/updates

{
  "location": {
    "latitude": 42.8805,
    "longitude": -8.5457,
    "altitude": 365.2
  },
  "battery": 85,
  "message": "Just arrived in Santiago! What an amazing journey! 🎉"
}

Status: 201 Created

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "tripId": "660e8400-e29b-41d4-a716-446655440000",
  "location": {
    "latitude": 42.8805,
    "longitude": -8.5457,
    "altitude": 365.2
  },
  "battery": 85,
  "message": "Just arrived in Santiago! What an amazing journey! 🎉",
  "reactions": {
    "heart": 0,
    "smiley": 0,
    "sad": 0,
    "laugh": 0,
    "anger": 0
  },
  "timestamp": "2025-10-16T15:30:00Z"
}

curl -X POST http://localhost:8081/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 42.8805,
      "longitude": -8.5457,
      "altitude": 365.2
    },
    "battery": 85,
    "message": "Made it to Santiago!"
  }'

Post just your current location without additional information:

curl -X POST http://localhost:8081/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 42.8805,
      "longitude": -8.5457
    }
  }'

Share a status message with your location:

curl -X POST http://localhost:8081/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 43.0000,
      "longitude": -8.2000
    },
    "message": "Taking a rest at this beautiful viewpoint! 🏔️",
    "battery": 65
  }'

Include location, battery, altitude, and message:

curl -X POST http://localhost:8081/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 42.9500,
      "longitude": -8.3000,
      "altitude": 450.5
    },
    "battery": 72,
    "message": "Climbing up the mountain pass. Great views!"
  }'

The Trip Update API is designed to work seamlessly with OwnTracks, a popular location tracking app:

1. Configure OwnTracks to use HTTP mode
2. Set the endpoint URL to: http://your-server:8081/api/1/trips/{tripId}/updates
3. Add authentication header: Authorization: Bearer <your-token>

OwnTracks sends location data that maps to the Trip Update format:

• lat → location.latitude
• lon → location.longitude
• alt → location.altitude
• batt → battery

Trip doesn't exist:

{
  "timestamp": "2025-10-16T10:30:00.000Z",
  "status": 404,
  "error": "Not Found",
  "message": "Trip not found",
  "path": "/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates"
}

Invalid location data:

{
  "timestamp": "2025-10-16T10:30:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Latitude must be between -90 and 90",
  "path": "/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates"
}

Cannot update someone else's trip:

{
  "timestamp": "2025-10-16T10:30:00.000Z",
  "status": 403,
  "error": "Forbidden",
  "message": "You don't have permission to update this trip",
  "path": "/api/1/trips/660e8400-e29b-41d4-a716-446655440000/updates"
}

• Walking/Hiking: Every 5-10 minutes
• Driving: Every 1-2 minutes
• Stationary: Only when location changes significantly

• Reduce update frequency when battery is low
• Use coarse location accuracy for longer battery life
• Consider disabling updates below certain battery threshold

• Keep messages concise (under 280 characters recommended)
• Use emojis to convey emotion and save characters
• Include relevant context (weather, terrain, mood)

When internet connectivity is unavailable:

1. Queue updates locally on the device
2. Retry with exponential backoff
3. Send queued updates when connection is restored

The following endpoints for querying trip updates are planned:

• GET /api/1/trips/{tripId}/updates - Get all updates for a trip
• GET /api/1/trips/{tripId}/updates/latest - Get the most recent update
• GET /api/1/trips/{tripId}/updates/{updateId} - Get a specific update

• Trip API - Create and manage trips
• Comment API - Comment on trip updates
• Getting Started Guide - Full workflow examples