{
  "openapi": "3.0.3",
  "info": {
    "title": "PTV Flows Realtime Congestions API",
    "description": "The PTV Flows AI congestion detectors API provides realtime congestions and their features.",
    "version": "1.1.0"
  },
  "tags": [
    {
      "name": "Congestions"
    },
    {
      "name": "Feedback"
    }
  ],
  "paths": {
    "/realtime/feedback": {
      "post": {
        "tags": [
          "Feedback"
        ],
        "summary": "Submit feedback",
        "description": "Endpoint to submit feedback data.",
        "operationId": "submitFeedback",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedbackResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/realtime/get-congestions": {
      "get": {
        "tags": [
          "Congestions"
        ],
        "summary": "Realtime traffic congestions",
        "description": "Returns the traffic congestions currently detected for the product instance. Each item of `congestions` describes one detected congestion on the road network.\n\nThe fields of a congestion fall into these groups:\n- **Identification**: `id`, `uuId`, `parentUuIds`, `piid`, `type`.\n- **Timing**: `timestampEpoch`, `startingTimestampEpoch`.\n- **Location**: `shape`, `edges`, `name`, `description`.\n- **Severity** (how bad it is): `severity`, `severityByStreet`, `severityTrend`.\n- **Usuality** (how unexpected it is): `usuality`, `usualityByStreet`, `usualityByHierarchy`.\n- **Speed and extent**: `ffSpeedByStreet`, `speedDistributionByStreet`, `lengthM`, `lengthByHierarchy`, `sizeTrend`.\n\nAll `...ByStreet` arrays list one value per edge, in the same order as `edges`.",
        "operationId": "getTrafficCongestions",
        "parameters": [
          {
            "name": "If-None-Match",
            "in": "header",
            "description": "`ETag` value of a previous response. If the congestions have not changed since that ETag was issued, the server returns `304 Not Modified` without a body.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Currently detected congestions.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrafficCongestionsResponse"
                }
              }
            }
          },
          "204": {
            "description": "No congestions detected: the latest detection result contains no congestions.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            }
          },
          "304": {
            "description": "Not Modified. The `If-None-Match` value matches the current ETag: the congestions have not changed since that ETag was issued.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The API key or token is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Insufficient access rights: the Sentinel feature must be purchased.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found. No detection result exists for the product instance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests. The rate limit of 60 requests per minute per API key is exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error. The request could not be processed due to an internal error, for example because the stored detection result cannot be parsed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable. No recent detection result is available: the latest one is older than 15 minutes, for example because detection stopped.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "ETag": {
        "description": "An Etag is an identifier for a specific version of data. You should retain the latest ETag value you receive. The next time you call the same API to get data, you should use the If-None-Match request header along with the retained ETag value, so that the API will send back a full response if and only if the data changes.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "required": [
          "description",
          "errorCode",
          "traceId"
        ],
        "type": "object",
        "properties": {
          "description": {
            "description": "A human readable message that describes the error.",
            "type": "string"
          },
          "errorCode": {
            "description": "A constant string that can be used to identify this error class programmatically. An errorCode can have **details** to provide information in additional properties which are described with the code they apply to. They are of type string unless otherwise specified.  \n\nNote that additional errorCodes as well as the **details** of existing errorCodes may be added at any time. Furthermore, the **description** may change at any time.  \n\n**HTTP status code: 400**  \n* `GENERAL_VALIDATION_ERROR` - The validation of the request failed. Details can be found in **causes**.  \n* `GENERAL_PARSING_ERROR` - The JSON syntax is invalid.  \n\n**HTTP status code: 401**  \n* `GENERAL_UNAUTHENTICATED` - Invalid or missing authentication credentials.  \n  * `message` - An additional error message.  \n\n**HTTP status code: 403**  \n* `GENERAL_FORBIDDEN` - Insufficient access rights.  \n* `GENERAL_QUOTA_EXCEEDED` - The transaction limit is exceeded.  \n  * `message` - An additional error message.  \n\n**HTTP status code: 404**  \n* `GENERAL_RESOURCE_NOT_FOUND` - A requested resource does not exist.  \n  * `message` - An additional error message.  \n\n**HTTP status code: 429**  \n* `GENERAL_RATE_LIMIT_EXCEEDED` - The rate limit is exceeded.  \n\n**HTTP status code: 500**  \n* `GENERAL_INTERNAL_SERVER_ERROR` - The request could not be processed due to an internal error.  \n  * `message` - An additional error message.  \n  * `hint` - A hint how to solve the problem.  \n\n**HTTP status code: 503**  \n* `GENERAL_SERVICE_UNAVAILABLE` - The service is temporarily unavailable.",
            "type": "string"
          },
          "traceId": {
            "description": "A unique identifier of the corresponding trace forest. It can be used to trace errors by the support.",
            "type": "string"
          },
          "errorId": {
            "description": "A unique identifier specific to this error instance. It can be used to trace errors by the support.",
            "type": "string"
          },
          "causes": {
            "description": "A list of affected parameters and/or properties that caused this error.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CausingError"
            }
          },
          "details": {
            "description": "Additional properties specific to this error class.",
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "CausingError": {
        "required": [
          "description",
          "errorCode"
        ],
        "type": "object",
        "properties": {
          "description": {
            "description": "A human readable message that describes the error.",
            "type": "string"
          },
          "errorCode": {
            "description": "A constant string that can be used to identify this error class programmatically. An errorCode can have **details** to provide information in additional properties which are described with the code they apply to. They are of type string unless otherwise specified. \n\nNote that additional errorCodes as well as the **details** of existing errorCodes may be added at any time. Furthermore, the **description** may change at any time.  \n\n**Error codes for** `GENERAL_VALIDATION_ERROR`\n* `GENERAL_INVALID_VALUE` - A parameter is set to an invalid value.  \n  * `value` - The invalid value.  \n* `GENERAL_UNRECOGNIZED_PARAMETER` - A parameter is unknown.  \n* `GENERAL_DUPLICATE_PARAMETER` - A parameter is duplicated.  \n* `GENERAL_MINIMUM_VALUE_VIOLATED` - The minimum value restriction is violated.  \n  * `minimumValue` - The minimum value (integer or double).  \n* `GENERAL_MAXIMUM_VALUE_VIOLATED` - The maximum value restriction is violated.  \n  * `maximumValue` - The maximum value (integer or double).",
            "type": "string"
          },
          "parameter": {
            "description": "The name of the affected query or path parameter or a JSONPath to the affected property of the request.",
            "type": "string"
          },
          "details": {
            "description": "Additional properties specific to this error class.",
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "FeedbackData": {
        "required": [
          "trigger"
        ],
        "type": "object",
        "properties": {
          "congestionId": {
            "description": "Congestion ID related to the feedback (required for feedback type, null for behaviour type).",
            "type": "string"
          },
          "trigger": {
            "description": "Type of user action.",
            "enum": [
              "LIKE",
              "DISLIKE",
              "HIDE",
              "SHOW_ALL",
              "LIST_OPEN",
              "LIST_CLOSE",
              "SEARCH",
              "GO_NAME",
              "GO_BUTTON",
              "GO_MAP",
              "GO_TREND",
              "SHOW"
            ],
            "type": "string"
          },
          "comment": {
            "description": "Optional comment (only for feedback type).",
            "type": "string"
          }
        }
      },
      "FeedbackPayload": {
        "required": [
          "timestampOfUserAction",
          "productInstanceId",
          "ptvUserId",
          "type",
          "data"
        ],
        "type": "object",
        "properties": {
          "timestampOfUserAction": {
            "format": "int64",
            "description": "Epoch timestamp when the user performed the action.",
            "type": "integer"
          },
          "timestampOfFeedbackReceipt": {
            "format": "int64",
            "description": "Epoch timestamp when feedback was received (optional).",
            "type": "integer"
          },
          "productInstanceId": {
            "description": "Product instance identifier.",
            "type": "string"
          },
          "ptvUserId": {
            "description": "PTV user identifier.",
            "type": "string"
          },
          "type": {
            "description": "Type of payload.",
            "enum": [
              "FEEDBACK",
              "BEHAVIOUR"
            ],
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/FeedbackData"
          }
        }
      },
      "FeedbackResponse": {
        "required": [
          "status",
          "feedbackId",
          "receivedAt"
        ],
        "type": "object",
        "properties": {
          "status": {
            "description": "Status of the feedback submission (e.g., \"success\").",
            "type": "string"
          },
          "feedbackId": {
            "description": "Unique identifier for the submitted feedback.",
            "type": "string"
          },
          "receivedAt": {
            "format": "int64",
            "description": "Epoch timestamp when the feedback was received.",
            "type": "integer"
          }
        }
      },
      "TrafficCongestionsResponse": {
        "description": "Traffic congestions currently detected for the product instance.",
        "required": [
          "congestions"
        ],
        "type": "object",
        "properties": {
          "congestions": {
            "description": "Congestions detected in the latest detection cycle. Empty when none are detected.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "uuId": {
                  "description": "UUID string identifying this congestion within the current response. Reserved for future use as an identity that is kept between detection snapshots.\n\nUse it like `id`, as a unique reference to a congestion within one response.\n\n**Limitation:** newly generated on every detection cycle, even for the same ongoing congestion. It does not persist between calls, so do not use it to correlate congestions across polls.",
                  "type": "string",
                  "example": "3f6c2a9e-1b7d-4c55-9a0e-2d8f4b1c7e01"
                },
                "parentUuIds": {
                  "description": "UUIDs of all ancestor congestions of this congestion. A congestion can have several ancestors.\n\nUse it to trace what caused a congestion: the cause of a congestion is other congestions.\n\n**Limitation:** tracking congestions over time is not implemented yet. Reserved for future use. Not currently populated in responses (always an empty array). Do not rely on this field yet.",
                  "type": "array",
                  "items": {
                    "format": "uuid",
                    "type": "string"
                  },
                  "example": []
                },
                "id": {
                  "description": "Number identifying this congestion within the current response (1 to N).\n\nUse it to reference a specific congestion within a single response, for example in your own UI or logs for that call.\n\n**Limitation:** reassigned on every detection cycle. It does not persist between calls, so do not use it to track the same congestion across polls. To correlate a congestion between calls, use its location (`shape`, `edges`, `name`) instead.",
                  "type": "integer",
                  "example": 1
                },
                "startingTimestampEpoch": {
                  "format": "int64",
                  "description": "Start of the detection window, as a Unix epoch timestamp in seconds.",
                  "type": "integer",
                  "example": 1759305300
                },
                "timestampEpoch": {
                  "format": "int64",
                  "description": "Time of the traffic snapshot this detection is based on, as a Unix epoch timestamp in seconds. All congestions in a response share the same value.\n\nUse it as the \"last observed at\" time of the congestion.",
                  "type": "integer",
                  "example": 1759305600
                },
                "type": {
                  "description": "Category of the reported item. Currently always `Congestion`.",
                  "type": "string",
                  "example": "Congestion"
                },
                "shape": {
                  "description": "Geometry of the congested road edges as a Well-Known Text (WKT) `MULTILINESTRING`. Coordinates are in WGS84 (EPSG:4326), in longitude latitude order.\n\nParse it with any WKT or geometry library to draw the congestion on a map.\n\n**Limitation:** `null` when no geometry could be resolved for any edge of the congestion.",
                  "type": "string",
                  "example": "MULTILINESTRING ((12.5432 41.8711, 12.5448 41.8702), (12.5448 41.8702, 12.5461 41.8695))"
                },
                "speedDistributionByStreet": {
                  "description": "Reserved for a per-edge speed distribution, in the same order as `edges`.\n\n**Limitation:** reserved for future use. Not currently populated in responses (always an empty array). Do not rely on this field yet.",
                  "type": "array",
                  "items": {
                    "type": "object"
                  },
                  "example": []
                },
                "usualityByStreet": {
                  "description": "Usuality per edge, from 0 (highly unusual for this place and time) to 1 (fully usual), in the same order as `edges`.\n\nUse it for edge-level detail within a longer congestion.\n\n**Limitation:** edges without a historical speed profile score 1, so they never make a congestion look unusual.",
                  "type": "array",
                  "items": {
                    "format": "float",
                    "type": "number"
                  },
                  "example": [
                    0.25,
                    0.43
                  ]
                },
                "severityByStreet": {
                  "description": "Severity per edge, from 0 (traffic at free-flow speed) to 1 (traffic at a standstill), in the same order as `edges`. Computed as `(freeFlowSpeed - currentSpeed) / freeFlowSpeed`, clamped to 0–1.\n\nUse it to highlight the worst-affected part of a longer congestion.",
                  "type": "array",
                  "items": {
                    "format": "float",
                    "type": "number"
                  },
                  "example": [
                    0.7,
                    0.54
                  ]
                },
                "ffSpeedByStreet": {
                  "description": "Free-flow speed in km/h per edge, in the same order as `edges`: the speed traffic moves at without congestion.\n\nIt is the baseline used to compute `severityByStreet`.",
                  "type": "array",
                  "items": {
                    "format": "float",
                    "type": "number"
                  },
                  "example": [
                    50.0,
                    50.0
                  ]
                },
                "edges": {
                  "description": "Road-network edges that make up the congestion. Each item is a two-element array `[streetId, fromNodeId]`. Edges are listed in the same order as every `...ByStreet` array.\n\nUse these identifiers to cross-reference the congestion with your own network data when you need edge-level detail.",
                  "type": "array",
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "example": [
                    [
                      123456,
                      789
                    ],
                    [
                      123457,
                      790
                    ]
                  ]
                },
                "description": {
                  "description": "Reserved for a human-readable description of the congestion.\n\n**Limitation:** reserved for future use. Not currently populated in responses (always null). Do not rely on this field yet.",
                  "type": "string"
                },
                "severity": {
                  "format": "float",
                  "description": "Overall severity of the congestion, from 0 (traffic at free-flow speed) to 1 (traffic at a standstill), based on how much slower traffic moves than its free-flow speed.\n\nUse it as the primary \"how bad is it\" indicator, for example to rank alerts or colour a map.\n\nComputed as the mean of `severityByStreet` weighted by edge length, the same way as `usuality`: a long edge counts more than a short one.",
                  "type": "number",
                  "example": 0.65
                },
                "usuality": {
                  "format": "float",
                  "description": "How expected this congestion is for this place and time, from 0 (highly unusual) to 1 (fully usual). Computed as the mean of `usualityByStreet` weighted by edge length.\n\nUse it to tell routine congestion, such as the daily rush hour, from unexpected events such as incidents. A common threshold is to treat values below about 0.5 as unusual.\n\n**Limitation:** edges without a historical speed profile score 1, so they never make a congestion look unusual.",
                  "type": "number",
                  "example": 0.31
                },
                "lengthM": {
                  "format": "float",
                  "description": "Total length of the congestion in metres.\n\nUse it for display (for example \"1.3 km of congestion\") or to rank congestions by impact.",
                  "type": "number",
                  "example": 1270.5
                },
                "lengthByHierarchy": {
                  "description": "Length of the congestion in metres per functional road class. Keys are functional road class codes, as strings. This is the only field that gives the congested length per road class: the response has no length or road class per edge.\n\nUse it to prioritise congestions by road class, for example motorways first: 1 km on a motorway has a different impact than 1 km on a local street.\n\nTogether with `usualityByHierarchy`, it lets you recompute the overall usuality: the sum of `usualityByHierarchy[class] × lengthByHierarchy[class]` over all classes, divided by `lengthM`.",
                  "type": "object",
                  "additionalProperties": {
                    "format": "float",
                    "type": "number"
                  },
                  "example": {
                    "2": 850.0,
                    "4": 420.5
                  }
                },
                "usualityByHierarchy": {
                  "description": "Usuality per functional road class, from 0 (highly unusual) to 1 (fully usual). Keys are functional road class codes, as strings. Each value is the mean of `usualityByStreet` over the edges of that road class, weighted by edge length.\n\nUse it to see which road classes of a congestion are unusual, for example an unexpected jam on its motorway part.",
                  "type": "object",
                  "additionalProperties": {
                    "format": "float",
                    "type": "number"
                  },
                  "example": {
                    "2": 0.25,
                    "4": 0.43
                  }
                },
                "name": {
                  "description": "Street or location name of the congestion, for display (for example \"Congestion on Via Tuscolana\"). Taken from the first named edge of the congestion.\n\n**Limitation:** `null` when no edge of the congestion has a name.",
                  "type": "string",
                  "example": "Via Tuscolana"
                },
                "severityTrend": {
                  "description": "Intended to show whether the congestion is getting worse, better or staying the same.\n\n**Limitation:** reserved for future use. Not currently populated in responses (always null). Do not rely on this field yet. Do not build alerting logic that depends on it.",
                  "type": "string"
                },
                "sizeTrend": {
                  "description": "Intended to show whether the congestion is growing, shrinking or staying the same size.\n\n**Limitation:** reserved for future use. Not currently populated in responses (always null). Do not rely on this field yet. Do not build logic that depends on it.",
                  "type": "string"
                },
                "piid": {
                  "description": "Product instance id: the product instance the congestion was detected for. It is the product instance of the credentials (API key or token) used for the call.",
                  "type": "string",
                  "example": "my-product-instance"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "apiKey"
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://api.ptvgroup.tech/flows/realtime-congestions/v1"
    }
  ]
}