From 9a30df8f2673da02d7ffdb0a01aff888868994ef Mon Sep 17 00:00:00 2001
From: Brian Fauble <bfauble@users.noreply.github.com>
Date: Fri, 22 Dec 2023 09:32:08 -0600
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=F0=9F=8D=8E=F0=9F=9A=AB?=
 =?UTF-8?q?=F0=9F=92=B0=20Update=20Swagger=20API=20documentation=20to=20ex?=
 =?UTF-8?q?plain=20non-revenue=20service=20representation=20and=20predicti?=
 =?UTF-8?q?on=20'uncertainty'=20(#700)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* add uncertainty docs

* add revenue_status filter docs

* add revenue status description

* update wording
---
 .../controllers/prediction_controller.ex      | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/apps/api_web/lib/api_web/controllers/prediction_controller.ex b/apps/api_web/lib/api_web/controllers/prediction_controller.ex
index 60db84f9..4c4c4bbe 100644
--- a/apps/api_web/lib/api_web/controllers/prediction_controller.ex
+++ b/apps/api_web/lib/api_web/controllers/prediction_controller.ex
@@ -277,6 +277,61 @@ defmodule ApiWeb.PredictionController do
               "x-nullable": true
             )
 
+            arrival_uncertainty(
+              [:integer, :null],
+              """
+              Uncertainty value for the arrival time prediction.
+
+              Bus and Commuter Rail
+              See [entities tripUpdate stop_time_updates arrival uncertainty](https://swiftly-inc.stoplight.io/docs/realtime-standalone/613d1d7f1eae3-gtfs-rt-trip-updates)
+
+              | Value            | Description |
+              |------------------|-------------|
+              | < 300 or omitted |	Valid real-time prediction |
+              | 300              |  Real-time prediction not available. This code is primarily used when a vehicle has not yet been assigned to the trip, (i.e. because the block has not started yet). It is a schedule-based prediction, but Swiftly adjusts the schedule-based prediction time using observed historical travel times to make predictions more accurate than the schedule |
+              | 301              |	Valid real-time prediction, though the bus appears to be stalled or significantly delayed and predictions are not as accurate |
+              | > 301            |	Likely invalid prediction, recommend not showing anything (and not showing scheduled time), very rare situation |
+
+
+              Subway/Light Rail
+              See [GTFS `Realtime` `FeedMessage` `FeedEntity` `TripUpdate` `StopTimeUpdate` `arrival`](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-stoptimeupdate).
+
+              | Value  | Description |
+              |--------|-------------|
+              | 60   | A trip that has already started |
+              | 120  | A terminal/reverse trip departure for a trip that has NOT started and a train is awaiting departure at the origin |
+              | 360  | A terminal/reverse trip for a trip that has NOT started and a train is completing a previous trip |
+              """,
+              example: 60
+            )
+
+            departure_uncertainty(
+              [:integer, :null],
+              """
+              Uncertainty value for the departure time prediction.
+
+              Bus and Commuter Rail
+              See [entities tripUpdate stop_time_updates departure uncertainty](https://swiftly-inc.stoplight.io/docs/realtime-standalone/613d1d7f1eae3-gtfs-rt-trip-updates)
+
+              | Value            | Description |
+              |------------------|-------------|
+              | < 300 or omitted |	Valid real-time prediction |
+              | 300              | Real-time prediction not available. This code is primarily used when a vehicle has not yet been assigned to the trip, (i.e. because the block has not started yet). It is a schedule-based prediction, but Swiftly adjusts the schedule-based prediction time using observed historical travel times to make predictions more accurate than the schedule |
+              | 301              |	Valid real-time prediction, though the bus appears to be stalled or significantly delayed and predictions are not as accurate |
+              | > 301            |	Likely invalid prediction, recommend not showing anything (and not showing scheduled time), very rare situation |
+
+              Subway/Light Rail
+              See [GTFS `Realtime` `FeedMessage` `FeedEntity` `TripUpdate` `StopTimeUpdate` `departure`](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-stoptimeupdate).
+
+              | Value | Description |
+              |-------|-------------|
+              | 60    | A trip that has already started |
+              | 120   | A terminal/reverse trip departure for a trip that has NOT started and a train is awaiting departure at the origin |
+              | 360   | A terminal/reverse trip for a trip that has NOT started and a train is completing a previous trip |
+              """,
+              example: 60
+            )
+
             schedule_relationship(
               :string,
               """