car-park.swagger.yaml

swagger: "2.0"

info:
  version: 0.1.0
  title: Car parks
  x-logo:
    url: "https://developer.tripgo.com/img/tripgo-api-logo-color.svg"
  description:
    Work-in-progress proposal for car park operators to connect their services to SkedGo's platform.

paths:
  /carparks:
    get:
      description: |
        Provides a list of all car parks (regardless of whether they are currently available or not), including optionally (but highly recommended!) information on prices. Required method.
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/CarParkInfo'

definitions:
  RGBColor:
    properties:
      red:
        type: integer
        minimum: 0
        maximum: 255
      blue:
        type: integer
        minimum: 0
        maximum: 255
      green:
        type: integer
        minimum: 0
        maximum: 255
    required:
      - red
      - blue
      - green

  ImageObject:
      description: Image stored remotely
      externalDocs:
        url: "http://schema.org/ImageObject"
      properties:
        caption:
          type: string
          description: The caption for this object
        contentUrl:
          type: string
          description: URL to download image
        fileFormat:
          type: string
          description: Media type of image
          externalDocs:
            url: "http://schema.org/fileFormat"
        width:
          type: integer
          description: Width in pixels
        height:
          type: integer
          description: Height in pixels
      required:
        - contentUrl

  CarParkInfo:
    externalDocs:
      url: 'https://fiware-datamodels.readthedocs.io/en/latest/Parking/OffStreetParking/doc/spec/index.html'
    properties:
      id:
        type: string
      name:
        type: string
        description: Car park name
        externalDocs:
          url: "http://schema.org/name"
      address:
        type: string
        externalDocs:
          url: "http://schema.org/address"
      coordinates:
        $ref: '#/definitions/GeoCoordinates'
      provider:
        $ref: '#/definitions/CompanyInfo'
      totalSpotNumber:
        description: Static information of total spaces
        type: integer
      avalableSpotNumber:
        description: Real-time information of total spaces
        type: integer
      timestamp:
        type: string
        format: date-time
        description: Timestamp `availableSpotNumber` got recorded in ISO8601 format
      openingHours:
        type: array
        items:
          $ref: '#/definitions/OpeningHours'
        example:
          - ["Mo-Fr 06:30-21:00", "Sa 08:00-14:00"]
      pricingTable:
          description: The pricing schemas used. Free is assummed if this array is empty.
          type: array
          items:
            $ref: '#/definitions/PricingTable'
      restrictions:
        $ref: '#/definitions/Restrictions'
      entrances:
        type: array
        items:
          $ref: '#/definitions/Entrance'
      source:
        $ref: '#/definitions/DataSourceAttribution'
      info:
        type: string
        description: Additional information about this car park
      maxHeightInMetres:
        type: number
        minimum: 0
        description: Maximum height allowed
      link:
        type: string
        description: Specific URL which identifies this car park
      avalability:
        $ref: '#/definitions/RealtimeStatus'
    required:
      - id
      - coordinates
      - name

  OpeningHours:
    type: string
    description: Opening times period
    externalDocs:
     url: "http://schema.org/openingHours"
    example:
      - "Mo-Su" # all week
      - "Mo-Fr" # all day from Mondays to Fridays
      - "Mo-Su 08:00-21:00" # all week from 8:00 to 21:00
      - "Tu,Th 08:00-12:00" # Tuesdays and Thursdays from 8:00 to 12:00

  GeoCoordinates:
    description: The geographic coordinates of a place or event.
    externalDocs:
      url: "http://schema.org/GeoCoordinates"
    properties:
      latitude:
        type: number
        description: Latitude information
      longitude:
        type: number
        description: Longitude information
      address:
        type: string
        description: Physical address of the item.
      # other fields that could be added:
      #  - addressCountry
      #  - postalcode
      #  - elevation
    required:
      - latitude
      - longitude

  CompanyInfo:
    externalDocs:
      url: 'https://schema.org/provider'
    properties:
      name:
        type: string
      address:
        type: string
      phone:
        type: string
      website:
        type: string
      logos:
        type: array
        items:
          $ref: '#/definitions/ImageObject'
      color:
        $ref: '#/definitions/RGBColor'

    required:
      - name

  DataSourceAttribution:
    description:
      Information on how data should get attributed. When present, this needs to get displayed on relevant screens / views.
    properties:
      provider:
        $ref: '#/definitions/CompanyInfo'
      disclaimer:
        type: string
        description: Longer disclaimer that should be displayed for this provider
    required:
      - provider

  PricingTable:
    properties:
      title:
        type: string
        description: descriptive fare title
      category:
        type: string
        description: additional informatinon in case this pricing applies to a specif group, like 'DISABLED'.
      times:
        $ref: '#/definitions/OpeningHours'
      freeDuringOutHours:
        type: boolean
        description: if true, pricing is free when car park is closed.
      currency:
        type: string
      prices:
        type: array
        items:
          $ref: '#/definitions/Price'
    required:
      - times
      - currency
      - prices
    example:
      times: 06:00 - 22:00
      title: Regular fare
      currency: AUD
      prices:
        - maxDurationInMinutes: 60
          amount: 20
        - type: time
          maxDurationInMinutes: 120
          amount: 32
        - type: additional
          maxDurationInMinutes: 60
          amount: 10
        - type: daytime
          amount: 56

  Price:
    type: object
    properties:
      type:
        type: string
        description: Fare type. Could be 'time' based or not. The 'additional' type refers to additional minutes defined on $maxDurationInMinutes
        enum: [time, additional, daytime, minimum, maximun, evening, overnight]
      amount:
        type: number
        description: price in local curreny.
      maxDurationInMinutes:
        type: integer
        minimum: 0
        description: maximun duration for this price in minutes
      extraArgs:
        type: string
        description: additional information which chould be needed.
    required:
      - amount

  Restrictions:
    description: Information about the car park restrictions.
    properties:
      maxStayInMinutes:
        description: Maximun stay time in minutes
        type: integer
        minimum: 0
      noRestrictionWhenClosed:
        description: If this is `true`, the restrictions applies only during the time zone defined in `openingHours`
        type: boolean
      allowedOnly:
        description: Only the vehicles which satisfy these requirements could stay
        type: array
        items:
          type: string
          enum:
            - SUBSCRIBERS
            - VISITORS
            - CUSTOMERS
            - PERMIT_HOLDERS
            - EVENTS
            - VALET
            - DISABLED
            - COACH
            - MOTORCYCLES
      notAllowed:
        description: The vehicle types which are not allowed to stay
        type: array
        items:
          type: string
          enum:
            - SUVS
            - LPG_CARS
    example:
      maxStayInMinutes: 120
      noRestrictionWhenClosed: true
      allowedOnly: CUSTOMERS

  Entrance:
    description: Information about the car park entrance.
    properties:
      type:
        description: Entrance type identifier
        type: string
        enum:
            - ENTRANCE_EXIT
            - ENTRANCE_ONLY
            - EXIT_ONLY
            - PEDESTRIAN
            - DISABLED_PEDESTRIAN
            - PERMIT
      address:
        type: string
      lat:
        type: number
        description: Latitude
      lng:
        type: number
        description: Longitude
    required:
      - type
      - lat
      - lng

  RealtimeStatus:
    description: Realtime status information.
    properties:
      isOpen:
        type: boolean
        description: true if car park is open today.
      totalSpaces:
        type: integer
        minimum: 0
        description: Parking spots which could be used.
      availableSpaces:
        type: integer
        minimum: 0
        description: Available parking spots which are free now.
      opens:
        type: string
        description: Opening time.
      closes:
        type: string
        description: Closing time.
      lastUpdated:
        type: string
        format: date-time
        description: Last updated time in ISO 8601 format.
      source:
        $ref: '#/definitions/CompanyInfo'
    required:
      - availableSpaces
      - lastUpdated
    example:
      - isOpen: true
        lastUpdated: '2018-05-23T12:52:02Z'
        opens: '00:00'
        availableSpaces: 19
        totalSpaces": 61
        closes: '24:00'