swagger: "2.0"
schemes:
  - https
  - http
host: api.deutschebahn.com
basePath: /freeplan/v1
info:
  contact:
    email: DBOpenData@deutschebahn.com
    name: DBOpenData
    url: https://developer.deutschebahn.com/store/
  description: |-
    A RESTful webservice to request a railway journey - FREE plan with restricted access (max. 10 requests per minute). Please ignore the message in the API Console about the access token.

    Register to use an less restricted version, which requires an access token.
  license:
    name: DB Data Portal
    url: http://data.deutschebahn.com/pages/nutzungsbedingungen
  termsOfService: http://data.deutschebahn.com/nutzungsbedingungen.html
  title: Fahrplan-Free
  version: v1
  x-apisguru-categories:
    - transport
    - open_data
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://pbs.twimg.com/profile_images/591140150413025280/Cjcqjl2J.png
  x-origin:
    - format: swagger
      url: https://developer.deutschebahn.com/store/api-docs/DBOpenData/Fahrplan-Free/v1
      version: "2.0"
  x-providerName: deutschebahn.com
  x-serviceName: fahrplan
consumes:
  - application/json
produces:
  - application/json
paths:
  "/arrivalBoard/{id}":
    get:
      description: Get arrival board at a given location at a given daten and time.
      parameters:
        - description: Id of location. Use attribute 'id' from the result of 'location'
          in: path
          name: id
          required: true
          type: string
        - description: "Date and time in ISO-8601 format, yyyy-mm-ddThh:mm:ss, example: 2017-04-01 or 2017-04-01T10:30"
          in: query
          name: date
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: arrival board
          schema:
            $ref: "#/definitions/BoardResponse"
        "400":
          description: Invalid date/time specification.
          schema:
            $ref: "#/definitions/ErrorModel"
        "500":
          description: Internal Server Error.
          schema:
            $ref: "#/definitions/ErrorModel"
        "503":
          description: The service has been disabled temporarily.
          schema:
            $ref: "#/definitions/ErrorModel"
      summary: Get arrival board of a location
      x-auth-type: None
      x-throttling-tier: 10_per_minute
  "/departureBoard/{id}":
    get:
      description: Get departure board at a given location at a given daten and time.
      parameters:
        - description: Id of a location. Use attribute 'id' from the result of 'location'
          in: path
          name: id
          required: true
          type: string
        - description: "Date and time in ISO-8601 format, yyyy-mm-ddThh:mm:ss, example: 2017-04-01 or 2017-04-01T10:30"
          in: query
          name: date
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: departure board
          schema:
            $ref: "#/definitions/BoardResponse"
        "400":
          description: Invalid date/time specification.
          schema:
            $ref: "#/definitions/ErrorModel"
        "500":
          description: Internal Server Error.
          schema:
            $ref: "#/definitions/ErrorModel"
        "503":
          description: The service has been disabled temporarily.
          schema:
            $ref: "#/definitions/ErrorModel"
      summary: Get departure board of a location
      x-auth-type: None
      x-throttling-tier: 10_per_minute
  "/journeyDetails/{id}":
    get:
      description: Retrieve details of a journey. The id of journey should come from an arrival board or a departure board.
      parameters:
        - description: Id of a journey. Use attribute 'detailsId' from the result of  'arrivalBoard' or 'departureBoard'
          in: path
          name: id
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: journey details, locations of a journey
          schema:
            $ref: "#/definitions/JourneyResponse"
        "500":
          description: Internal Server Error.
          schema:
            $ref: "#/definitions/ErrorModel"
        "503":
          description: The service has been disabled temporarily.
          schema:
            $ref: "#/definitions/ErrorModel"
      summary: Get details about a single journey
      x-auth-type: None
      x-throttling-tier: 10_per_minute
  "/location/{name}":
    get:
      description: Get information about locations matching the given name or name fragment
      parameters:
        - description: Name or name fragment of a location
          in: path
          name: name
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: location information
          schema:
            $ref: "#/definitions/LocationResponse"
        "500":
          description: Internal Server Error.
          schema:
            $ref: "#/definitions/ErrorModel"
        "503":
          description: The service has been disabled temporarily.
          schema:
            $ref: "#/definitions/ErrorModel"
      summary: Get location information
      x-auth-type: None
      x-throttling-tier: 10_per_minute
definitions:
  Board:
    properties:
      boardId:
        description: ""
        type: string
      dateTime:
        description: ""
        type: string
      detailsId:
        description: ""
        type: string
      name:
        description: Name of train
        type: string
      origin:
        description: ""
        type: string
      stopId:
        description: ""
        type: string
      stopName:
        description: ""
        type: string
      track:
        description: ""
        type: string
      type:
        description: ""
        type: string
    required:
      - name
      - type
      - boardId
      - stopId
      - stopName
      - dateTime
      - origin
      - track
      - detailsId
    type: object
  BoardResponse:
    properties:
      boards:
        items:
          $ref: "#/definitions/Board"
        minItems: 1
        type: array
        uniqueItems: true
    required:
      - boards
    type: object
  ErrorModel:
    properties:
      code:
        type: integer
      internal_code:
        type: integer
      internal_message:
        type: string
      message:
        type: string
    required:
      - code
      - message
    type: object
  JourneyResponse:
    properties:
      train_locs:
        items:
          $ref: "#/definitions/TrainLocation"
        minItems: 1
        type: array
        uniqueItems: true
    required:
      - train_locs
    type: object
  Location:
    properties:
      id:
        description: "id of location (eva-number), example: 8000105"
        type: string
      lat:
        description: "latitude, example: 50.107149"
        type: number
      lon:
        description: "longitude, example: 8.663785"
        type: number
      name:
        description: "Name of location, example: Frankfurt(Main)Hbf"
        type: string
    required:
      - name
      - lon
      - lat
      - id
    type: object
  LocationResponse:
    properties:
      locations:
        items:
          $ref: "#/definitions/Location"
        minItems: 1
        type: array
        uniqueItems: true
    required:
      - locations
    type: object
  TrainLocation:
    properties:
      arrTime:
        description: ""
        type: string
      depTime:
        description: ""
        type: string
      lat:
        description: ""
        type: number
      lon:
        description: ""
        type: number
      operator:
        description: ""
        type: string
      stopId:
        description: ""
        type: string
      stopName:
        description: ""
        type: string
      train:
        description: ""
        type: string
      type:
        description: ""
        type: string
    required:
      - stopId
      - stopName
      - lat
      - lon
      - arrTime
      - depTime
      - train
      - type
      - operator
    type: object
