openapi.yaml

openapi: 3.1.0

info:
  description: API to search for OpenRailwayMap-vector
  contact:
    name: Hidde Wieringa
    email: openrailwaymap@hiddewieringa.nl
    url: https://github.com/hiddewie/OpenRailwayMap-vector
  license:
    identifier: GPL-2.0-or-later
    name: GNU General Public License v2.0 or later
  title: OpenRailwayMap API
  version: current

servers:
  - url: https://openrailwaymap.app
  - url: http://localhost:8000

tags:
  - name: search
    description: Search API
  - name: status
    description: Status API

externalDocs:
  description: GitHub
  url: https://github.com/hiddewie/OpenRailwayMap-vector#readme

paths:
  /api/status:
    get:
      operationId: status
      description: Status endpoint
      summary: Status endpoint
      tags:
        - status

  /api/replication_timestamp:
    get:
      operationId: replicationTimestamp
      description: The replication timestamp of the OpenStreetMap data
      summary: Replication endpoint
      tags:
        - replication
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  import_timestamp:
                    type: string
                    format: date-time
                    example: '2026-01-01T00:00:00Z'
                  replication_timestamp:
                    type: string
                    format: date-time
                    example: '2026-02-05T21:21:38Z'

  /api/facility:
    get:
      operationId: searchFacilities
      summary: Facility search
      description: |
        The facility endpoint returns detail of a facility (station, junction, yard, …) by its name or reference.
        
        The parameters q, name and ref are mutually exclusive.
        
        Reference is one of the supported facility reference tags, such as `railway:ref`, `uic_ref`, `ref:ibnr`, `ref:IFOPT`, `ref:EU:PLC` and others. See https://github.com/hiddewie/OpenRailwayMap-vector/edit/master/features/stations.yaml for the full list.
        
        It takes the first keyword of (name, ref) and the optional the operator to search for the data.
      tags:
        - search
      parameters:
        - name: q
          in: query
          schema:
            type: string
            example: Karlsruhe
          description: |
            search term (will be looked up in all `name=*` tags, `railway:ref=*`, `uic_ref=*`, `ref:ibnr`, `ref:IFOPT`, `ref:EU:PLC`, etc.)
        - name: name
          in: query
          schema:
            type: string
            example: Karlsruhe
          description: |
            search term (name search only)
        - name: ref
          in: query
          schema:
            type: string
            example: Gd
          description: |
            search by official facility reference number/code only
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 200
          description: maximum number of results
        - name: lang
          in: query
          schema:
            type: string
          required: false
          description: language to use for determining localized name
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    latitude:
                      type: number
                    longitude:
                      type: number
                    osm_ids:
                      type: array
                      items:
                        type: integer
                        description: |
                          OSM node ID
                    osm_types:
                      type: array
                      items:
                        type: string
                        enum:
                          - 'N'
                          - 'W'
                        description: |
                          The type of OSM object, same order as the IDs
                    name:
                      type: string
                      nullable: true
                    localized_name:
                      type: string
                      nullable: true
                      description: The localized name, if the `lang` parameter is given and present, otherwise equal to the name
                    railway:
                      type: string
                      nullable: true
                    station:
                      type: string
                      nullable: true
                    railway_ref:
                      type: string
                      nullable: true
                    uic_ref:
                      type: string
                      nullable: true
                    references:
                      type: object
                      nullable: true
                    operator:
                      type: array
                      items:
                        type: string
                    network:
                      type: array
                      items:
                        type: string
                    wikidata:
                      type: array
                      items:
                        type: string
                    wikimedia_commons:
                      type: array
                      items:
                        type: string
                    image:
                      type: array
                      items:
                        type: string
                    mapillary:
                      type: array
                      items:
                        type: string
                    wikipedia:
                      type: array
                      items:
                        type: string
                    note:
                      type: array
                      items:
                        type: string
                    description:
                      type: array
                      items:
                        type: string
                    rank:
                      type: integer
                      description: |
                        an importance rank calculated by taking the public transport route relations into account using this station/halt
                example:
                  - osm_ids:
                    - 5284961126
                    osm_types:
                      - "N"
                    name: Ostkreuz (Ringbahn)
                    localized_name: Ostkreuz (Ringbahn)
                    feature: station
                    state: present
                    station: light_rail
                    railway_ref: BOK
                    uic_ref: '8089028'
                    references:
                      uic: '8089028'
                      station: '4809'
                      railway-ref: BOK
                    operator:
                      - DB InfraGO AG
                    network:
                      - Verkehrsverbund Berlin-Brandenburg
                    wikidata:
                      - Q660045
                    wikimedia_commons: [ ]
                    wikimedia_commons_file: [ ]
                    image: [ ]
                    mapillary: [ ]
                    wikipedia:
                      - de:Bahnhof Berlin Ostkreuz
                    note:
                      - Bitte die 5 Nodes mit uic_ref in Bezug auf das Eisenbahn-Tagging so lassen und
                        auch die Position nicht verändern. Die beiden Stadtbahn-Nodes BOKS und BOKR werden
                        gerendert.
                    description: [ ]
                    latitude: 13.469119499999998
                    longitude: 52.50298119908801
                    rank: 100
                  - osm_ids:
                      - 29803428
                    osm_types:
                      - "N"
                    name: Rummelsburg
                    localized_name: Rummelsburg
                    feature: station
                    state: present
                    station: light_rail
                    railway_ref: BRH
                    uic_ref: '8089084'
                    references:
                      uic: '8089084'
                      parent: BOK
                      railway-ref: BRH
                    operator:
                      - DB Netz AG
                    network:
                      - Verkehrsverbund Berlin-Brandenburg
                    wikidata:
                      - Q15107132
                    wikimedia_commons: [ ]
                    wikimedia_commons_file: [ ]
                    image: [ ]
                    mapillary: [ ]
                    wikipedia:
                      - de:Bahnhof Berlin-Rummelsburg (S-Bahn)
                    note: [ ]
                    description: [ ]
                    latitude: 13.478366999999999
                    longitude: 52.501287999088085
                    rank: 0
                  - osm_ids:
                      - 257981401
                    osm_types:
                      - "N"
                    name: Frankfurter Allee
                    localized_name: Frankfurter Allee
                    feature: halt
                    state: present
                    station: light_rail
                    railway_ref: BFA
                    uic_ref: '8089013'
                    references:
                      uic: '8089013'
                      parent: BOK
                      station: '526'
                      railway-ref: BFA
                    operator:
                      - DB InfraGO AG
                    network:
                      - Verkehrsverbund Berlin-Brandenburg
                    wikidata:
                      - Q552872
                    wikimedia_commons: [ ]
                    wikimedia_commons_file: [ ]
                    image: [ ]
                    mapillary: [ ]
                    wikipedia:
                      - de:Bahnhof Berlin Frankfurter Allee
                    note:
                      - Die S-Bahn-Station hat keine Weichen und ist daher ein Haltepunkt.
                    description: [ ]
                    latitude: 13.4745707
                    longitude: 52.51493749908766
                    rank: 0
                  - osm_ids:
                      - 261941954
                    osm_types:
                      - "N"
                    name: Treptower Park
                    localized_name: Treptower Park
                    feature: station
                    state: present
                    station: light_rail
                    railway_ref: BTP
                    uic_ref:
                    references:
                      ibnr: '8089043'
                      parent: BOK
                      station: '6251'
                      railway-ref: BTP
                    operator:
                      - DB InfraGO
                    network:
                      - Verkehrsverbund Berlin-Brandenburg
                    wikidata:
                      - Q559274
                    wikimedia_commons: [ ]
                    wikimedia_commons_file: [ ]
                    image: [ ]
                    mapillary: [ ]
                    wikipedia:
                      - de:Bahnhof Berlin Treptower Park
                    note: [ ]
                    description: [ ]
                    latitude: 13.461829599999998
                    longitude: 52.49384909908831
                    rank: 0

        '400':
          description: |
            Bad request: invalid parameter values

  /api/milestone:
    get:
      operationId: searchMilestones
      summary: Milestone search
      description: |
        The milestone endpoint returns the position of milestones or other items such as signals or level crossings with a mapped position on a line.
        
        The API will return the features within a maximum distance of 10 km (hardcoded). The presence of an `operator=*` tag on the tracks is honoured, it will be used to
        distinguish reference numbers used by different infrastructure operators and/or in different countries.
        
        Mileage is read from the OSM tags `railway:position=*` and `railway:position:exact=*` with precedence of the exact mileage. The tracks must be tagged with a reference number (OSM tag `ref=*`).
        
        The tracks must not tagged with `service=*` (this condition does not apply to tracks with `usage=industrial/military/test`).
        
        Negative mileage is supported but gaps in mileage or duplicated positions (if railway lines are reroute) are not supported. For example, you cannot query for `16.8+200` or things like that.
      tags:
        - search
      parameters:
        - name: ref
          required: true
          in: query
          schema:
            type: string
            example: '4201'
          description: |
            reference number of the railway route the mileage refers to (in this case, route means lines as infrastructure, not the services using the tracks)
        - name: position
          required: true
          in: query
          schema:
            type: number
            example: 18.4
          description: |
            position (can be negative)
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 200
          description: maximum number of results
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    latitude:
                      type: number
                    longitude:
                      type: number
                    osm_id:
                      type: integer
                      description: |
                        OSM node ID
                    line_ref:
                      type: string
                      description: |
                        Reference number of the railway line the feature is located on.
                      nullable: true
                    milestone_ref:
                      type: string
                      nullable: true
                      description: |
                        Reference number of the feature.
                    operator:
                      type: string
                      description: |
                        operator of the infrastructure
                      nullable: true
                    railway:
                      type: string
                      description: |
                        type of the facility following Tagging rules (https://wiki.openstreetmap.org/wiki/OpenRailwayMap/Tagging#Operating_Sites), e.g. `milestone`, `level_crossing`, `signal`.
                      nullable: true
                    position:
                      type: string
                      description: |
                        Mileage of the feature
                      nullable: true
                    wikidata:
                      type: string
                      nullable: true
                    wikimedia_commons:
                      type: string
                      nullable: true
                    image:
                      type: string
                      nullable: true
                    mapillary:
                      type: string
                      nullable: true
                    wikipedia:
                      type: string
                      nullable: true
                    note:
                      type: string
                      nullable: true
                    description:
                      type: string
                      nullable: true
                example:
                  - description:
                    image:
                    latitude: 13.372542999999999
                    line_ref: '6020'
                    longitude: 52.471930899089024
                    mapillary:
                    milestone_ref:
                    note:
                    operator: DB InfraGO AG
                    osm_id: 11562536788
                    position: 22.7
                    railway: milestone
                    wikidata:
                    wikimedia_commons:
                    wikipedia:
                  - description:
                    image:
                    latitude: 13.3739671
                    line_ref: '6020'
                    longitude: 52.47137729908903
                    mapillary:
                    milestone_ref:
                    note:
                    operator: DB InfraGO AG
                    osm_id: 11558214672
                    position: 22.6
                    railway: milestone
                    wikidata:
                    wikimedia_commons:
                    wikipedia:
        '400':
          description: |
            Bad request: invalid parameter values

  /api/wikidata/{entity}:
    get:
      operationId: wikidataImage
      summary: Find the image from Wikidata
      description: |
        The Wikidata image endpoint returns the URL of the image thumbnail for a given Wikidata entity.
      tags:
        - wikidata
      parameters:
        - name: entity
          required: true
          in: path
          schema:
            type: string
            example: 'Q2655858'
          description: |
            The Wikidata entity ID
      responses:
        '404':
          description: Entity not found
          content:
            text/plain:
              schema:
                type: string
                description: The reason that the entity was not found
        '307':
          description: |
            Location of the Wikikdata thumbnail image

  /api/route/{osm_id}:
    get:
      operationId: route
      summary: Fetch a route
      description: |
        The route API returns the geometry and metadata of railway, tram, subway and lightrail OpenStreetMap route relations.
      tags:
        - route
      parameters:
        - name: osm_id
          required: true
          in: path
          schema:
            type: integer
            example: 324092
          description: |
            The OpenStreetMap route relation ID
      responses:
        '200':
          description: Success
          content:
            application/geo+json:
              schema:
                type: object
                description: |
                  A single GeoJSON feature containing the geometry and features of the route
                example:
                  id: 64050
                  type: Feature
                  geometry:
                    type: 'MultiLineString'
                    coordinates: [[[5.9004266, 51.985173599], [5.900491, 51.985163999]]]
                  properties:
                    to: 'S Spindlersfeld'
                    ref: 'S47'
                    from: 'S Hermannstraße'
                    name: 'S47: S Hermannstraße => S Spindlersfeld'
                    type: 'light_rail'
                    brand: null
                    color: '#BA8A4D'
                    osm_id: 64050
                    operator: 'S-Bahn Berlin GmbH'
        '404':
          description: |
            The route could not be found