API docs by Redocly

Event Reporting API (1)

Download OpenAPI specification:Download

Use this API to report cancellation and delay events, as well as other SLA breaches, directly to Ruter, along with a flag indicating whether you as an operator consider that the event was outside your control, and that you should be exempt from being fined for incurred/reported SLA breach(es).

/v1/traffic-events

Report traffic event

Report a cancellation or delay event.

header Parameters
Authorization
string

OAuth2 access token as Bearer token.

NOTE: Separate documentation will be provided on how to obtain client credentials and use these to request access tokens.

Request Body schema: application/json
required
category
required
string
Enum: "CANCELLATION" "DELAY"

The main category of the traffic event.

subcategory
required
string
Enum: "FULL" "PARTIAL" "FROM_START" "IN_TRANSIT"

The subcategory of the traffic event.

Permitted values if category is CANCELLATION:

  • FULL
  • PARTIAL

Permitted values if category is DELAY:

  • FROM_START
  • IN_TRANSIT
reason
required
string
Enum: "BOOM_BARRIER_OPENING" "CUSTOMER_CARE" "DEMONSTRATION" "DRIVER_ERROR" "EARLIER_DELAY" "EVENT" "FALLEN_DEBRIS" "FAULTY_BRAKES" "FAULTY_DOOR" "FAULTY_ENGINE" "FAULTY_GEARBOX" "FAULTY_SIS_SYSTEM" "FAULTY_TAAS_SYSTEM" "FAULTY_TICKET_MACHINE" "HEAVY_SNOWFALL" "IMPROPERLY_PARKED_VEHICLE" "NO_POWER" "OTHER_OBSTRUCTION" "OTHER_TECHNICAL_PROBLEM" "ROAD_ACCIDENT" "ROAD_WORK" "SIGNAL_ERROR" "SLIPPERY_ROADS" "TICKET_INSPECTION" "TRAFFIC_CONGESTION"

The reason for the traffic event. If set to OTHER_OBSTRUCTION or OTHER_TECHNICAL_PROBLEM, a description must be provided in the reasonDescription field.

reasonDescription
string
Default: "null"

Required if reason is set to OTHER_OBSTRUCTION or OTHER_TECHNICAL_PROBLEM, optional otherwise. A further detailing of the reason for the traffic event, and if relevant, an explanation for why you as an operator should be exempt from being fined for any SLA breach(es) incurred as a consequence of this traffic event (see isOperatorExempt).

startDateTime
string
Default: "null"

Required if datedJourneyRef is null, optional otherwise. An ISO UTC date string representing the date and time that the traffic event started. If null, the start time of the journey represented by datedJourneyRef is used instead.

endDateTime
string
Default: "null"

Required if datedJourneyRef is null, optional otherwise. An ISO UTC date string representing the date and time that the traffic event ended. If null, the end time of the journey represented by datedJourneyRef, plus delayMinutes if given, is used instead.

datedJourneyRef
string
Default: "null"

Required if lineRef is null. A reference to the planned journey that is affected by this traffic event, if only a single journey is affected.

Format should be one of:

  • <dated journey ID from plan data>
  • <vehicle task ID>-<journey start date time in ISO offset format>
vehicleInternalNumber
string
Default: "null"

Required if datedJourneyRef is set and a vehicle has been assigned to the journey. The internal number of the assigned vehicle that is affected by this traffic event, including prefixed garage number.

lineRef
string
Default: "null"

Required if datedJourneyRef is null, ignored otherwise. A reference to the affected line when multiple journeys are affected by this traffic event.

stopPlaceOrQuayRefs
Array of strings

Required if category is CANCELLATION and subcategory is PARTIAL, ignored otherwise. A list of NSR stop place or quay references to the stop places or quays that are affected by the partial cancellation.

delayMinutes
integer <int32>

Required if category is DELAY, ignored otherwise. The number of minutes that the journey is delayed.

isOperatorExempt
required
boolean

A flag indicating whether you as an operator consider that the event was outside your control, and that you should be exempt from being fined for any SLA breach(es) incurred as a consequence of the traffic event. If needed, an exemption reason can be provided in the reasonDescription field.

Responses

Request samples

Content type
application/json
{
  • "category": "CANCELLATION",
  • "subcategory": "PARTIAL",
  • "reason": "TRAFFIC_CONGESTION",
  • "reasonDescription": "En feilparkert bil blokkerte traséen",
  • "startDateTime": "1970-01-01T12:00:00Z",
  • "endDateTime": "1970-01-01T13:00:00Z",
  • "datedJourneyRef": "1234-1970-01-01T11:00:00+01:00",
  • "vehicleInternalNumber": "123456",
  • "lineRef": "RUT:Line:123",
  • "stopPlaceOrQuayRefs": [
    ],
  • "delayMinutes": 21,
  • "isOperatorExempt": true
}

Response samples

Content type
application/json
[
  • {
    }
]

/v1/sla-breaches

Report SLA breach

Report an SLA breach directly to Ruter, along with a flag indicating whether you as an operator consider that the breach was outside your control, and that you should be exempt from being fined for the breach.

header Parameters
Authorization
string

OAuth2 access token as Bearer token.

NOTE: Separate documentation will be provided on how to obtain client credentials and use these to request access tokens.

Request Body schema: application/json
required
breachNumber
string
Default: "null"

The SLA breach number. Must be null on registration.

category
required
string
Value: "DATA_QUALITY"

The SLA breach category.

reason
required
string
Enum: "ACCELEROMETER" "AUTOMATIC_PASSENGER_COUNTING" "BATTERY_LEVEL" "CHARGING_STATUS" "CLOCK" "DOOR_STATUS" "DYNAMIC_PASSENGER_INFORMATION" "ENERGY_CONSUMPTION" "INSIDE_TEMPERATURE" "ODOMETER" "OUTSIDE_TEMPERATURE" "POSITION" "SIGN_ON_SIGN_OFF" "STOP_SIGNAL" "TICKET_SALE" "VALIDATION_OF_RIGHT_TO_TRAVEL" "WINDSCREEN_WIPER_STATUS"

The reason for the SLA breach.

reasonDescription
string
Default: "null"

Optional. A further detailing of the reason for the SLA breach, and if relevant, an explanation for why you as an operator should be exempt from being fined for this breach (see isOperatorExempt).

datedJourneyRef
string
Default: "null"

Required if both vehicleTaskId and contractRef are null, takes precedence over both otherwise. A reference to the planned journey that is affected by this SLA breach.

Format should be one of:

  • <dated journey ID from plan data>
  • <vehicle task ID>-<journey start date time in ISO offset format>
vehicleTaskId
string
Default: "null"

Required if both datedJourneyRef and contractRef are null, takes precedence over contractRef otherwise. The ID of the vehicle task that is affected by this SLA breach.

vehicleInternalNumber
string
Default: "null"

Required if datedJourneyRef or vehicleTaskId is set and a vehicle has been assigned to the journey or vehicle task, or if all of datedJourneyRef, vehicleTaskId and contractRef are null. The internal number of the assigned vehicle that is affected by this SLA breach, including prefixed garage number.

contractRef
string
Default: "null"

Required if all of datedJourneyRef, vehicleTaskId and vehicleInternalNumber are null, ignored otherwise. A reference to the contract that governs the SLA that was breached.

startDateTime
string
Default: "null"

Required if contractRef or vehicleInternalNumber is set and both datedJourneyRef and vehicleTaskId are null, ignored otherwise. An ISO UTC date string representing the date and time that the SLA breach started. If not set, breach duration is inferred from referenced journey or vehicle task, in that order.

endDateTime
string
Default: "null"

Required if contractRef or vehicleInternalNumber is set and both datedJourneyRef and vehicleTaskId are null, ignored otherwise. An ISO UTC date string representing the date and time that the SLA breach ended. If not set, breach duration is inferred from referenced journey or vehicle task, in that order.

isOperatorExempt
required
boolean

A flag flag indicating whether you as an operator consider that the breach was outside your control, and that you should be exempt from being fined for the breach. If needed, an exemption reason can be provided in the reasonDescription field.

registeredBy
string
Default: "null"

Your operator's client identifier, automatically inferred from your API credentials. Must be null on registration.

registeredAt
string
Default: "null"

The date and time that the SLA breach was registered, in ISO UTC format. Automatically set on registration. Must be null on registration.

Responses

Request samples

Content type
application/json
{
  • "breachNumber": "1234",
  • "category": "DATA_QUALITY",
  • "reason": "DOOR_STATUS",
  • "reasonDescription": "Feil på sensor for dørstatus",
  • "datedJourneyRef": "1234-1970-01-01T11:00:00+01:00",
  • "vehicleTaskId": "1234",
  • "vehicleInternalNumber": "123456",
  • "contractRef": "RUT:Contract:123",
  • "startDateTime": "1970-01-01T12:00:00Z",
  • "endDateTime": "1970-01-01T13:00:00Z",
  • "isOperatorExempt": true,
  • "registeredBy": "Ruterbuss AS",
  • "registeredAt": "1970-01-01T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "breachNumber": "1234",
  • "category": "DATA_QUALITY",
  • "reason": "DOOR_STATUS",
  • "reasonDescription": "Feil på sensor for dørstatus",
  • "datedJourneyRef": "1234-1970-01-01T11:00:00+01:00",
  • "vehicleTaskId": "1234",
  • "vehicleInternalNumber": "123456",
  • "contractRef": "RUT:Contract:123",
  • "startDateTime": "1970-01-01T12:00:00Z",
  • "endDateTime": "1970-01-01T13:00:00Z",
  • "isOperatorExempt": true,
  • "registeredBy": "Ruterbuss AS",
  • "registeredAt": "1970-01-01T12:00:00Z"
}