swisstopo WMS API

openapi: 3.2.0
info:
  title: Swisstopo WMS API
  version: 1.6.2
  description: 'Operations tagged WMS across 2 of this provider''s published API definitions: swissgeol-lexic-webmap-api.yaml, swisstopo-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://webmap-api.swissgeol.ch
  description: Swisstopo Production Server
- url: https://int-webmap-api.swissgeol.ch
  description: Swisstopo INT Server
- url: https://dev-webmap-api.swissgeol.ch
  description: Swisstopo DEV Server
security:
- ApiKeyAuth: []
tags:
- name: WMS
  description: Endpoints to obtain WMS links for filtered layers
paths:
  /generateWmsRequest:
    post:
      tags:
      - WMS
      summary: Generate a WMS Base URL for a filtered layer (semantic query applied)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WmsRequest'
            example:
              webmapId: SwissTopoMap
              layerId: tecto_units_augm
              filters:
              - filterId: f-tectonic-term
                parameters:
                  term: https://dev-lexic.swissgeol.ch/TectonicUnits/AutochthonousNorthAlpineForeland
                  includeNarrowers: true
        required: true
      responses:
        '200':
          description: WMS endpoint with filtered layer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WmsResponse'
              example:
                url: https://dev-webmap-api.swissgeol.ch/v1/wms
                body: REQUEST=GetMap&SERVICE=WMS&VERSION=1.3.0&FORMAT=image/png&STYLES=swisstopo:filtered&TRANSPARENT=true&LAYERS=tecto_units_augm&TILED=true&SEMANTIC_FILTER=calculate_semantic_constraint( "tecto_units_augm" , "f-tectonic-term" , "https://dev-lexic.swissgeol.ch/TectonicUnits/AutochthonousNorthAlpineForeland" , "true" )&CRS=EPSG:2056
                mimeType: image/png
                note: The WMS URL includes encoded semantic query parameters.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postGenerateWmsRequest
      x-operation-id-source: derived
    servers:
    - url: https://webmap-api.swissgeol.ch
      description: Swisstopo Production Server
    - url: https://int-webmap-api.swissgeol.ch
      description: Swisstopo INT Server
    - url: https://dev-webmap-api.swissgeol.ch
      description: Swisstopo DEV Server
  /wms:
    get:
      tags:
      - WMS
      summary: Retrieve WMS service information
      description: WMS endpoint that complies with the OGC WMS standard, see at https://www.ogc.org/it/standards/wms/. The request may include standard WMS parameters such as REQUEST, SERVICE, VERSION, LAYERS, CRS, BBOX, WIDTH, HEIGHT, and FORMAT. Clients may also provide the optional SEMANTIC_FILTER parameter generated from /generateWmsRequest. When SEMANTIC_FILTER is omitted, the request is proxied without semantic filtering.
      parameters:
      - in: query
        name: SEMANTIC_FILTER
        required: false
        schema:
          type: string
        description: Optional semantic filter expression generated from /generateWmsRequest.
      responses:
        '200':
          description: Successful WMS response
          content:
            image/png:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getWms
      x-operation-id-source: derived
    post:
      tags:
      - WMS
      summary: Retrieve WMS service information
      description: WMS endpoint that complies with the OGC WMS standard, see at https://www.ogc.org/it/standards/wms/. POST requests use the same WMS parameters as GET requests, encoded as application/x-www-form-urlencoded to support long WMS filter payloads. Clients may also provide the optional SEMANTIC_FILTER parameter generated from /generateWmsRequest. When SEMANTIC_FILTER is omitted, the request is proxied without semantic filtering.
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties:
                type: string
              properties:
                SEMANTIC_FILTER:
                  type: string
                  description: Optional semantic filter expression generated from /generateWmsRequest.
      responses:
        '200':
          description: Successful WMS response
          content:
            image/png:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postWms
      x-operation-id-source: derived
    servers:
    - url: https://webmap-api.swissgeol.ch
      description: Swisstopo Production Server
    - url: https://int-webmap-api.swissgeol.ch
      description: Swisstopo INT Server
    - url: https://dev-webmap-api.swissgeol.ch
      description: Swisstopo DEV Server
components:
  schemas:
    ChronostratigraphyFilterParameter:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - Younger
          - From-To
          - Older
        from:
          type: string
          description: From term (required if type is From-To or Older)
        to:
          type: string
          description: To term (required if type is From-To or Younger)
    WmsResponse:
      type: object
      required:
      - url
      - body
      - mimeType
      - note
      properties:
        url:
          type: string
          format: uri
          description: WMS endpoint URL to call.
          example: https://dev-webmap-api.swissgeol.ch/v1/wms
        body:
          type: string
          description: WMS request parameter string generated by /generateWmsRequest.
          example: REQUEST=GetMap&SERVICE=WMS&VERSION=1.3.0&FORMAT=image/png&STYLES=swisstopo:filtered&TRANSPARENT=true&LAYERS=tecto_units_augm&TILED=true&SEMANTIC_FILTER=calculate_semantic_constraint( "tecto_units_augm" , "f-tectonic-term" , "https://dev-lexic.swissgeol.ch/TectonicUnits/AutochthonousNorthAlpineForeland" , "true" )&CRS=EPSG:2056
        mimeType:
          type: string
          example: image/png
        note:
          type: string
          example: WMS URL includes encoded semantic query parameters.
    ByAttributeFilterParameter:
      type: object
      required:
      - attribute
      - value
      properties:
        attribute:
          type: string
          description: Attribute key available from /layers/{layerId}/attributeList
        value:
          oneOf:
          - type: string
          - type: number
          - type: boolean
          description: Attribute value to match
    TermFilterParameter:
      type: object
      required:
      - term
      properties:
        term:
          type: string
          description: Selected term from vocabulary
        includeNarrowers:
          type: boolean
          description: Whether to include narrower terms
          default: true
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    WmsRequest:
      required:
      - webmapId
      - layerId
      type: object
      properties:
        webmapId:
          type: string
        layerId:
          type: string
        filters:
          type: array
          description: List of applied filters and their parameter values
          items:
            $ref: '#/components/schemas/WmsRequest_filters'
    WmsRequest_filters:
      type: object
      properties:
        filterId:
          type: string
          enum:
          - f-chronostrat-term
          - f-tectonic-term
          - f-lithostrat-term
          - f-lithology-term
          - f-byAttribute
        parameters:
          oneOf:
          - $ref: '#/components/schemas/ChronostratigraphyFilterParameter'
          - $ref: '#/components/schemas/TermFilterParameter'
          - $ref: '#/components/schemas/ByAttributeFilterParameter'
  responses:
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal server error
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'API key required to access all endpoints of the SwissTopo WebMap Semantic Filtering API.

        '
externalDocs:
  description: WebMap semantic filter architecture and usage
  url: https://virtserver.swaggerhub.com/epsilonitalia/SwissTopoWebmapAPI/1.0.1
x-refined-from:
- swissgeol-lexic-webmap-api.yaml
- swisstopo-openapi.yml