swagger: '2.0'
info:
  version: 2.0.4
  title: Bike and Ride API
  description: >-
    This API can be used to receive information about Bike and Ride sites and their availability.

schemes:
  - https
paths:
  '/vrr-api/rest/br/site':
    get:
      tags:
        - Bike and Ride API
      description: Find all available Bike and Ride 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/br/site/{id}/availability':
    get:
      tags:
        - Bike and Ride API
      description: Get availability information of the bike and ride 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 Bike 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. Witten
        - in: query
          name: ifopt
          type: string
          required: false
          description: Optional "Ifopt" filter - The global_id of the stop, i.e. de:05954:6316
        - in: query
          name: stopName
          type: string
          required: false
          description: Optional "StopName" filter - The name of the stop, i.e. Witten Bachstr.
        - in: query
          name: stopNameWithoutLocality
          type: string
          required: false
          description: Optional "StopNameWithoutLocality" filter - The alternative name of the stop, i.e. Bachstr.
        - 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/br/site/all/availability':
    get:
      tags:
        - Bike and Ride API
      description: Get availability information of the bike and ride slots for all 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. Witten
        - in: query
          name: ifopt
          type: string
          required: false
          description: Optional "Ifopt" filter - The global_id of the stop, i.e. de:05954:6316
        - in: query
          name: stopName
          type: string
          required: false
          description: Optional "StopName" filter - The name of the stop, i.e. Witten Bachstr.
        - in: query
          name: stopNameWithoutLocality
          type: string
          required: false
          description: Optional "StopNameWithoutLocality" filter - The alternative name of the stop, i.e. Bachstr.
        - 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 B+R site.
      name:
        type: string
        description: The name of the B+R site.
      provider:
        type: string
        description: The operator of this B+R site.
      latitude:
        type: number
        description: The latitude of this B+R site.
      longitude:
        type: number
        description: The longitude of this B+R 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
    properties:
      timestamp:
        type: string
        description: Timestamp of last change (ISO 8601) UTC, i.e. 2019-03-31T16:45:00.000Z
      inactive:
        type: integer
      defect:
        type: integer
      bookable:
        type: integer
      blocked:
        type: integer
      occupied:
        type: integer
      sum_boxes:
        type: integer
      url:
        type: string
        description: DeepLink to book a box using the unitId, without unitId null is returned