swagger: '2.0'
info:
  version: 2.0.4
  title: Park and Ride API
  description: >-
    This API can be used to receive information about Park and Ride parking
    sites and their availability.
schemes:
  - https
paths:
  '/vrr-api/rest/pr/site':
    get:
      tags:
        - Park and Ride API
      description: Find all available parking sites
      security:
        - ApiKey: []
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: ok
          schema:
            type: array
            items:
              $ref: '#/definitions/SiteSummary'
        '400':
          description: Bad Request.
        '401':
          description: Authorization required.
        '404':
          description: Not found.
          
  '/vrr-api/rest/pr/site/{id}/availability':
    get:
      tags:
        - Park and Ride API
      description: Get availability information of the parking slots for the given site id within the specified timeframe. Returns only the single most recent information if the query parameters "from" and "to" are not specified.
      security:
        - ApiKey: []
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: integer
          required: true
          description: The id of the Park and Ride site to return the availability of.
        - in: query
          name: from
          type: string
          required: false
          description: Optional "From" filter - Timestamp (ISO 8601) UTC, i.e. 2019-03-31T16:45:00.000Z
        - in: query
          name: to
          type: string
          required: false
          description: Optional "To" filter - Timestamp (ISO 8601) UTC, i.e. 2019-03-31T16:45:00.000Z
        - in: query
          name: place
          type: string
          required: false
          description: Optional "Place" filter- The place of the stop, i.e. "Dortmund"
        - in: query
          name: ifopt
          type: string
          required: false
          description: Optional "ifopt" filter -  The ifopt of the stop, i.e. "de:05154:35102"
        - in: query
          name: stopName
          type: string
          required: false
          description: Optional "StopName" filter - The name of a stop, i.e. "Dortmund Hbf"
        - in: query
          name: stopNameWithoutLocality
          type: string
          required: false
          description: Optional "StopNameWithoutLocality" filter - The name of a stop without locality, i.e. "Hbf"
        - in: query
          name: osm
          type: string
          required: false
          description: Optional "OSM" filter - area within which the stop must be located. Area must be specified by a set of geo locations encoded as string input.<br> longitude and latitude values must be separated by a single semicolon ;  i.e. 13.703963;15.374694<br> coordinates must be separated by two semicolons ;; i.e. 13.703963;15.374694;;13.703984;15.377439<br><br>
            Input Pattern:<br>
            longitude1;latitude1;;longitude2;latitude2;;longitude3;latitude3;;longitude4;lattitude4
            <br><br>
            Example Value<br>
            13.703963;15.374694;;13.703984;15.377439;;13.698338;15.374908;;13.698495;115.37755
      responses:
        '200':
          description: ok
          schema:
            type: array
            items:
              $ref: '#/definitions/Availability'
        '400':
          description: Bad Request.
        '401':
          description: Authorization required.
        '404':
          description: Not found.
       
  '/vrr-api/rest/pr/site/all/availability':
    get:
      tags:
        - Park and Ride API
      description: Get availability information of the parking slots for all site sites within the specified timeframe. Returns only the single most recent information if the query parameters "from" and "to" are not specified.
      security:
        - ApiKey: []
      produces:
        - application/json
      parameters:
        - in: query
          name: from
          type: string
          required: false
          description: Optional "From" filter - Timestamp (ISO 8601) UTC, i.e. 2019-03-31T16:45:00.000Z
        - in: query
          name: to
          type: string
          required: false
          description: Optional "To" filter - Timestamp (ISO 8601) UTC, i.e. 2019-03-31T16:45:00.000Z
        - in: query
          name: place
          type: string
          required: false
          description: Optional "Place" filter- The place of the stop, i.e. "Dortmund"
        - in: query
          name: ifopt
          type: string
          required: false
          description: Optional "ifopt" filter -  The ifopt of the stop, i.e. "de:05154:35102"
        - in: query
          name: stopName
          type: string
          required: false
          description: Optional "StopName" filter - The name of a stop, i.e. "Dortmund Hbf"
        - in: query
          name: stopNameWithoutLocality
          type: string
          required: false
          description: Optional "StopNameWithoutLocality" filter - The name of a stop without locality, i.e. "Hbf"
        - in: query
          name: osm
          type: string
          required: false
          description: Optional "OSM" filter - area within which the stop must be located. Area must be specified by a set of geo locations encoded as string input.<br> longitude and latitude values must be separated by a single semicolon ;  i.e. 13.703963;15.374694<br> coordinates must be separated by two semicolons ;; i.e. 13.703963;15.374694;;13.703984;15.377439<br><br>
            Input Pattern:<br>
            longitude1;latitude1;;longitude2;latitude2;;longitude3;latitude3;;longitude4;lattitude4
            <br><br>
            Example Value<br>
            13.703963;15.374694;;13.703984;15.377439;;13.698338;15.374908;;13.698495;115.37755
      responses:
        '200':
          description: ok
          schema:
            type: array
            items:
              $ref: '#/definitions/Site'
        '400':
          description: Bad Request.
        '401':
          description: Authorization required.
        '404':
          description: Not found.

securityDefinitions:
  ApiKey:
    type: apiKey
    name: x-api-key
    in: header
    
definitions:
  Stop:
    title: Stop
    type: object
    properties:
      ifopt:
        type: string
        description: The global ID of the stop
      name:
        type: string
        description: The name of the stop
      place:
        type: string
        description: The place of the stop

  SiteSummary:
    title: SiteSummary
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: integer
        description: The unique id of the parking site.
      name:
        type: string
        description: The name of the parking site.
      provider:
        type: string
        description: The operator of this parking site.
      latitude:
        type: number
        description: The latitude of this parking site.
      longitude:
        type: number
        description: The longitude of this parking site.
      stop:
        $ref: '#/definitions/Stop'

  Site:
    title: Site
    allOf: 
      - $ref: '#/definitions/SiteSummary'
      - type: object
      - properties:
          availability:
            type: array
            items:
              $ref: '#/definitions/Availability'
   
  Availability:
    title: Availability
    type: object
    required:
      - timestamp
      - standardSlotsTotal
      - standardSlotsFree
      - standardSlotsOccupied
      - disabledSlotsTotal
      - disabledSlotsFree
      - diasabledSlotsOccupied
      - womanSlotsTotal
      - womanSlotsFree
      - womanSlotsOccupied
      - familySlotsTotal
      - familySlotsFree
      - familySlotsOccupied
      - fee
    properties:
      timestamp:
        type: string
        description: Timestamp of last change (ISO 8601) UTC, i.e. 2019-03-31T16:45:00.000Z
      standardSlotsTotal:
        type: integer
        description: The total amount of standard, non special parking slots.
      standardSlotsFree:
        type: integer
        description: The amount of free standard, non special parking slots.
      standardSlotsOccupied:
        type: integer
        description: The amount of occupied standard, non special parking slots.
      disabledSlotsTotal:
        type: integer
        description: The total amount of parking slots for disabled people.
      disabledSlotsFree:
        type: integer
        description: The amount of free parking slots for disabled people.
      diasabledSlotsOccupied:
        type: integer
        description: The amount of occupied parking slots for disabled people.
      womanSlotsTotal:
        type: integer
        description: The total amount of parking slots for woman.
      womanSlotsFree:
        type: integer
        description: The amount of free parking slots for woman.
      womanSlotsOccupied:
        type: integer
        description: The amount of occupied parking slots for woman.
      familySlotsTotal:
        type: integer
        description: The total amount of family or mother child parking slots.
      familySlotsFree:
        type: integer
        description: The amount of free family or mother child parking slots.
      familySlotsOccupied:
        type: integer
        description: The amount of occupied family or mother child parking slots.
      fee:
        type: boolean
        description: Indicates whether fee-based or not. If it is null in the answer, there is no information about it.