Service Intervals

Service Intervals#

A Service Interval represents the time period during which a Vehicle is currently planned to be available for operations and thus available to complete Waypoints. The Service Interval is part of the Vehicle’s Mission and indicates when the current service period ends and where the Vehicle should go afterwards.

Service Interval Object#

The Service Interval is nested inside the Mission object and contains the following fields:

  • expected_end – The expected end time of the current service period.

  • service_break – The Service Break defining where the Vehicle goes at the end of the interval.

In addition, the Mission object exposes a driving_to_service_break_location flag indicating that the Vehicle is now driving to the Service Break Location.

{
  "mission": {
    "id": "95de2164-92c5-3ca0-80e9-e66f22c7afc5",
    "waypoints": [],
    "driving_to_service_break_location": false,
    "non_boarded_rides_should_be_moved": false,
    "service_interval": {
      "expected_end": "2024-03-13T12:00:00Z",
      "service_break": {
        "service_break_location": {
          "id": "sbl-001",
          "location": {
            "latitude": 53.583061,
            "longitude": 10.085728,
            "heading": 160
          }
        },
        "alternative_service_break_locations": [
          {
            "id": "sbl-002",
            "location": {
              "latitude": 53.587234,
              "longitude": 10.044567,
              "heading": 90
            }
          }
        ]
      }
    }
  }
}

Service Break#

Each Service Interval has a Service Break that defines where the Vehicle should go at the end of its service period. The Service Break contains:

  • service_break_location – The currently assigned Service Break Location where the Vehicle should go.

  • alternative_service_break_locations – A list of alternative locations that can be selected instead of the assigned one. If this list is empty, the assigned location is fixed and cannot be changed.

Service Break Location#

A Service Break Location represents a designated place to which a Vehicle returns at the end of a Service Interval. Each Service Break Location has:

  • id – Unique identifier of the location.

  • location – Geographic coordinates (latitude, longitude) and heading.

Service Interval Functionality#

Querying Service Intervals#

A Vehicle’s current Service Interval is returned as part of the Mission in the GetVehicle response.

Changing the Service Break Location#

When alternative Service Break Locations are available, the API client can change the assigned location using the UpdateServiceBreakLocation endpoint.

The request requires:

  • vehicle_id – The Vehicle to update.

  • fleet_id – The Fleet the Vehicle belongs to.

  • service_break_location_id – The id of the Service Break Location to use. Must be one of the alternative_service_break_locations.

  • previous_mission_id – The current Mission id, used to ensure that the Mission is only updated if it has not changed since it was last retrieved.

Note

The selected location must be one of the alternative_service_break_locations listed in the Service Break. Selecting a location not in this list will result in an error.