---
openapi: "3.0.0"
info:
  version: "1.0.0"
  title: Service WMTS
  description: |
    A RESTFul implementation of the [WMTS](https://www.ogc.org/standards/wmts) [OGC](https://www.ogc.org/) standard.
    For detailed information, see [WMTS OGC](https://www.ogc.org/standards/wmts) standard

    *NOTE: Only the RESTFul request encoding to `GetTile` and `GetCapabilities` are implemented, not the `GetLegend` and `GetFeatureInfo`.
    No KVP and SOAP request encoding is supported.*

servers:
  - url: https://wmts.geo.admin.ch

tags:
  - name: Checker
    description: Endpoint to check the service status
  - name: WMTS Capabilities
    description: Get WMTS Capabilities endpoints
  - name: Tiles
    description: Get tiles endpoints

paths:
  /checker:
    get:
      summary: Liveness checker
      description: Route to check if the service is up.
      operationId: liveness-checker
      tags:
        - Checker
      responses:
        200:
          description: Returning OK.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Always true for 200 response.
                  message:
                    type: string
                  version:
                    type: string
                    description: Application version string (SemVer 2.0)
                example:
                  success: true
                  message: "OK"
                  version: "v0.2.0-beta.1"
        500:
          $ref: "#/components/responses/internalServerError"
  /checker/ready:
    get:
      summary: Readiness checker
      description: Route to check if the service is ready to serve requests. It also checks the readiness of the WMS backend.
      operationId: readiness-checker
      tags:
        - Checker
      responses:
        200:
          description: Returning OK.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Always true for 200 response.
                  message:
                    type: string
                example:
                  success: true
                  message: "OK"
        500:
          $ref: "#/components/responses/internalServerError"
        502:
          $ref: "#/components/responses/backendWmsConnectionFailure"
        503:
          $ref: "#/components/responses/backendWmsFailure"
  /1.0.0/{layer_id}/{style_name}/{time}/{srid}/{zoom}/{col}/{row}.{extension}:
    parameters:
      - name: layer_id
        in: path
        required: true
        description: Layer ID, see the [WMTS GetCapabilities](http://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.
        schema:
          type: string
        example: ch.bav.schienennetz
      - name: style_name
        in: path
        required: true
        description: Style name, only `default` is supported
        schema:
          type: string
          enum:
           - default
      - name: time
        in: path
        required: true
        description: |
          Date of tile generation in (ISO-8601) or logical value like `current`. A list of available
          values is provided in the [WMTS GetCapabilities](http://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml)
          document under the `<Dimension>` tag. We recommend to use the value under the `<Default>` tag.
          Note that these values might change frequently - check for updates regularly.
        schema:
          oneOf:
            - type: string
              enum:
               - current
            - type: string
              format: date-time
            - type: string
              format: date
      - name: srid
        in: path
        required: true
        description: EPSG code for the projection
        schema:
          type: string
          enum:
            - 2056
            - 21781
            - 4326
            - 3857
      - name: zoom
        in: path
        required: true
        description: Zoom level, depends on the resolution.
        schema:
          type: integer
      - name: col
        in: path
        required: true
        description: Tile column
        schema:
          type: integer
      - name: row
        in: path
        required: true
        description: Tile row
        schema:
          type: integer
      - name: extension
        in: path
        required: true
        description: Format extension. Mostly `png`, except for some raster layer (pixelkarte and swissimage)
        schema:
          type: string
          enum:
            - png
            - jpeg
    options:
      summary: Options for GET Tiles
      description: Returns the HTTP options for GET Tiles
      operationId: options-tiles
      tags:
        - Tiles
      responses:
        200:
          description: Returns header options
          headers:
            Cache-Control:
              schema:
                type: string
              example: "public, max-age=1800"
            Access-Control-Allow-Origin:
              schema:
                type: string
              example: "*"
            Access-Control-Allow-Methods:
              schema:
                type: string
              example: "GET,HEAD"
            Access-Control-Allow-Headers:
              schema:
                type: string
              example: "Content-Type, Authorization, x-requested-with, Origin, Accept"
          content:
            text/plain:
              example: ''
        500:
          $ref: "#/components/responses/internalServerError"
    get:
      summary: Get Tile
      description: Get a tile
      operationId: gettile
      tags:
        - Tiles
      parameters:
        - name: mode
          in: query
          description: Operation mode
          schema:
            type: string
            enum:
              - default
              - debug
              - preview
        - name: nodata
          in: query
          description: |
            If `true` returns `OK` if the image was successfully fetched and created. Can be used for tile generation.
          schema:
            type: boolean
      responses:
        200:
          description: Tile image
          content:
            image/png:
              schema:
                type: string
                format: binary
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
              example:
                error:
                  code: 400
                  message: "Unsupported zoom level 139 for srid 2056"
                success: false
            plain/html:
              example: |
                <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
                <title>400 Bad Request</title>
                <h1>Bad Request</h1>
                <p>Unsupported zoom level 139 for srid 2056</p>
        500:
          $ref: "#/components/responses/internalServerError"
        502:
          $ref: "#/components/responses/backendWmsConnectionFailure"
        503:
          $ref: "#/components/responses/backendWmsFailure"
  /1.0.0/WMTSCapabilities.xml:
    get:
      summary: Get Capabilities - alias 1
      operationId: getCapabilities1
      tags:
        - WMTS Capabilities
      parameters:
        - $ref: "#/components/parameters/epsgQuery"
        - $ref: "#/components/parameters/langQuery"
      responses:
        200:
          $ref: "#/components/responses/capabilities"
        400:
          $ref: "#/components/responses/badRequestError"
        500:
          $ref: "#/components/responses/internalServerError"
  /EPSG/{epsg}/1.0.0/WMTSCapabilities.xml:
    parameters:
      - $ref: "#/components/parameters/epsgPath"
    get:
      summary: Get Capabilities - alias 2
      operationId: getCapabilities2
      tags:
        - WMTS Capabilities
      responses:
        200:
          $ref: "#/components/responses/capabilities"
        400:
          $ref: "#/components/responses/badRequestError"
        500:
          $ref: "#/components/responses/internalServerError"
  /EPSG/{epsg}/{lang}/1.0.0/WMTSCapabilities.xml:
    parameters:
      - $ref: "#/components/parameters/epsgPath"
      - $ref: "#/components/parameters/langPath"
    get:
      summary: Get Capabilities - alias 3
      operationId: getCapabilities3
      tags:
        - WMTS Capabilities
      responses:
        200:
          $ref: "#/components/responses/capabilities"
        400:
          $ref: "#/components/responses/badRequestError"
        500:
          $ref: "#/components/responses/internalServerError"
  /1.0.0/WMTSCapabilities.EPSG.{epsg}.xml:
    parameters:
      - $ref: "#/components/parameters/epsgPath"
    get:
      summary: Get Capabilities - alias 3
      operationId: getCapabilities
      tags:
        - WMTS Capabilities
      responses:
        200:
          $ref: "#/components/responses/capabilities"
        400:
          $ref: "#/components/responses/badRequestError"
        500:
          $ref: "#/components/responses/internalServerError"

components:
  schemas:
    error:
      type: object
      properties:
        success:
          type: boolean
          description: Always false in case of error.
        error:
          type: object
          properties:
            code:
              type: integer
              description: Error code.
            message:
              type: string
              description: Description of the error.
    epsg:
      type: integer
      enum:
        - 2056
        - 21781
        - 3857
        - 4326
      default: 21781
    language:
      type: string
      enum:
        - de
        - fr
        - it
        - rm
        - en
      default: de
  parameters:
    epsgQuery:
      name: epsg
      in: query
      description: Returns the WMTS Capabilities for this EPSG
      schema:
        $ref: "#/components/schemas/epsg"
    epsgPath:
      name: epsg
      in: path
      required: true
      description: Returns the WMTS Capabilities for this EPSG
      schema:
        $ref: "#/components/schemas/epsg"
    langQuery:
      name: lang
      in: query
      description: Returns the WMTS Capabilities in the given language
      schema:
        $ref: "#/components/schemas/language"
    langPath:
      name: lang
      in: path
      required: true
      description: Returns the WMTS Capabilities in the given language
      schema:
        $ref: "#/components/schemas/language"
  responses:
    capabilities:
      description: WMTS Capabilities XML
      content:
          text/xml:
            schema:
              type: object
              description: See [WMTS OGC](https://www.ogc.org/standards/wmts) standard for the details of the xml.
            example: |
              <?xml version="1.0" encoding="UTF-8"?>
              <Capabilities xmlns="http://www.opengis.net/wmts/1.0"
                            xmlns:ows="http://www.opengis.net/ows/1.1"
                            xmlns:xlink="http://www.w3.org/1999/xlink"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xmlns:gml="http://www.opengis.net/gml"
                            xsi:schemaLocation="http://www.opengis.net/wmts/1.0 http://schemas.opengis.net/wmts/1.0/wmtsGetCapabilities_response.xsd"
                            version="1.0.0">
                  <ows:ServiceIdentification>
                      <ows:Title>WMTS BGDI</ows:Title>
                      <ows:Abstract>-</ows:Abstract>
                      <ows:Keywords>
                          <ows:Keyword>Switzerland</ows:Keyword>
                          <ows:Keyword>Web Map Service</ows:Keyword>
                          <ows:Keyword>Schweiz</ows:Keyword>
                          <ows:Keyword>OGC</ows:Keyword>
                          <ows:Keyword>WMS</ows:Keyword>
                          <ows:Keyword>swisstopo</ows:Keyword>
                          <ows:Keyword>Bundesamt fuer Landestopografie</ows:Keyword>
                          <ows:Keyword>Landeskarte</ows:Keyword>
                          <ows:Keyword>Pixelkarte</ows:Keyword>
                          <ows:Keyword>Luftbilder</ows:Keyword>
                          <ows:Keyword>SWISSIMAGE</ows:Keyword>
                          <ows:Keyword>Grenzen</ows:Keyword>
                          <ows:Keyword>swissBOUNDARIES3D</ows:Keyword>
                          <ows:Keyword>Historische Karten</ows:Keyword>
                          <ows:Keyword>Siegfriedatlas</ows:Keyword>
                          <ows:Keyword>Dufourkarte</ows:Keyword>
                      </ows:Keywords>
                      <ows:ServiceType>OGC WMTS</ows:ServiceType>
                      <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
                      <ows:Fees>Die Nutzung des Dienstes ist kostenlos unter Berücksichtigung der Bestimmungen zum Fair Use. www.geo.admin.ch/terms-of-use/ows:Fees>
                      <ows:AccessConstraints>Bei übermässiger Nutzung von Geodiensten kann der Zugang eingeschränkt oder verweigert werden. In diesem Fällen kann swisstopo mit dem Datennutzer / der Datennutzerin einen Vertrag abschliessen (Art. 44 Abs. 2 GeoIV) www.geo.admin.ch/terms-of-use.</ows:AccessConstraints>
                  </ows:ServiceIdentification>
                  <ows:ServiceProvider>
                      <ows:ProviderName>Bundesamt für Landestopografie swisstopo</ows:ProviderName>
                      <ows:ProviderSite xlink:href="http://www.swisstopo.admin.ch"/>
                      <ows:ServiceContact>
                          <ows:IndividualName>webgis@swisstopo.ch</ows:IndividualName>
                          <ows:PositionName></ows:PositionName>
                          <ows:ContactInfo>
                              <ows:Phone>
                                  <ows:Voice>+41 58 469 01 11</ows:Voice>
                                  <ows:Facsimile>+41 58 469 04 59</ows:Facsimile>
                              </ows:Phone>
                              <ows:Address>
                                  <ows:DeliveryPoint>swisstopo</ows:DeliveryPoint>
                                  <ows:City>Bern</ows:City>
                                  <ows:AdministrativeArea>BE</ows:AdministrativeArea>
                                  <ows:PostalCode>3084</ows:PostalCode>
                                  <ows:Country>Switzerland</ows:Country>
                                  <ows:ElectronicMailAddress>webgis@swisstopo.ch</ows:ElectronicMailAddress>
                              </ows:Address>
                          </ows:ContactInfo>
                      </ows:ServiceContact>
                  </ows:ServiceProvider>
                  <ows:OperationsMetadata>
                      <ows:Operation name="GetCapabilities">
                          <ows:DCP>
                              <ows:HTTP>
                                  <ows:Get xlink:href="https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml">
                                      <ows:Constraint name="GetEncoding">
                                          <ows:AllowedValues>
                                              <ows:Value>REST</ows:Value>
                                          </ows:AllowedValues>
                                      </ows:Constraint>
                                  </ows:Get>
                              </ows:HTTP>
                          </ows:DCP>
                      </ows:Operation>
                      <ows:Operation name="GetTile">
                          <ows:DCP>
                              <ows:HTTP>
                                  <ows:Get xlink:href="https://wmts.geo.admin.ch/">
                                      <ows:Constraint name="GetEncoding">
                                          <ows:AllowedValues>
                                              <ows:Value>REST</ows:Value>
                                          </ows:AllowedValues>
                                      </ows:Constraint>
                                  </ows:Get>
                              </ows:HTTP>
                          </ows:DCP>
                      </ows:Operation>
                  </ows:OperationsMetadata>
                  <Contents>
                      <Layer>
                          <ows:Title>Logistikräume ALC</ows:Title>
                          <ows:Abstract>Zuständigkeitsräume der Armeelogistikcenter (ALC).</ows:Abstract>
                          <ows:WGS84BoundingBox>
                              <ows:LowerCorner>5.140242 45.398181</ows:LowerCorner>
                              <ows:UpperCorner>11.47757 48.230651</ows:UpperCorner>
                          </ows:WGS84BoundingBox>
                          <ows:Identifier>ch.vbs.logistikraeume-armeelogistikcenter</ows:Identifier>
                          <ows:Metadata xlink:href="https://www.geocat.ch/geonetwork/srv/ger/md.viewer#/full_view/270a2032-d346-42c5-a657-9129186f1f08"/>
                          <Style>
                              <ows:Title>Logistikräume ALC</ows:Title>
                              <ows:Identifier>ch.vbs.logistikraeume-armeelogistikcenter</ows:Identifier>
                              <LegendURL format="image/png" xlink:href="https://api3.geo.admin.ch/static/images/legends/ch.vbs.logistikraeume-armeelogistikcenter_de.png"/>
                          </Style>
                          <Format>image/png</Format>
                          <Dimension>
                              <ows:Identifier>Time</ows:Identifier>
                              <Default>20141217</Default>
                              <Value>20141217</Value>
                          </Dimension>
                          <TileMatrixSetLink>
                              <TileMatrixSet>2056_26</TileMatrixSet>
                          </TileMatrixSetLink>
                          <ResourceURL format="image/png" resourceType="tile" template="https://wmts.geo.admin.ch/1.0.0/ch.vbs.logistikraeume-armeelogistikcenter/default/{Time}/2056/{TileMatrix}/{TileCol}/{TileRow}.png"/>
                      </Layer>

                      <TileMatrixSet>
                          <ows:Identifier>2056_18</ows:Identifier>
                          <ows:SupportedCRS>urn:ogc:def:crs:EPSG:2056</ows:SupportedCRS>
                          <TileMatrix>
                              <ows:Identifier>0</ows:Identifier>
                              <ScaleDenominator>14285714.285714287</ScaleDenominator>
                              <TopLeftCorner>2420000.0 1350000.0</TopLeftCorner>
                              <TileWidth>256</TileWidth>
                              <TileHeight>256</TileHeight>
                              <MatrixWidth>1</MatrixWidth>
                              <MatrixHeight>1</MatrixHeight>
                          </TileMatrix>
                      </TileMatrixSet>

                  </Contents>
                  <Themes>
                      <Theme>
                          <ows:Title>Basisdaten</ows:Title>
                          <ows:Abstract>Basisdaten</ows:Abstract>
                          <ows:Identifier>23c58de608ebd19b6d5908fd82aecd00</ows:Identifier>
                          <Theme>
                              <ows:Title>Koordinatenreferenzsysteme</ows:Title>
                              <ows:Abstract>Koordinatenreferenzsysteme</ows:Abstract>
                              <ows:Identifier>2</ows:Identifier>
                              <LayerRef>ch.swisstopo.dreiecksvermaschung</LayerRef>
                              <LayerRef>ch.swisstopo.fixpunkte-agnes</LayerRef>
                              <LayerRef>ch.swisstopo.geoidmodell-ch1903</LayerRef>
                              <LayerRef>ch.swisstopo.geoidmodell-etrs89</LayerRef>
                              <LayerRef>ch.swisstopo.koordinatenaenderung</LayerRef>
                              <LayerRef>ch.swisstopo.transformationsgenauigkeit</LayerRef>
                              <LayerRef>ch.swisstopo-vd.spannungsarme-gebiete</LayerRef>
                              <LayerRef>ch.swisstopo.verschiebungsvektoren-tsp1</LayerRef>
                              <LayerRef>ch.swisstopo.verschiebungsvektoren-tsp2</LayerRef>
                          </Theme>
                      </Theme>
                  </Themes>
                  <ServiceMetadataURL xlink:href="https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml"/>
              </Capabilities>
    badRequestError:
      description: 400 Bad Request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
            example:
              success: false
              error:
                code: 400
                message: "Unsupported epsg 20536, must be on of [21781, 2056, 3857, 4326]"
    internalServerError:
      description: Unexpected error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
            example:
              success: false
              error:
                code: 500
                message: "An internal error occurred"
        text/html:
          example: |
            <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
            <title>500 Internal Server Error</title>
            <h1>Internal Server Error</h1>
    backendWmsConnectionFailure:
      description: Cannot connect to backend WMS
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
            example:
              success: false
              error:
                code: 502
                message: "Cannot connect to backend WMS"
        text/html:
          example: |
            <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
            <title>502 Bad Gateway</title>
            <h1>Bad Gateway</h1>
            <p>Cannot connect to backend WMS</p>
    backendWmsFailure:
      description: Incomprehensible answer. WMS is probably not ready yet.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error"
            example:
              success: false
              error:
                code: 503
                message: "Incomprehensible answer. WMS is probably not ready yet."
        text/html:
          example: |
            <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
            <title>503 Service Unavailable</title>
            <h1>Service Unavailable</h1>
            <p>Incomprehensible answer. WMS is probably not ready yet.</p>