LocoNav Trips API

openapi: 3.2.0
info:
  title: LocoNav Integration Trips API
  version: v1
  description: 'LocoNav''s REST APIs for fleet telematics integration: telematics (sensor/GPS/video/live-stream), CRUD resource management (drivers, vehicles, trips, geofences, users), safety and connected-driver features, alerts and alert-subscriptions, and immobilization. Converted from LocoNav''s published Postman documentation at developers.loconav.com. All listing endpoints are paginated (page/perPage); time parameters use epoch seconds.'
  contact:
    name: LocoNav Developer Support
    url: https://developers.loconav.com/
servers:
- url: https://api.a.loconav.com/integration/api/v1
  description: Production
security:
- UserAuthentication: []
tags:
- name: Trips
paths:
  /integration/api/v1/trips:
    get:
      operationId: listTrips
      summary: List Trips
      tags:
      - Trips
      responses:
        '200':
          description: Successful response
      description: 'Overview


        This API allows users to retrieve a list of trips based on various filters such as unique ID, start time, end time, states, driver ID, sort column, sort order, page number, and number of trips per page.


        Query Parameters:


        uniqueId (string, optional): Unique ID of the trip.


        startTime (integer, optional): Start time of the trip.


        endTime (integer, optional): End time of the trip.


        states (string, optional): Comma-separated list of states to filter trips by. { initialized, trashed, ongoing, delayed, unsuccessful, completed }


        driverId (integer, optional): ID of the driver associated with the trip.


        sortColumn (string, optional): Column to sort the trips by. {shouldStartAt, createdAt}


        sortOrder (string, optional): Order of sorting {asc, desc}.


        page (integer, optional): Page number of the results.


        perPage (integer, optional): Number of trips per page.


        vehicleNumber (string, optional): Number of the vehicle associated with the trip.


        Response Structure


        success (boolean): Indicates whether the request was successful.


        data.values (array): Array of trip objects.


        id (integer): ID of the trip.


        vehicleNumber (string): Number of the vehicle associated with the trip.


        vehicleId (integer): ID of the vehicle associated with the trip.


        uniqueId (string): Unique ID of the trip.


        shouldStartTs (integer): Start time of the trip.


        createdAt (integer): Time'
    post:
      operationId: createTrip
      summary: Create Trip
      tags:
      - Trips
      responses:
        '200':
          description: Successful response
      description: 'Overview


        Create Trip.


        Create trip using route name: Pass route name in the create trip API.


        Create trip using Route id: Pass route id in the create trip API.


        Create trip using geofence: Pass geofence id in the create trip API


        Create Trip using the address and coordinates : Pass address and coordinates in source in the create trip API


        Create Trip where the destination is not known


        Create Trip with multiple stops/checkpoints


        Create Trip Request


        Removing the vehicle json object from the body of the request will create a trip request instead of trip. (Trip state will be "requested" instead of "new"). For this "trip_request" feature should be enabled for User.


        Mandatory Fields :


        should_start_at


        source


        "geofence_id" or "geofence_name" or a combination of ("coordinates" and "address")


        Validations:


        etd (Estimated Time of Departure) > eta (Estimated Time of Arrival)


        Cases:


        Route[id, name], if either of id and name is present, it means we are using existing route. source, checkpoints, destination can be ignored.


        If Route[id, name] not present, send Source and CheckPoints. Destination is optional.


        if create_new_vehicle_route is not present, route won''t be shown on UI.


        if create_new vehicle route is present, route name is mandatory and will be shown on UI.


        Request Body


        vehicle


        id (integer)


        number (string)


        route


        <ul'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              trip:
                vehicle:
                  number: VT_MOCKER2
                customFields: {}
                createNewVehicleRoute: true
                newVehicleRouteName: test_test_route_12
                shouldStartAt: 1706264834
                uniqueId: test_01
                expectedDistance: 30
                tripDelayAlertsEnabled: true
                sourceName: Gurugram
                shouldExpireOldTrips: false
                source:
                  address: test_address
                  coordinates: 10.01,10.01
                  radius: 10
                  eta: 1706285834
                  etd: 1706287834
  /integration/api/v1/trips/{tripId}:
    put:
      operationId: updateTrip
      summary: Update Trip
      tags:
      - Trips
      responses:
        '200':
          description: Successful response
      description: 'Overview


        This API endpoint allows users to update trip details such as the source location and actions.


        Action can have these 4 values


        UPDATE_TRIP - Can update any variables


        Mandatory Fields : action, source


        END_TRIP - To end the trip: Only need "id" for this.


        Mandatory Fields : action, source


        PARTIAL_UPDATE_TRIP - Can be used to update "custom_fields" only.


        Mandatory Fields : action, custom_fields


        REJECT_TRIP - To reject a trip which is in requested state.


        Mandatory Fields: action


        START_TRIP - To start the trip: Only need "id" for this.


        Mandatory Fields : action


        Path Variables


        tripId (integer): Unique identifier for the trip to be deleted.


        Request Body


        action (string, required)


        newVehicleRouteName (string)


        shouldStartAt (integer, epoch timestamp) Time by which trip should be started


        expectedDistance (integer)


        tripDelayAlertsEnabled (boolean)


        sourceName (string)


        destinationName (string)


        shouldExpireOldTrips (boolean) Mark True if you want to expire all active trips on the vehicle.


        checkPoints


        geofenceId (integer)


        geofenceName (string)


        eta (integer, epoch timestamp in seconds)


        etd (integer, epoch timestamp in seconds)


        coordinates (string, lat,long)


        address (string)


        createGatepass (boolean)


        source


        geofe'
      parameters:
      - name: tripId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              trip:
                action: START_TRIP
                source:
                  address: test_address
                  coordinates: 10.01,10.01
                  radius: 10
                  eta: 1706285834
                  etd: 1706287834
    delete:
      operationId: deleteTrip
      summary: Delete Trip
      tags:
      - Trips
      responses:
        '200':
          description: Successful response
      description: 'Overview


        This API endpoint allows administrators to delete a trip based on its ID.


        Request Parameters


        tripId (integer): Unique identifier for the trip to be deleted.


        Response Structure


        success (boolean): Indicates whether the request was successful.


        message(string): A message confirming the success of the deletion operation.


        Notes


        Replace {trip_id} in the URL with the actual ID of the trip to be deleted.'
      parameters:
      - name: tripId
        in: path
        required: true
        schema:
          type: string
  /integration/api/v1/trips/{tripId}/track_url:
    get:
      operationId: getTripTrackUrl
      summary: Get Trip Track Url
      tags:
      - Trips
      responses:
        '200':
          description: Successful response
      description: 'Overview


        This API endpoint retrieves a public tracking URL for a specific trip, including given checkpoints, allowing users to monitor the trip''s progress in real-time.


        Clients can send this URL directly to end customers for real time public tracking of the vehicle.


        Path Parameters


        {trip_id} (integer): ID of the trip for which the tracking URL is requested.


        Query Parameters


        allCheckPoints (boolean): Indicates whether to include all checkpoints in the tracking URL. Set to true to include all checkpoints.


        checkPointIds (array of integer): If allCheckPoints param is false then user need to pass geofence ids that were passed in Create Trip API. (Eg: [23,45]). The map will only shows the mentioned check points.


        Response Structure


        success (boolean): Indicates whether the request was successful.


        data


        tripTrackToken (string): Token used to track the trip.


        url (string): Tracking URL for the trip.'
      parameters:
      - name: tripId
        in: path
        required: true
        schema:
          type: string
components:
  securitySchemes:
    UserAuthentication:
      type: apiKey
      in: header
      name: User-Authentication
      description: User-level API token supplied in the User-Authentication request header.