swagger.yml

swagger: "2.0"
info:
  version: "1.0.0"
  title: "UnderLX API"
  description: "
  ![UnderLX logo](https://blog.underlx.com/images/logo.png)
  
  Part of the [UnderLX project](https://underlx.com), this API provides information about public transit networks.
  Like the remainder of the project, it is currently very focused on the [Lisbon Metro](https://www.metrolisboa.pt).

  Most of the API can be used freely without providing any credentials.
  The UnderLX project reserves the right to throttle or outright deny service to certain users based on their IP address.
  
  A small part of the API requires authentication and is currently for exclusive use of the UnderLX project.
  
  The main consumer of this API is the [UnderLX Android application](https://github.com/underlx/underlx).
  
  <br>
  The API \"speaks\" both JSON and [MessagePack](https://msgpack.org/).
  When consuming it, the `Accept` header must be set to the desired serialization format, as well as the `Content-Type` header when sending requests with a body.
  If it is not specified, beautified JSON is provided, which is not ideal.
  
  This documentation assumes JSON is used.
  MessagePack request and response bodies are generally equivalent to their JSON counterparts, but there are some differences, namely, in how dates and durations are serialized.
  
  <br>
  Some of the information provided by this API comes from the [UnderLX Open Data](https://github.com/underlx/data) project, and is provided under the [Open Database License](https://github.com/underlx/data/blob/master/LICENSE).

  The API itself is licensed under the [Apache License Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)."
  termsOfService: "https://underlx.com/terms"
  contact:
    name: "UnderLX Team"
    email: "underlx@tny.im"
    url: "https://underlx.com/contact"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "api.underlx.com"
basePath: "/v1"
tags:
- name: "announcements"
  description: "Official news and social media posts"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/announcement.go"
- name: "connections"
  description: "Directional line segments between stations"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/connection.go"
- name: "datasets"
  description: "Meta-information used for data versioning"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/dataset.go"
- name: "disturbances"
  description: "Service disruption and degradation events"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/disturbance.go"
- name: "feedback"
  description: "User feedback and problem reports"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/feedback.go"
- name: "gateways"
  description: "Forms of real-time communication between server and clients"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/gateway.go"
- name: "lines"
  description: "Passenger service lines"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/line.go"
- name: "line_conditions"
  description: "Supposed service conditions (number of cars per train, etc.)"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/linecondition.go"
- name: "lobbies"
  description: "Station lobbies, with one or more exits"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/lobby.go"
- name: "maps"
  description: "Pointers to transit maps for human consumption"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/map.go"
- name: "meta"
  description: "Meta-information about the API and its state"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/meta.go"
- name: "networks"
  description: "Transit networks"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/network.go"
- name: "pair"
  description: "Authentication credentials"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/pair.go"
- name: "pair_connections"
  description: "Connections with external services"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/pairconnection.go"
- name: "pois"
  description: "Points of Interest - notable world locations"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/poi.go"
- name: "stations"
  description: "Transit stations"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/station.go"
- name: "stats"
  description: "Transit network statistics"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/stats.go"
- name: "transfers"
  description: "Directional connections between passenger service lines"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/transfer.go"
- name: "trips"
  description: "Journey in public transit"
  externalDocs:
    description: "Source code"
    url: "https://github.com/underlx/disturbancesmlx/blob/master/resource/trip.go"
schemes:
- "https"
paths:
  /announcements:
    get:
      tags:
      - "announcements"
      summary: "List announcements"
      operationId: "listAnnouncements"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Announcement"
  /announcements/{sourceID}:
    get:
      tags:
      - "announcements"
      summary: "List announcements of source"
      operationId: "listAnnouncementsOfSource"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "sourceID"
        required: true
        type: string
        description: "The ID of the source for which to retrieve announcements"
        x-example: "pt-ml-rss"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Announcement"
  
  /connections:
    get:
      tags:
      - "connections"
      summary: "List connections"
      operationId: "listConnections"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Connection"
  /connections/{from}/{to}:
    get:
      tags:
      - "connections"
      summary: "Get specific connection"
      operationId: "getConnection"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "from"
        required: true
        type: string
        description: "The ID of origin station for the connection to retrieve"
        x-example: "pt-ml-bc"
      - in: path
        name: "to"
        required: true
        type: string
        description: "The ID of target station for the connection to retrieve"
        x-example: "pt-ml-ro"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Connection"

  /datasets:
    get:
      tags:
      - "datasets"
      summary: "List available datasets"
      operationId: "listDatasets"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Dataset"
  /datasets/{id}:
    get:
      tags:
      - "datasets"
      summary: "Get information about a dataset"
      operationId: "getDataset"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The network ID of the dataset to retrieve"
        x-example: "pt-ml"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Dataset"

  /disturbances:
    get:
      tags:
      - "disturbances"
      summary: "List past and/or ongoing disturbances"
      operationId: "listDisturbances"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: query
        name: "omitduplicatestatus"
        description: "Whether duplicate line status should be omitted. Duplicate line status are present mainly on earlier disturbances. Should always be true."
        required: false
        type: boolean
      - in: query
        name: "start"
        required: false
        type: string
        format: date-time
        description: "Limit returned disturbances to those after this date-time. Incompatible with `filter=ongoing`"
      - in: query
        name: "end"
        required: false
        type: string
        format: date-time
        description: "Limit returned disturbances to those before this date-time. Incompatible with `filter=ongoing`"
      - in: query
        name: "filter"
        required: false
        type: string
        enum: [all, ongoing]
        description: "If `ongoing`, will limit returned disturbances to ongoing ones. Incompatible with `start` and `end`"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Disturbance"
  /disturbances/{id}:
    get:
      tags:
      - "disturbances"
      summary: "Get specific disturbance"
      operationId: "getDisturbance"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The ID of the disturbance to retrieve"
        x-example: "9b8d7a99-044e-4248-9b3c-ae98f7de38c8"
      - in: query
        name: "omitduplicatestatus"
        description: "Whether duplicate line status should be omitted. Duplicate line status are present mainly on earlier disturbances. Should always be true."
        required: false
        type: boolean
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Disturbance"
  /disturbances/reports:
    post:
      tags:
      - "disturbances"
      summary: "Report service disruption"
      operationId: "reportDisturbance"
      security:
        - apiPair: []
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: "body"
        name: "body"
        description: "Report"
        required: true
        schema:
          type: object
          properties:
            line:
              type: string
              description: "ID of the affected line"
              example: "pt-ml-azul"
            category:
              type: string
              description: "Problem category. Currently ignored"
      responses:
        200:
          description: "successful operation"

  /feedback:
    post:
      tags:
      - "feedback"
      summary: "Submit feedback"
      operationId: "submitFeedback"
      security:
        - apiPair: []
      consumes:
      - "application/json"
      - "application/msgpack"
      produces:
        - "application/json"
        - "application/msgpack"
      parameters:
      - in: "body"
        name: "body"
        description: "Feedback to submit"
        required: true
        schema:
          $ref: "#/definitions/Feedback"
      responses:
        201:
          description: "feedback submitted successfully"
          schema:
            $ref: "#/definitions/Feedback"
        401:
          $ref: "#/responses/Unauthorized"

  /gateways:
    get:
      tags:
      - "gateways"
      summary: "List available gateways"
      operationId: "listGateways"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Gateway"
  
  /lines:
    get:
      tags:
      - "lines"
      summary: "List service lines"
      operationId: "listLines"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Line"
  /lines/{id}:
    get:
      tags:
      - "lines"
      summary: "Get specific line"
      operationId: "getLine"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The ID of the line to retrieve"
        x-example: "pt-ml-azul"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Line"

  /lines/conditions:
    get:
      tags:
      - "line_conditions"
      summary: "List past and/or current line conditions"
      operationId: "listLineConditions"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: query
        name: "filter"
        required: false
        type: string
        enum: [all, latest]
        description: "If `latest`, will limit returned conditions to current ones."
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/LineCondition"
  /lines/{lineID}/conditions:
    get:
      tags:
      - "line_conditions"
      summary: "List past and/or current conditions for a specific line"
      operationId: "listLineConditionsForLine"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "lineID"
        required: true
        type: string
        description: "The ID of the line for which to retrieve conditions"
        x-example: "pt-ml-verde"
      - in: query
        name: "filter"
        required: false
        type: string
        enum: [all, latest]
        description: "If `latest`, will limit returned conditions to the current one."
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/LineCondition"
  /lines/conditions/{id}:
    get:
      tags:
      - "line_conditions"
      summary: "Get specific line condition"
      operationId: "getLineCondition"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The ID of the line condition to retrieve"
        x-example: "7f63f9df-ac76-4d88-a984-eeb04852e741"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/LineCondition"

  /lobbies:
    get:
      tags:
      - "lobbies"
      summary: "List station lobbies"
      operationId: "listLobbies"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Lobby"
  /lobbies/{id}:
    get:
      tags:
      - "lobbies"
      summary: "Get specific lobby"
      operationId: "getLobby"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The ID of the lobby to retrieve"
        x-example: "pt-ml-as-central"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Lobby"
  
  /maps:
    get:
      tags:
      - "maps"
      summary: "List transit maps"
      operationId: "listMaps"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Map"
  
  /meta:
    get:
      tags:
      - "meta"
      summary: "Obtain API endpoint meta-information"
      operationId: "getMeta"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Meta"

  /meta/backers:
    get:
      tags:
      - "meta"
      summary: "Obtain information about project supporters and sponsors"
      operationId: "getBackers"
      produces:
      - "text/html"
      responses:
        200:
          description: "successful operation.
            The reponse contains simple HTML markup, possibly containing image tags, with backer information, meant to be displayed to the user.
            Should be cached by the client for up to 48 hours; the `last-modified` header, obtained with a HEAD request,
            should be used to decide whether updating this information is necessary."
          headers:
            last-modified:
              type: string
              description: "Date-time, in HTTP format, of the last modification of this information. Should be used by clients to decide whether updating this information is necessary."
          schema:
            type: file
    head:
      tags:
      - "meta"
      summary: "Obtain last modification time of project supporters and sponsors"
      operationId: "headBackers"
      responses:
        200:
          description: "successful operation"
          headers:
            last-modified:
              type: string
              description: "Date-time, in HTTP format, of the last modification of this information. Should be used by clients to decide whether updating this information is necessary."

  /networks:
    get:
      tags:
      - "networks"
      summary: "List transit networks"
      operationId: "listNetworks"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Network"
  /networks/{id}:
    get:
      tags:
      - "networks"
      summary: "Get specific network"
      operationId: "getNetwork"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The ID of the network to retrieve"
        x-example: "pt-ml"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Network"
  
  /pair:
    post:
      tags:
      - "pair"
      summary: "Create authentication credentials"
      operationId: "createPair"
      consumes:
      - "application/json"
      - "application/msgpack"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: "body"
        name: "body"
        description: "Pair request information"
        required: true
        schema:
          type: object
          properties:
            nonce:
              type: string
              format: uuid
              description: "Client-generated 36 characters long random string. The use of a v4 UUID is recommended. This is used to prevent replay attacks."
            timestamp:
              type: string
              format: date-time
              description: "Client-generated request timestamp, in RFC3339 format. This is used to confirm that the clock of the client is sufficiently synchronized"
            androidID:
              type: string
              description: "Client device ID. This is used to prevent Sybil attacks."
            signature:
              type: string
              description: "Base64-encoded SHA256 ECDSA signature of the concatenation of `nonce` with `timestamp` and `androidID`. The private key used to generate the signature is undisclosed. This is used to prevent unauthorized creation of API credentials"
      responses:
        200:
          description: "pair created"
          schema:
            type: object
            properties:
              key:
                type: string
                description: "API access key. Should be provided as the username in exchanges that require one, like HTTP Basic Auth or the MQTT CONNECT packet"
              secret:
                type: string
                description: "API access secret. Should be provided as the password in exchanges that require one, like HTTP Basic Auth or the MQTT CONNECT packet"
              type:
                type: string
                description: "Pair type"
              activation:
                type: string
                format: date-time
                description: "Date-time after which this pair is valid and can be used to access the API"
  /authtest:
    get:
      tags:
      - "pair"
      summary: "Check API pair validity"
      operationId: "checkPair"
      security:
        - apiPair: []
      produces:
        - "application/json"
        - "application/msgpack"
      responses:
        200:
          description: "valid credentials"
          schema:
            type: object
            properties:
              result:
                type: string
                example: "ok"
                description: "Should be `ok`"
              key:
                type: string
                description: "Echoing of the API pair key"
        401:
          $ref: "#/responses/Unauthorized"
  
  /pair/connections:
    get:
      tags:
      - "pair_connections"
      summary: "List service connections for the pair"
      operationId: "listPairConnections"
      security:
        - apiPair: []
      produces:
        - "application/json"
        - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/PairConnection"
        401:
          $ref: "#/responses/Unauthorized"
    post:
      tags:
      - "pair_connections"
      summary: "Connect pair to a service"
      operationId: "createPairConnection"
      security:
        - apiPair: []
      consumes:
      - "application/json"
      - "application/msgpack"
      produces:
        - "application/json"
        - "application/msgpack"
      parameters:
      - in: "body"
        name: "body"
        description: "Connection request"
        required: true
        schema:
          type: object
          properties:
            code:
              type: string
              description: "User-provided code for association with a service"
            deviceName:
              type: string
              description: "Human-friendly name of the client device (brand, model)"
      responses:
        200:
          description: "successful operation"
          schema:
            type: object
            properties:
              result:
                type: string
                description: "Should be `connected`"
                example: "connected"
              serviceName:
                type: string
                description: "Human-friendly name of the service the user just connected with"
                example: "PosPlay"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: "a service willing to connect using the provided code was not found"
          schema:
            type: object
            properties:
              result:
                type: string
                example: "failure"
  /pois:
    get:
      tags:
      - "pois"
      summary: "List points of interest"
      operationId: "listPOIs"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/POI"
  /pois/{id}:
    get:
      tags:
      - "pois"
      summary: "Get specific point of interest"
      operationId: "getPOI"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        format: uuid
        description: "The ID of the point of interest to retrieve"
        x-example: "89eca3cc-3d8e-49ac-a112-98a7d7c6724f"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/POI"

  /stations:
    get:
      tags:
      - "stations"
      summary: "List stations"
      operationId: "listStations"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Station"
  /stations/{id}:
    get:
      tags:
      - "stations"
      summary: "Get specific station"
      operationId: "getStation"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        description: "The ID of the station to retrieve"
        x-example: "pt-ml-pe"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Station"
  
  /stats:
    get:
      tags:
      - "stats"
      summary: "Get statistics for all networks"
      operationId: "getStats"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: query
        name: "start"
        required: false
        type: string
        format: date-time
        description: "Start of the range for which to compute statistics. Defaults to the present moment minus 7 days"
      - in: query
        name: "end"
        required: false
        type: string
        format: date-time
        description: "End of the range for which to compute statistics. Defaults to the present moment"
      - in: query
        name: "type"
        required: false
        type: string
        enum: [official, unofficial]
        description: "Whether to consider unofficial disturbances in the computations. Defaults to official only."
      responses:
        200:
          description: "successful operation"
          schema:
            type: object
            description: "Map indexed by network ID containing statistics for each network"
            additionalProperties:
              $ref: "#/definitions/Stats"
  /stats/{networkID}:
    get:
      tags:
      - "stats"
      summary: "Get statistics for specific network"
      operationId: "getStatsForNetwork"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "networkID"
        required: true
        type: string
        description: "The ID of the network for which to retrieve stats"
        x-example: "pt-ml"
      - in: query
        name: "start"
        required: false
        type: string
        format: date-time
        description: "Start of the range for which to compute statistics. Defaults to the present moment minus 7 days"
      - in: query
        name: "end"
        required: false
        type: string
        format: date-time
        description: "End of the range for which to compute statistics. Defaults to the present moment"
      - in: query
        name: "type"
        required: false
        type: string
        enum: [official, unofficial]
        description: "Whether to consider unofficial disturbances in the computations. Defaults to official only."
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Stats"

  /transfers:
    get:
      tags:
      - "transfers"
      summary: "List transfers"
      operationId: "listTransfers"
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Transfer"
  /transfers/{stationID}/{fromID}/{toID}:
    get:
      tags:
      - "transfers"
      summary: "Get specific transfer"
      operationId: "getTransfer"
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "stationID"
        required: true
        type: string
        description: "The ID of the station for the transfer to retrieve"
        x-example: "pt-ml-am"
      - in: path
        name: "fromID"
        required: true
        type: string
        description: "The ID of the line from which the transfer to retrieve originates"
        x-example: "pt-ml-verde"
      - in: path
        name: "toID"
        required: true
        type: string
        description: "The ID of the line to which the transfer to retrieve goes"
        x-example: "pt-ml-vermelha"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Transfer"

  /trips:
    get:
      tags:
      - "trips"
      summary: "List trips made by the user"
      operationId: "listMyTrips"
      security:
        - apiPair: []
      produces:
      - "application/json"
      - "application/msgpack"
      responses:
        200:
          description: "successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Trip"
        400:
          description: "Bad request. This is most likely due to an invalid trip"
        401:
          $ref: "#/responses/Unauthorized"
    post:
      tags:
      - "trips"
      summary: "Submit trip"
      operationId: "submitTrip"
      security:
        - apiPair: []
      consumes:
      - "application/json"
      - "application/msgpack"
      produces:
        - "application/json"
        - "application/msgpack"
      parameters:
      - in: "body"
        name: "body"
        description: "Trip to submit. Some fields will be overwritten by the server"
        required: true
        schema:
          $ref: "#/definitions/Trip"
      responses:
        201:
          description: "trip submitted successfully"
          schema:
            $ref: "#/definitions/Trip"
        401:
          $ref: "#/responses/Unauthorized"
    put:
      tags:
      - "trips"
      summary: "Edit user trip"
      operationId: "editMyTrip"
      security:
        - apiPair: []
      consumes:
      - "application/json"
      - "application/msgpack"
      produces:
        - "application/json"
        - "application/msgpack"
      parameters:
      - in: "body"
        name: "body"
        description: "Edited trip. Some fields will be overwritten by the server"
        required: true
        schema:
          $ref: "#/definitions/Trip"
      responses:
        200:
          description: "trip edited successfully"
          schema:
            $ref: "#/definitions/Trip"
        400:
          description: "Bad request. This is most likely due to an invalid trip"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: "trip not found or not made by the user"
  /trips/{id}:
    get:
      tags:
      - "trips"
      summary: "Get specific trip made by the user"
      operationId: "getMyTrip"
      security:
        - apiPair: []
      produces:
      - "application/json"
      - "application/msgpack"
      parameters:
      - in: path
        name: "id"
        required: true
        type: string
        format: uuid
        description: "The ID of the trip to retrieve"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Trip"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: "trip not found or not made by the user"

definitions:
  Announcement:
    type: "object"
    properties:
      time:
        type: string
        format: date-time
      title:
        type: string
      body:
        type: string
      imageURL:
        type: string
        format: url
      url:
        type: string
        format: url
      source:
        type: string
        description: "ID of the source of this information"
      network:
        type: string
        description: "ID of the network this announcement pertains to"
  Connection:
    type: "object"
    properties:
      from:
        type: string
        description: "ID of the station this connection originates from"
        example: "pt-ml-po"
      to:
        type: string
        description: "ID of the station this connection ends at"
        example: "pt-ml-af"
      typWaitS:
        type: integer
        description: "Typical waiting seconds. The average time users are waiting for a vehicle at `from` when going in the direction of `to`"
      typStopS:
        type: integer
        description: "Typical stop seconds. The average time vehicles are stopping by `from` when going in the direction of `to`"
      typS:
        type: integer
        description: "Typical seconds. The average time it takes for a vehicle to go through this connection"
      worldLength:
        type: integer
        description: "The length of this connection in meters"
        example: 732
  Dataset:
    type: "object"
    properties:
      network:
        type: string
        description: "ID of the network covered by this dataset"
        example: "pt-ml"
      version:
        type: string
        description: "Version of the dataset. Usually the date of the last modification, but this is not guaranteed to be the case forever."
        example: "2019-09-20T15:28:32+01:00"
      authors:
        type: array
        items:
          type: string
        description: "List of authors of this dataset"
  Disturbance:
    description: "A disturbance is a service disruption or degradation events signalled by one or more line status indicative of bad service."
    type: "object"
    properties:
      id:
        type: string
        format: uuid
        description: "Unique disturbance ID in the UnderLX system"
      official:
        type: boolean
        description: "Whether this disturbance was confirmed by official sources"
      oStartTime:
        type: string
        format: date-time
        description: "Official start time. Invalid if the disturbance is not official"
      oEndTime:
        type: string
        format: date-time
        description: "Official end time. Invalid if the disturbance is not official or if it is still ongoing"
      oEnded:
        type: boolean
        description: "Whether the disturbance has ended, according to official sources. False if the disturbance is still ongoing"
      startTime:
        type: string
        format: date-time
        description: "Disturbance start time. Always a valid date-time"
      endTime:
        type: string
        format: date-time
        description: "Disturbance end time. Invalid if the disturbance is still ongoing"
      ended:
        type: boolean
        description: "Whether the disturbance has ended"
      description:
        type: string
        description: "Disturbance for the description according to the sources. Usually corresponds to the first status of the disturbance"
      notes:
        type: string
        description: "Notes manually added by the UnderLX team. May contain simple HTML markup, including image tags."
      network:
        type: string
        description: "ID of the network affected by this disturbance"
        example: "pt-ml"
      line:
        type: string
        description: "ID of the line affected by this disturbance"
        example: "pt-ml-amarela"
      categories:
        description: "Categories automatically assigned by UnderLX"
        type: array
        items:
          type: string
          enum:
          - SIGNAL_FAILURE
          - TRAIN_FAILURE
          - POWER_OUTAGE
          - 3RD_PARTY_FAULT
          - PASSENGER_INCIDENT
          - STATION_ANOMALY
          - COMMUNITY_REPORTED
      statuses:
        description: "Line statuses"
        type: array
        items:
          $ref: "#/definitions/LineStatus"
  Feedback:
    type: object
    properties:
      id:
        type: string
        format: uuid
        description: "Feedback UUID as generated by the client"
      time:
        type: string
        format: date-time
        description: "Time at which feedback was provided"
      type:
        type: string
        enum:
          - s2ls-incorrect-detection
        description: "The type of feedback"
      contents:
        type: string
        description: "Arbitrary feedback data whose semantics depend on `type`"

  LineStatus:
    type: object
    properties:
      id:
        type: string
        format: uuid
        description: "Unique line status ID in the UnderLX system"
      time:
        type: string
        format: date-time
        description: "Time at which the line assumed this status (or at which UnderLX received this status for the line)"
      downtime:
        type: boolean
        description: "Whether this status represents a disruption in the passenger service"
      status:
        type: string
        description: "Line status as produced/captured"
        example: "Devido a avaria na sinalização está interrompida a circulação na linha entre as estações  Odivelas e Lumiar. Não é possível prever a duração da interrupção, que poderá ser prolongada. Pedimos desculpa pelo incómodo causado"
      msgType:
        type: string
        description: "Status type as automatically identified from `status`. Can be used to facilitate automated translation of statuses by the client."
        example: "ML_SIGNAL_BETWEEN_LONGHALT"
      source:
        type: string
        description: "Internal ID of the status source in the UnderLX system"
        example: "mlxscraper-pt-ml"
      officialSource:
        type: boolean
        description: "Whether the `source` is considered official"
  Line:
    type: "object"
    allOf:
      - type: object
        properties:
          id:
            type: string
            description: "Unique line ID in the UnderLX system"
            example: "pt-ml-azul"
          name:
            type: string
            description: "Main human-friendly name of the line"
            example: "Azul"
          color:
            type: string
            description: "Color associated with this line, in hexadecimal RRGGBB format."
            example: "5082C3"
          typCars:
            type: integer
            description: "Typical number of cars for vehicles performing service in this line"
            example: 6
          order:
            type: integer
            description: "Value used for sorting this line next to other lines of the same network, when displayed to users"
            example: 10
          externalID:
            type: string
            description: "ID of this line in 3rd-party systems, such as the transit operator's system"
            example: "A"
          network:
            type: string
            description: "ID of the network this line belongs to"
            example: "pt-ml"
          stations:
            type: array
            items:
              type: string
            description: "IDs of stations that are part of this line, in sequential order"
          schedule:
            type: array
            items:
              $ref: "#/definitions/Schedule"
            description: "Schedules defining the opening time of this line"
          worldPaths:
            description: "Paths of the line in the real world. Some lines have multiple paths because of e.g. each direction taking a slightly different route."
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                  description: "ID of the path"
                  example: "pt-ml-azul-rb"
                path:
                  type: array
                  description: Latitude-longitude pairs defining the path.
                  items:
                    example: [38.719805, -9.155609]
                    type: array
                    items:
                      type: number
                      format: float
      - $ref: "#/definitions/Localizable"
  LineCondition:
    type: object
    properties:
      id:
        type: string
        format: uuid
        description: "Unique line condition ID in the UnderLX system"
      time:
        type: string
        format: date-time
        description: "Time at which this condition was assumed"
      trainCars:
        type: integer
        description: "Supposed number of cars for trains performing passenger service in the line. If zero, there's no information or there is no passenger service on the line"
      trainFrequency:
        type: string
        description: "Target time interval between trains performing passenger service in the line"
        example: "4m30s"
      line:
        type: string
        description: "ID of the line this condition applies to"
        example: "pt-ml-verde"
      source:
        type: string
        description: "Internal ID of the condition source in the UnderLX system"
  Lobby:
    type: object
    properties:
      id:
        type: string
        description: "Unique lobby ID in the UnderLX system"
      name:
        type: string
        description: "Human-friendly lobby name"
      network:
        type: string
        description: "ID of the network this lobby belongs to"
        example: "pt-ml"
      station:
        type: string
        description: "ID of the station this lobby belongs to"
      exits:
        description: "Station entrances that lead to this lobby"
        type: array
        items:
          $ref: "#/definitions/StationExit"
      schedule:
        type: array
        items:
          $ref: "#/definitions/Schedule"
        description: "Schedules defining the opening time of this lobby"
  StationExit:
    type: object
    properties:
      id:
        type: integer
        description: "ID of the station exit in the UnderLX system"
      worldCoord:
        description: "Latitude-longitude pair describing the real world position of the exit"
        example: [38.76845, -9.12848]
        type: array
        items:
          type: number
          format: float
      streets:
        description: "Names of nearby streets and places"
        type: array
        items:
          type: string
      type:
        description: "The type of exit"
        type: string
        enum:
          - stairs
          - lift
          - ramp
          - escalator
  Meta:
    type: object
    properties:
      supported:
        type: boolean
        description: "True if this API endpoint is still maintained and not deprecated. If false, clients must refrain from using this endpoint, and update their systems to use a supported endpoint, and/or inform the end user to update their client software, and/or announce service deprecation."
      up:
        type: boolean
        description: "True if this API endpoint is operating normally. If false, clients must refrain from using this endpoint, and inform the user of the unavailability of online services."
      minAndroidClient:
        type: integer
        description: "Minimum build version of the UnderLX Android client allowed to use this endpoint. If the build number is below this value, the client must refrain from using this endpoint, and tell the user to update the client."
      motd:
        description: "The endpoint's \"Message of the day\". This is a localized string meant to be displayed to the user, if possible."
        type: object
        properties:
          html:
            description: "Map of language codes to strings, providing translations for each locale. Strings may contain simple HTML markup, possibly including image tags.
            
            If a translation is not available for the relevant locale, the one specified by `mainLocale` should be used."
            type: object
            additionalProperties:
              type: string
          mainLocale:
            type: string
            description: Key of the `html` to use, when a translation is not available for the relevant locale.
          priority:
            type: integer
            description: "How prominently the MOTD should be displayed to the user. Lower values signify higher priority and prominence."
  Network:
    allOf:
      - type: object
        properties:
          id:
            type: string
            description: "Unique network ID in the UnderLX system"
            example: "pt-ml"
          name:
            type: string
            description: "Main human-friendly name of the transit network"
            example: "Metro de Lisboa"
          typCars:
            type: integer
            description: "Typical number of cars for vehicles performing service in this network"
            example: 6
          holidays:
            description: "List of holidays observed by this network, as days of the year (January 1st: 1; December 31st: 365/366).
            
            This information is needed to correctly operate with schedules."
            type: array
            items:
              type: integer
          openTime:
            type: string
            description: "DEPRECATED - use schedules. Typical opening time of the network"
          duration:
            type: string
            description: "DEPRECATED - use schedules. Typical opening period duration of the network"
          timezone:
            type: string
            description: "Timezone of this network, used when operating with schedules"
            example: "Europe/Lisbon"
          newsURL:
            type: string
            description: "DEPRECATED - use announcements instead"
          lines:
            description: "IDs of lines pertaining to this network"
            type: array
            items:
              type: string
              example: "pt-ml-azul"
          stations:
            description: "IDs of stations pertaining to this network"
            type: array
            items:
              type: string
              example: "pt-ml-or"
          schedule:
            type: array
            items:
              $ref: "#/definitions/Schedule"
            description: "Schedules defining the opening time of this network"
      - $ref: "#/definitions/Localizable"
  PairConnection:
    type: object
    properties:
      service:
        type: string
        description: "ID of the external service in the UnderLX system"
        example: "posplay"
      serviceName:
        type: string
        description: "Human-friendly name of the external service"
        example: "PosPlay"
      creationTime:
        type: string
        format: date-time
        description: "Time of creation of this connection"
      extra:
        type: object
        description: "Extra service-specific information about the connection"
  POI:
    allOf:
      - type: object
        properties:
          id:
            type: string
            description: "Unique point of Interest ID in the UnderLX system"
            format: uuid
          type:
            type: string
            description: "Type/category of point of interest"
            enum:
              - dinning
              - police
              - fire-station
              - sports
              - school
              - university
              - library
              - airport
              - embassy
              - church
              - business
              - zoo
              - park
              - hospital
              - monument
              - museum
              - shopping-center
              - health-center
              - bank
              - viewpoint
              - casino
              - theater
              - show-room
              - organization
              - transportation-hub
              - public-space
              - government
              - market
              - public-service
              - institute
              - post-office
              - cemetery
              - hotel
          worldCoord:
            description: "Latitude-longitude pair describing the real world position of the point of interest"
            example: [38.744876, -9.138903]
            type: array
            items:
              type: number
              format: float
          webURL:
            description: "URL of 3rd-party web page associated with this point of interest"
            type: string
      - $ref: "#/definitions/Localizable"
  Station:
    type: object
    properties:
      id:
        type: string
        description: "Unique station ID in the UnderLX system"
        example: "pt-ml-pe"
      name:
        type: string
        description: "Human-friendly station name"
        example: "Praça de Espanha"
      altNames:
        description: "Alternative names that users may use when referring to this station"
        type: array
        items:
          type: string
          example: "Palhavã"
      tags:
        description: "List of tags that describe the station and its features, including connections to other transportation services, amenities and accessibilities"
        type: array
        items:
          $ref: "#/definitions/StationTag"
      lowTags:
        description: "List of lower-priority tags. The complete list of tags, without duplicates, can be obtained by simply appending `lowTags` to `tags`"
        type: array
        items:
          $ref: "#/definitions/StationTag"
      network:
        type: string
        description: "ID of the network this station belongs to"
        example: "pt-ml"
      lines:
        description: "IDs of lines serving this station"
        type: array
        items:
          type: string
          example: "pt-ml-azul"
      features:
        type: object
        description: "DEPRECATED - use `tags` and `lowTags`"
        properties:
          lift:
            type: boolean
          bus:
            type: boolean
          boat:
            type: boolean
          train:
            type: boolean
          airport:
            type: boolean
      lobbies:
        description: "IDs of the lobbies of this station"
        type: array
        items:
          type: string
          example: "pt-ml-pe-norte"
      pois:
        description: "IDs of the POIs associated with this station"
        type: array
        items:
          type: string
          format: uuid
      triviaURLs:
        description: "Maps locales to relative URLs of HTML files, containing trivia for this station.
        
        URLs are relative to the API endpoint. The HTML markup is simple, possibly including image tags"
        type: object
        additionalProperties:
          type: string
      connURLs:
        description: "Maps connection types (bike, boat, bus, park, train) to maps, that in turn, map locales to relative URLs of HTML files, which contain connection information for this station.
        
        URLs are relative to the API endpoint. The HTML markup is simple, possibly including image tags"
        type: object
        additionalProperties:
          type: object
          additionalProperties:
            type: object
      wiFiAPs:
        description: "Wi-Fi Acess Points present at this station. Used by S2LS, the Segvault Subway Location System."
        type: array
        items:
          type: object
          properties:
            bssid:
              description: "BSSID of the access point"
              type: string
              example: "24:a4:3c:04:1d:5b"
            line:
              description: "DEPRECATED"
              type: string
  StationTag:
    type: string
    enum:
      - a_baby
      - a_store
      - a_wc
      - a_wifi
      - c_airport
      - c_bike
      - c_boat
      - c_bus
      - c_parking
      - c_taxi
      - c_train
      - m_escalator_platform
      - m_escalator_surface
      - m_lift_platform
      - m_lift_surface
      - m_platform
      - m_stepfree
      - s_client
      - s_info
      - s_lostfound
      - s_navegante
      - s_ticket1
      - s_ticket2
      - s_ticket3
      - s_urgent_pass
  Stats:
    type: object
    properties:
      lineStats:
        type: object
        description: "Map containing statistics for each line, indexed by line ID"
        additionalProperties:
          type: object
          properties:
            availability:
              description: "Fraction of time this line operated without issues in the relevant time frame"
              type: number
              format: float
            avgDistDuration:
              description: "Average disturbance duration in the relevant time frame, in HH`h`mm`m`SS`s` format"
              type: string
      lastDisturbance:
        type: string
        format: date-time
        description: "Date-time of the end of last disturbance"
      curOnInTransit:
        type: integer
        description: "Approximate number of UnderLX users currently online and in transit. This number is always relative to the present moment, independently of the request parameters"
  Transfer:
    type: object
    properties:
      station:
        type: string
        description: "ID of the station where this transfer takes place"
        example: "pt-ml-am"
      from:
        type: string
        description: "ID of the line this transfer originates from"
        example: "pt-ml-verde"
      to:
        type: string
        description: "ID of the line this transfer ends at"
        example: "pt-ml-vermelha"
      typS:
        type: integer
        description: "Typical seconds. The average time it takes for a user to go through this transfer"
        example: 463
  Trip:
    type: object
    properties:
      id:
        type: string
        format: uuid
        description: "Trip UUID as generated by the client"
      startTime:
        type: string
        format: date-time
        description: "Date-time at which the trip started"
      endTime:
        type: string
        format: date-time
        description: "Date-time at which the trip ended"
      submitTime:
        type: string
        format: date-time
        description: "Date-time at which the trip was submitted"
      editTime:
        type: string
        format: date-time
        description: "Date-time at which the trip was edited. Invalid if `edited` is false"
      edited:
        type: boolean
        description: "Whether the trip was edited"
      userConfirmed:
        type: boolean
        description: "Whether the trip data was confirmed by the user"
      uses:
        description: "Station uses defining the path the user took"
        type: array
        items:
          $ref: "#/definitions/StationUse"
  StationUse:
    type: object
    properties:
      station:
        type: string
        example: "pt-ml-am"
        description: "ID of the station the user used"
      entryTime:
        type: string
        format: date-time
        description: "Date-time at which the user entered the station"
      leaveTime:
        type: string
        format: date-time
        description: "Date-time at which the user left the station"
      type:
        type: string
        enum:
          - NETWORK_ENTRY
          - NETWORK_EXIT
          - INTERCHANGE
          - GONE_THROUGH
          - VISIT
        description: "The type of station use"
      manual:
        type: boolean
        description: "Whether this use is part of a user-made edit of a trip"
      sourceLine:
        type: string
        description: "ID of the line the line change originated from. Only valid if `type` is INTERCHANGE"
      targetLine:
        type: string
        description: "ID of the target line for the line change. Only valid if `type` is INTERCHANGE"

  Map:
    type: object
    description: "Maps are used to indicate clients which human-friendly transit maps exist, how to obtain and how to render them.
    
    Do not confuse maps with datasets or networks. Maps are not explicitly associated to either of those, but dataset versioning indirectly controls map updates, in the sense that the client must invalidate the map cache when updating datasets."
    discriminator: type
    required:
      - type
    properties:
      type:
        type: string
        enum: [world-map, html]
  world-map:
    title: "MapWorldMap"
    allOf:
      - $ref: "#/definitions/Map"
  html:
    title: "MapHTML"
    allOf:
      - $ref: "#/definitions/Map"
      - type: object
        properties:
          url:
            type: string
            description: "URL of the HTML file containing the map. If the URL is relative, it is relative to the API endpoint"
          cache:
            type: boolean
            description: "Whether the map should be cached by the client. If false, the client must navigate to URL every time the map is displayed"
          wideViewport:
            type: boolean
            description: "Specific to clients that display the map in an Android WebView, this specifies whether the WebView should have a wide viewport."

  Gateway:
    type: object
    description: "Gateways are UnderLX's form of real-time communication between server and clients.
   
    They are used to support communication paradigms that are poorly supported by conventional HTTP, such as publish-subscribe or unreliable connections (as in UDP)."
    discriminator: protocol
    required:
      - protocol
    properties:
      protocol:
        type: string
        enum: [mqtt]
  mqtt:
    title: MQTTGateway
    allOf:
      - $ref: "#/definitions/Gateway"
      - type: object
        properties:
          host:
            type: string
            example: "api.underlx.com"
            description: "Host of the MQTT broker"
          port:
            type: integer
            description: "Port of the MQTT broker"
          pVer:
            type: string
            description: "MQTT protocol version"
            example: "3.1.1"
          tls:
            type: boolean
            description: "Whether the broker expects TLS connections"
  
  Localizable:
    type: object
    properties:
      mainLocale:
        type: string
        example: "pt"
        description: "Key of the name to use in the `names` map, when no specific translation is available for the current locale"
      names:
        type: object
        description: "Map of language codes to names providing name translations for each locale. If a translation is not available for the relevant locale, the one specified by `mainLocale` should be used."
        additionalProperties:
          type: string
        example:
          pt: "Azul"
          en: "Blue"
          fr: "Bleue"

  Schedule:
    type: object
    properties: 
      holiday:
        type: boolean
        description: "Whether this schedule applies to holidays, or is an exception. See `day` for more information."
      day:
        type: integer
        description: "Day of week (0-6: Sunday-Saturday) or day of year (January 1st: 1; December 31st: 365/366) this schedule applies to.
        
        - If `holiday` is false, this schedule applies to the day of the week specified by `day`;

        - If `holiday` is true and `day` is zero, this schedule applies to holidays, as defined in the holidays list of the relevant network;

        - If `holiday` is true and `day` is not zero, this is a one-off schedule for a specific day of the year, and `day` should be interpreted as the day of the year. If we are past that day in the current year, this should be interpreted as the Nth day of the next year."
      open:
        type: boolean
        description: "Whether the lobby/line/network will be open on this day"
      openTime:
        type: string
        description: "Start of the opening period for this day, in HH`:`mm`:`SS format. The timezone is that of the relevant transit network"
        example: "06:30:00"
      duration:
        type: string
        description: "Duration of the opening period for this day, in HH`h`mm`m`SS`s` format. May extend past the midnight of this day"
        example: "18h30m0s"
      

  GenericUnauthorizedResponse:
    type: object
    properties:
      success:
        type: boolean
        example: false
      errors:
        type: array
        items:
          type: string
          example: "Unauthorized"
responses:
  Unauthorized:
    description: "unauthorized: invalid credentials or missing authentication headers"

securityDefinitions:
  apiPair:
    type: basic
    
externalDocs:
  description: "UnderLX Developer Portal"
  url: "https://developer.underlx.com/"