openapi: 3.0.3
info:
  contact:
    name: API Specification (based on STAC)
    url: http://data.geo.admin.ch/api/stac/v1/
  description: |
    This is an OpenAPI definition of the API to query and access federal geodata on
    data.geo.admin.ch. The API is based on the core SpatioTemporal Asset Catalog API specification
    [STAC](http://stacspec.org) and adds two extensions for extended searching possibilities.

    Find tutorials, examples and best practices around the STAC API in the [Tech Docs](https://docs.geo.admin.ch/download-data/stac-api/overview.html).
  title: The SpatioTemporal Asset Catalog API for data.geo.admin.ch
  version: 1.0.0
servers:
  - description: Data.geo.admin.ch
    url: https://data.geo.admin.ch/api/stac/v1
tags:
  - description: Essential characteristics of this API
    name: Capabilities
  - description: Access to data (features)
    name: Data
  - description: Extension to OGC API - Features to support STAC metadata model and search API
    name: STAC
  - name: Sort Extension
    description: |
      [An extension to the STAC API](https://github.com/stac-api-extensions/sort) that allows sorting
      of results based on specified properties.

paths:
  /:
    get:
      description: >-
        The landing page provides links to the API definition, the conformance
        statements and to the feature collections in this dataset.
      operationId: getLandingPage
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/LandingPage"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Landing page
      tags:
        - Capabilities
  /collections:
    get:
      operationId: getCollections
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/limit"
        - $ref: "./components/parameters.yaml#/components/parameters/provider"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/Collections"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch collections
      description: The feature collections in the dataset
      tags:
        - Data
  /collections/{collectionId}:
    get:
      operationId: describeCollection
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/collectionId"
        - $ref: "./components/parameters.yaml#/components/parameters/IfMatch"
        - $ref: "./components/parameters.yaml#/components/parameters/IfNoneMatch"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/Collection"
        "304":
          $ref: "./components/responses.yaml#/components/responses/NotModified"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFound"
        "412":
          $ref: "./components/responses.yaml#/components/responses/PreconditionFailed"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch a single collection
      description: Describe the feature collection with id `collectionId`
      tags:
        - Data
  /collections/{collectionId}/items:
    get:
      description: >-
        Fetch features of the feature collection with id `collectionId`.


        Every feature in a dataset belongs to a collection. A dataset may
        consist of multiple feature collections. A feature collection is often a
        collection of features of a similar type, based on a common schema.


        Use content negotiation to request HTML or GeoJSON.
      operationId: getFeatures
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/collectionId"
        - $ref: "./components/parameters.yaml#/components/parameters/limit"
        - $ref: "./components/parameters.yaml#/components/parameters/bbox"
        - $ref: "./components/parameters.yaml#/components/parameters/datetime"
        - $ref: "./components/parameters.yaml#/components/parameters/sortby"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/Features"
        "400":
          $ref: "./components/responses.yaml#/components/responses/InvalidParameter"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFound"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch features
      tags:
        - Data
  /collections/{collectionId}/items/{featureId}:
    get:
      description: >-
        Fetch the feature with id `featureId` in the feature collection
        with id `collectionId`.


        Use content negotiation to request HTML or GeoJSON.
      operationId: getFeature
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/collectionId"
        - $ref: "./components/parameters.yaml#/components/parameters/featureId"
        - $ref: "./components/parameters.yaml#/components/parameters/IfMatch"
        - $ref: "./components/parameters.yaml#/components/parameters/IfNoneMatch"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/Feature"
        "304":
          $ref: "./components/responses.yaml#/components/responses/NotModified"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFound"
        "412":
          $ref: "./components/responses.yaml#/components/responses/PreconditionFailed"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch a single feature
      tags:
        - Data
  "/collections/{collectionId}/assets":
    get:
      description: >-
        Fetch collection assets of the collection with id `collectionId`.

        These assets do not belong to any item.
      operationId: getCollectionAssets
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/collectionId"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/CollectionAssets"
        "400":
          $ref: "./components/responses.yaml#/components/responses/InvalidParameter"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFound"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch all collection assets for a collection
      tags:
        - Data
  /collections/{collectionId}/assets/{assetId}:
    get:
      summary: Fetch a single collection asset
      tags:
        - Data
      description: >-
        Fetch the collection asset with id `assetId` of the collection with id `collectionId`.
      operationId: getCollectionAsset
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/collectionId"
        - $ref: "./components/parameters.yaml#/components/parameters/assetId"
        - $ref: "./components/parameters.yaml#/components/parameters/IfMatch"
        - $ref: "./components/parameters.yaml#/components/parameters/IfNoneMatch"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/CollectionAsset"
        "304":
          $ref: "./components/responses.yaml#/components/responses/NotModified"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFound"
        "412":
          $ref: "./components/responses.yaml#/components/responses/PreconditionFailed"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
  /{assetObjectHref}:
    servers:
      - url: http://data.geo.admin.ch/
    parameters:
      - $ref: "./components/parameters.yaml#/components/parameters/assetObjectHref"
    get:
      tags:
        - Data
      summary: Fetch an asset object
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/IfNoneMatch"
      operationId: getAssetObject
      description: |
        Return an asset object

        ### Notes on Caching

        Asset objects are cached by default for 2 hours (7200 seconds). Depending on the
        update interval of an asset object (e.g. for frequently updated data)
        the `Cache-Control` header can be different, in special cases it can even be
        set to `no-cache` (e.g. for realtime data).

        All endpoints support the precondition headers `If-Match` and `If-None-Match`.
        To reduce unnecessary traffic it's highly recommended to use these headers
        (mostly `If-None-Match`) when making calls.

        In case your application is using frequently updated data and you want to
        be sure not to miss an update of the data, the recommended procedure is as
        follows:

        ```python
        import requests
        import time

        refresh_interval = 60

        item_etag = "*"
        item_url = "https://data.geo.admin.ch/collections/{collectionID}/items/{itemId}"

        asset_id = 'data.json'
        asset_etag = "*"

        poll_for_new_data = True

        while(poll_for_new_data):
          item_response = requests.get(item_url, headers={'If-None-Match': f'"{item_etag}"'})
          if item_response.status_code == 304:
            # item metadata and hence any associated asset object didn't
            # change since last call

            time.sleep(refresh_interval)

          elif item_response.status_code == 200:
            # item metadata has changed since last visit

            item_etag = item_response.headers.get("ETag") # save the new etag
            asset_href = item_response.json['assets'][asset_id]['href'] # save the asset href

            obj_response = requests.get(asset_href, headers={'If-None-Match': f'"{asset_etag}"'})
            if obj_response.status_code == 304:
              # "our" asset object didn't change since last call,
              # we can ignore that the item metadata changed,
              # it was a different asset that has changed

              time.sleep(refresh_interval)

            elif obj_response.status_code == 200:
              # "our" asset object has changed, we load the new data

              asset_etag = obj_response.headers.get("ETag")  # save the new asset etag
              asset_checksum = obj_response.headers.get("X-Amz-Meta-Sha256")
              object = obj_response.data

              # calculate the sha256 checksum of the data in a proper way
              checksum = calc_checksum(object)
              if checksum != asset_checksum:
                # Error: corrupted data from download
                # do proper error handling

              # do sth with the data
            else:
              # do proper error handling
          else:
            # do proper error handling
        ```

      responses:
        "200":
          description: The asset object
          headers:
            ETag:
              $ref: "./components/headers.yaml#/components/headers/ETag"
            Cache-Control:
              description: |
                Cache header for the asset object
              example: "public, max-age=7200"
              schema:
                type: string
              required: true
            Content-Type:
              description: |
                The content type of the asset object as specified in the [asset object
                metadata](#tag/Data/operation/getFeature)
              required: true
              schema:
                type: string
            X-Amz-Meta-Sha256:
              description: |
                SHA256 checksum of the asset object.

                This checksum can be compared with the asset metadata `checksum:multihash` field
                (see [asset object metadata](#tag/Data/operation/getFeature)). Note that the
                `checksum:multihash` field is a multihash while `X-Amz-Meta-Sha256` is a SHA256.
                See [multihash](https://multiformats.io/multihash/) for more information.
              required: true
              example: 3dd6e1ead0760d278344394b0e7f017b5b6049e4fed3d2083b564fc268f07334
              schema:
                $ref: "./components/schemas.yaml#/components/schemas/sha256"
        "304":
          $ref: "./components/responses.yaml#/components/responses/NotModified"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFoundS3"
        "412":
          $ref: "./components/responses.yaml#/components/responses/PreconditionFailedS3"

  /conformance:
    get:
      description: >-
        A list of all conformance classes specified in a standard that the
        server conforms to.
      operationId: getConformanceDeclaration
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/ConformanceDeclaration"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Information about specifications that this API conforms to
      tags:
        - Capabilities
  /search:
    get:
      description: >-
        Retrieve Items matching filters. Intended as a shorthand API for simple
        queries. To filter by fields in "properties" please use the
        [POST /search](#tag/STAC/operation/postSearchSTAC) request.

      operationId: getSearchSTAC
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/bbox"
        - $ref: "./components/parameters.yaml#/components/parameters/intersects"
        - $ref: "./components/parameters.yaml#/components/parameters/datetime"
        - $ref: "./components/parameters.yaml#/components/parameters/limit"
        - $ref: "./components/parameters.yaml#/components/parameters/ids"
        - $ref: "./components/parameters.yaml#/components/parameters/collectionsArray"
        - $ref: "./components/parameters.yaml#/components/parameters/sortby"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/components/schemas/itemsSearchGet"
          description: A feature collection.
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Search STAC items with simple filtering.
      tags:
        - STAC
    post:
      description: >-
        Retrieve items matching filters. Intended as the standard, full-featured
        query API.

      operationId: postSearchSTAC
      requestBody:
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/components/schemas/searchBody"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/components/schemas/itemsSearchPost"
          description: A feature collection.
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Search STAC items with full-featured filtering.
      tags:
        - STAC
  /sortables:
    get:
      description: >-
        This endpoint returns a list of properties (or aliases) that can be used in the `sortby` parameter
        for the cross-collection item search (i.e. `GET /search` and `POST /search`).
        It returns a JSON Schema that defines the properties allowed in `sortby`.
        The precise definition of this can be found in the
        [OGC API - Features - Part 5: Schemas](https://docs.ogc.org/is/23-058r2/23-058r2.html).
      operationId: getSortables
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/Sortables"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch sortable fields for /search
      tags:
        - Sort Extension
  /collections/{collectionId}/sortables:
    get:
      description: >-
        This endpoint returns a list of properties (or aliases) that can be used in the `sortby` parameter
        for the item lists of a collection (i.e. `GET /collections/{collectionId}/items`).
        It returns a JSON Schema that defines the properties allowed in `sortby`.
        The precise definition of this can be found in the
        [OGC API - Features - Part 5: Schemas](https://docs.ogc.org/is/23-058r2/23-058r2.html).
      operationId: getCollectionSortables
      parameters:
        - $ref: "./components/parameters.yaml#/components/parameters/collectionId"
      responses:
        "200":
          $ref: "./components/responses.yaml#/components/responses/Sortables"
        "404":
          $ref: "./components/responses.yaml#/components/responses/NotFound"
        "500":
          $ref: "./components/responses.yaml#/components/responses/ServerError"
      summary: Fetch sortable fields for features in a collection
      tags:
        - Sort Extension