openapi: 3.0.3
info:
  title: Lagepuls API
  version: "1"
  description: >
    Standort-Resilienz-Score für Berliner Adressen (Pilotregion Berlin-only,
    siehe CLAUDE.md). Score-Werte sind wöchentlich neu berechnete
    Perzentilränge (0-100) innerhalb der Pilotregion, keine absoluten
    Kennzahlen — siehe /entwickler/dokumentation und /methodik für Details.
    Kein Gutachten im Sinne der ImmoWertV, keine Anlageberatung.
  contact:
    url: https://lagepuls.de/entwickler/dokumentation
servers:
  - url: https://lagepuls.de
paths:
  /api/v1/scores:
    post:
      summary: Resilienz-Score für eine oder mehrere Adressen abrufen
      description: >
        Public Tier: genau eine Adresse pro Anfrage, nur Gesamtscore.
        Developer/Enterprise Tier: bis zu 20 Adressen pro Anfrage
        (Batch), vollständige Dimension-Aufschlüsselung.
      security:
        - ApiKeyHeader: []
        - ApiKeyBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [addresses]
              properties:
                addresses:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: string
                  example: ["Alexanderplatz 1, Berlin"]
      responses:
        "200":
          description: Ergebnisse je angefragter Adresse
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScoreResponse"
        "400":
          description: Ungültiger Request-Body oder zu viele Adressen
        "401":
          description: API-Key fehlt, ungültig oder widerrufen
        "403":
          description: Batch-Anfrage mit Public-Tier-Key (nur 1 Adresse erlaubt)
        "429":
          description: Tageslimit des Tiers erreicht
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    ApiKeyBearer:
      type: http
      scheme: bearer
  schemas:
    Overall:
      type: object
      properties:
        score:
          type: number
          nullable: true
        ampel:
          type: string
          enum: [rot, gelb, gruen]
          nullable: true
        dimensionsIncluded:
          type: integer
        dimensionsTotal:
          type: integer
    ScoreResult:
      type: object
      properties:
        address:
          type: string
        status:
          type: string
          enum: [ok, invalid_address, address_not_found, outside_pilot_region]
        bezirk:
          type: string
        overall:
          $ref: "#/components/schemas/Overall"
        dimensions:
          type: array
          description: Nur ab Developer-Tier enthalten.
          items:
            type: object
    ScoreResponse:
      type: object
      properties:
        tier:
          type: string
          enum: [public, developer, enterprise]
        results:
          type: array
          items:
            $ref: "#/components/schemas/ScoreResult"