openapi: 3.1.0
info:
  title: mapx Elevation API
  version: 1.0.0
  description: Höhe für Punkte und Pfade aus dem mapx-DTM bzw. -DSM (BEV ALS 1 m, CC BY 4.0). Spezifikation, Verfügbarkeit siehe https://docs.mapx.at/changelog/.
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://api.mapx.at
paths:
  /v1/elevation:
    get:
      operationId: getElevation
      summary: Höhe für Punkte oder Profil entlang eines Pfads
      description: Entweder `points` (höchstens 512) oder `path` (2 bis 512 Stützpunkte, mit `samples`) angeben. Außerhalb der Daten ist `elevation` null.
      parameters:
        - name: points
          in: query
          description: "Liste `lon,lat;lon,lat` (WGS84)."
          schema: { type: string, example: "12.694,47.074;12.70,47.08" }
        - name: path
          in: query
          description: "Polylinie `lon,lat;lon,lat`; zusammen mit `samples`."
          schema: { type: string, example: "12.69,47.07;12.70,47.08" }
        - name: samples
          in: query
          description: Anzahl gleichmäßig verteilter Messpunkte entlang `path`.
          schema: { type: integer, minimum: 2, maximum: 1024, default: 100 }
        - name: model
          in: query
          schema: { type: string, enum: [dtm, dsm], default: dtm }
      responses:
        "200":
          description: GeoJSON FeatureCollection, ein Punkt-Feature je Messpunkt.
          content:
            application/geo+json:
              schema: { $ref: "#/components/schemas/ElevationCollection" }
            application/json:
              schema: { $ref: "#/components/schemas/ElevationCollection" }
        "400": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
components:
  responses:
    Problem:
      description: Fehler nach RFC 9457.
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
  schemas:
    ElevationCollection:
      type: object
      required: [type, features]
      properties:
        type: { const: FeatureCollection }
        features:
          type: array
          items:
            type: object
            required: [type, geometry, properties]
            properties:
              type: { const: Feature }
              geometry:
                type: object
                required: [type, coordinates]
                properties:
                  type: { const: Point }
                  coordinates: { type: array, items: { type: number }, minItems: 2, maxItems: 2 }
              properties:
                type: object
                required: [elevation, resolution_m, model, stichtag]
                properties:
                  elevation: { type: [number, "null"], description: Höhe in Metern (0,1 m gerundet), null außerhalb der Daten. }
                  resolution_m: { type: number, description: Rasterweite der Quelle in Metern. }
                  distance_m: { type: number, description: Nur bei `path` Strecke vom Pfadanfang in Metern. }
                  model: { type: string, enum: [dtm, dsm] }
                  stichtag: { type: string, description: Stichtag der Quelldaten (ISO 8601 Datum). }
    Problem:
      type: object
      required: [title, status]
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }