openapi: "3.0.3"
info:
  title: FDSN Station Web Service
  description: >-
    API documentation of the FDSNWS Station service which provides access to
    inventory metadata.
  termsOfService: https://www.orfeus-eu.org/data/eida/webservices/
  version: 1.1.0
servers:
  - url: http://rdsa.knmi.nl/fdsnws/station/1
tags:
  - name: Station
externalDocs:
  description: API Documentation
  url: http://www.fdsn.org/webservices/fdsnws-station-1.1.pdf
paths:
  /query:
    get:
      tags:
        - Station
      summary: Query inventory metadata
      parameters:
        - name: starttime
          in: query
          description: Limit results to time series samples on or after the specified start time.
          example: '2020-01-01'
          schema:
            type: string
            format: date-time
        - name: endtime
          in: query
          description: Limit results to time series samples on or before the specified end time.
          example: '2020-01-02T00:06:00'
          schema:
            type: string
            format: date-time
        - name: network
          in: query
          description: >-
            Select one or more network codes. Can be FDSN network codes or data center defined
            codes. Multiple codes are comma-separated.
          example: NL
          schema:
            type: string
        - name: station
          in: query
          description: Select one or more FDSN station codes. Multiple codes are comma-separated.
          example: HGN
          schema:
            type: string
        - name: location
          in: query
          description: >-
            Select one or more FDSN location identifiers. Multiple identifiers are
            comma-separated. As a special case "--" (two dashes) will be translated
            to a string of two space characters to match blank location IDs.
          example: '00'
          schema:
            type: string
        - name: channel
          in: query
          description: Select one or more FDSN channel codes. Multiple codes are comma-separated.
          example: BHZ
          schema:
            type: string
        - name: startbefore
          in: query
          description: Limit to metadata epochs starting before specified time.
          schema:
            type: string
            format: date-time
        - name: startafter
          in: query
          description: Limit to metadata epochs starting after specified time.
          schema:
            type: string
            format: date-time
        - name: endbefore
          in: query
          description: Limit to metadata epochs ending before specified time.
          schema:
            type: string
            format: date-time
        - name: endafter
          in: query
          description: Limit to metadata epochs ending after specified time.
          schema:
            type: string
            format: date-time
        - name: minlatitude
          in: query
          description: Limit to stations with a latitude larger than or equal to the specified minimum.
          schema:
            type: number
            format: float
            default: -90.0
        - name: maxlatitude
          in: query
          description: Limit to stations with a latitude smaller than or equal to the specified maximum.
          schema:
            type: number
            format: float
            default: 90.0
        - name: minlongitude
          in: query
          description: Limit to stations with a longitude larger than or equal to the specified minimum.
          schema:
            type: number
            format: float
            default: -180.0
        - name: maxlongitude
          in: query
          description: Limit to stations with a longitude smaller than or equal to the specified maximum.
          schema:
            type: number
            format: float
            default: 180.0
        - name: latitude
          in: query
          description: Specify the latitude to be used for a radius search.
          schema:
            type: number
            format: float
        - name: longitude
          in: query
          description: Specify the longitude to be used for a radius search.
          schema:
            type: number
            format: float
        - name: maxradius
          in: query
          description: >-
            Limit results to stations within the specified maximum number of degrees from the
            geographic point defined by the latitude and longitude parameters.
          schema:
            type: number
            format: float
        - name: minradius
          in: query
          description: >-
            Limit results to stations within the specified minimum number of degrees from the
            geographic point defined by the latitude and longitude parameters.
          schema:
            type: number
            format: float
        - name: level
          in: query
          description: Specify the level of detail for the results.
          schema:
            type: string
            format: string
            default: station
            enum:
              - network
              - station
              - channel
              - response
        - name: format
          in: query
          description: Specify format of result.
          schema:
            type: string
            default: xml
            enum:
              - xml
              - sc3ml
              - text
              - json
        - name: includerestricted
          in: query
          description: Specify if results should include information for restricted stations.
          schema:
            type: boolean
            format: boolean
            default: true
            enum:
              - true
              - false
        - name: nodata
          in: query
          description: Select status code for "no data".
          schema:
            type: string
            default: '204'
            enum:
              - '204'
              - '404'
      responses:
        '200':
          description: >-
            The request was successful and has returned plain text in the
            corresponding format.
          content:
            application/xml: {}
            text/plain: {}
            application/json:
              schema:
                $ref: '#/components/schemas/StationCollection'
        '204':
          description: The request returns no content.
          content: {}
        '400':
          description: 'The request was bad, check the filled in parameters.'
          content: {}
        '401':
          description: The request requires user authentication.
          content: {}
        '403':
          description: >-
            Forbidden: 'The server understood the request, but is refusing to
            fulfill it.'
          content: {}
        '404':
          description: >-
            Not Found: The server has not found anything matching the
            Request-URL.
          content: {}
        '413':
          description: >-
            Request Entity Too Large: The request entity is larger than the
            server is willing or able to process.
          content: {}
        '414':
          description: >-
            Request-URL Too Long: The request-URL is longer than the server is
            willing to interpret.
          content: {}
        '500':
          description: >-
            Internal Server Error: The server encountered an unexpected
            condition which prevented it from fulfilling the request.
          content: {}
        '503':
          description: >-
            Service Unavailable: The server is currently unable to handle the
            request due to a temporary overloading or maintenance of the server.
          content: {}
    post:
      tags:
        - Station
      summary: Query inventory metadata
      description: >-
        A plain-text file containing a selection list can be sent to the
        service. The contents of this message may contain multiple streams and
        traces to be downloaded. Option-value pairs are indicated once per
        request at the top of the message followed by a number of lines that
        contain SEED stream identifiers delimited by a space, followed by the
        trace starttime and endtime. Empty fields are marked by an asterisk.
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              example: |
                CH HASLI * BHZ 2020-01-01 2020-01-02
              type: string
              format: binary
      responses:
        '200':
          description: >-
            The request was successful and has returned plain text in the
            requested format.
          content:
            application/xml: {}
            text/plain: {}
        '204':
          description: The request returns no content.
          content: {}
        '400':
          description: 'The request was bad, check the filled in parameters.'
          content: {}
        '401':
          description: The request requires user authentication.
          content: {}
        '403':
          description: >-
            Forbidden: The server understood the request, but is refusing to
            fulfill it.
          content: {}
        '404':
          description: >-
            Not Found: The server has not found anything matching the
            Request-URL.
          content: {}
        '413':
          description: >-
            Request Entity Too Large: The request entity is larger than the
            server is willing or able to process.
          content: {}
        '414':
          description: >-
            Request-URL Too Long: The request-URL is longer than the server is
            willing to interpret.
          content: {}
        '500':
          description: >-
            Internal Server Error: The server encountered an unexpected
            condition which prevented it from fulfilling the request.
          content: {}
        '503':
          description: >-
            Service Unavailable: The server is currently unable to handle the
            request due to a temporary overloading or maintenance of the server.
          content: {}
  /version:
    get:
      tags:
        - Station
      summary: Request the service version
      responses:
        '200':
          description: Returns the application version.
          content:
            text/plain: {}
  /application.wadl:
    get:
      tags:
        - Station
      summary: The application documentation in a .wadl file.
      responses:
        '200':
          description: >-
            The documentation of the station application will be returned in a
            *.wadl format.
          content:
            application/xml: {}
components: 
  schemas:
    StationCollection:
      type: object
      properties:
        type:
          type: string
        features:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/StationFeature'
              - $ref: '#/components/schemas/StationChannelFeature'
        metadata:
          $ref: '#/components/schemas/StationMetadata'
    StationFeature:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
          example:
        properties:
          $ref: '#/components/schemas/StationProperties'
        geometry:
          $ref: '#/components/schemas/StationGeometry'
    StationChannelFeature:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
          example:
        properties:
          $ref: '#/components/schemas/StationChannelProperties'
        geometry:
          $ref: '#/components/schemas/StationGeometry'
    StationProperties:
      type: object
      properties:
        network:
          type: string
          example: NL
        station:
          type: string
          example: HGN
        starttime:
          type: string
          format: date-time
          example: "2023-06-12T05:22:36"
        endtime:
          type: string
          format: date-time
          example: "2023-06-20T05:22:36"
        lat:
          type: number
          format: float
          example: 53.154000
        lon:
          type: number
          format: float
          example: 6.892000
        elevation:
          type: number
          format: float
          example: 0.0
        site_name:
          type: string
          example: Muntendam
    StationChannelProperties:
      allOf:
        - $ref: '#/components/schemas/StationProperties'
        - type: object
          properties:
            location:
              type: string
              example: '00'
            channel:
              type: string
              example: 'HHZ'
            depth:
              type: number
              format: float
              example: 0.0
            azimuth:
              type: number
              format: float
              example: 0.0
            dip:
              type: number
              format: float
              example: 0.0
            sensor_description:
              type: string
              example: 'STS-2'
            scale:
              type: number
              format: float
              example: 0.0
            scale_freq:
              type: number
              format: float
              example: 0.0
            scale_units:
              type: string
              example: 'M/S'
            sample_rate:
              type: number
              format: float
              example: 0.0
    StationGeometry:
      type: object
      properties:
        type:
          type: string
        coordinates:
          type: array
          items:
            type: number
            format: float
    StationMetadata:
      type: object
      properties:
        created:
          type: string
          format: date-time
        url:
          type: string
        sender:
          type: string
        source:
          type: string
        count:
          type: integer
          format: int32