openapi: 3.0.3
info:
  title: ENDEMICA DSS - API REST
  version: 1.0.0
  description: API pubbliche di ENDEMICA DSS per consumo dati open access (POI, praterie di Posidonia, ZSC, segnalazioni citizen). Tutti i dati sono pubblicati con licenza CC-BY 4.0 in conformita' con la EU Open Data Directive 2019/1024 e la
    Direttiva INSPIRE 2007/2/CE. Le segnalazioni citizen sono aggregate e anonimizzate per conformita' GDPR.
  contact:
    name: ENDEMICA DSS
    url: /endemica/contatti/
  license:
    name: CC-BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: http://m067.aquariuspa.it
  description: Server attivo
- url: /
  description: Server relativo (qualsiasi host)
tags:
- name: POI
  description: Punti di interesse georeferenziati
- name: Praterie
  description: Praterie di Posidonia oceanica
- name: ZSC
  description: Zone Speciali di Conservazione e AMP
- name: Segnalazioni
  description: 'Citizen Science: avvistamenti, allerte, foto'
- name: Statistiche
  description: KPI aggregati real-time
- name: Sistema
  description: Health-check e meta-endpoint
- name: Download
  description: Download dataset multi-formato (KML, CSV, Shapefile)
paths:
  /endemica/api/health/:
    get:
      tags:
      - Sistema
      summary: Health check
      description: Endpoint di liveness/readiness per monitor esterni.
      responses:
        '200':
          description: Servizio operativo
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /endemica/api/poi.geojson:
    get:
      tags:
      - POI
      summary: Lista POI in GeoJSON
      description: Restituisce tutti i POI pubblicati come FeatureCollection GeoJSON. Filtraggio opzionale per tipologia e bounding box geografico.
      parameters:
      - name: tipo
        in: query
        description: Filtra per tipologia POI (es. totem_m7, lab, citizen).
        required: false
        schema:
          type: string
      - name: bbox
        in: query
        description: Bounding box geografico nel formato 'minLng,minLat,maxLng,maxLat'.
        required: false
        schema:
          type: string
        example: 15.5,38.0,17.0,40.0
      responses:
        '200':
          description: FeatureCollection GeoJSON
          content:
            application/json:
              schema: &id002
                type: object
                properties:
                  type:
                    type: string
                    enum:
                    - FeatureCollection
                  features:
                    type: array
                    items: &id001
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - Feature
                        id:
                          type: integer
                        geometry:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - Point
                              - LineString
                              - Polygon
                              - MultiPoint
                              - MultiLineString
                              - MultiPolygon
                              - GeometryCollection
                            coordinates:
                              type: array
                        properties:
                          type: object
        '400':
          description: Parametro bbox malformato
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /endemica/api/poi/{id}/:
    get:
      tags:
      - POI
      summary: Dettaglio POI
      description: Restituisce un singolo POI con i suoi metadati estesi (parco, prateria, campo boe associati).
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID del POI
      responses:
        '200':
          description: Feature GeoJSON del POI
          content:
            application/json:
              schema: *id001
        '404':
          description: POI non trovato o non pubblicato
  /endemica/api/praterie.geojson:
    get:
      tags:
      - Praterie
      summary: Lista praterie di Posidonia in GeoJSON
      description: Tutte le praterie con geometria nota, come FeatureCollection GeoJSON. Le proprieta' includono nome, specie, stato di conservazione, superficie in ettari.
      responses:
        '200':
          description: FeatureCollection GeoJSON
          content:
            application/json:
              schema: *id002
  /endemica/api/zsc.geojson:
    get:
      tags:
      - ZSC
      summary: Lista ZSC e aree marine protette
      description: Zone Speciali di Conservazione e Aree Marine Protette della Calabria, con perimetri ufficiali UE/Ministero Ambiente come FeatureCollection GeoJSON.
      responses:
        '200':
          description: FeatureCollection GeoJSON
          content:
            application/json:
              schema: *id002
  /endemica/api/campi-boe/:
    get:
      tags:
      - POI
      summary: Lista campi boe ecocompatibili
      description: Campi boe del progetto PNRR M2-C-4 I-3.5.
      responses:
        '200':
          description: Lista risultati
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        nome:
                          type: string
                        parco:
                          type: string
                          nullable: true
                        numero_boe:
                          type: integer
                        operativo:
                          type: boolean
                  count:
                    type: integer
  /endemica/api/segnalazioni/:
    post:
      tags:
      - Segnalazioni
      summary: Invia segnalazione citizen science
      description: Crea una nuova segnalazione cittadina. Accetta JSON o form-data multipart (per upload foto). La segnalazione entra in stato 'nuova' e viene poi validata dal biologo Ente Parchi nel back-office.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - categoria
              - descrizione
              - lat
              - lng
              - consenso_privacy
              properties:
                categoria:
                  type: string
                  enum:
                  - avvistamento
                  - danno
                  - rifiuti
                  - ancoraggio
                  - altro
                descrizione:
                  type: string
                lat:
                  type: number
                  format: float
                lng:
                  type: number
                  format: float
                nome_segnalante:
                  type: string
                email_segnalante:
                  type: string
                  format: email
                telefono_segnalante:
                  type: string
                consenso_privacy:
                  type: boolean
          multipart/form-data:
            schema:
              type: object
              properties:
                categoria:
                  type: string
                descrizione:
                  type: string
                lat:
                  type: number
                lng:
                  type: number
                foto:
                  type: string
                  format: binary
                nome_segnalante:
                  type: string
                email_segnalante:
                  type: string
                telefono_segnalante:
                  type: string
                consenso_privacy:
                  type: boolean
      responses:
        '201':
          description: Segnalazione creata
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  stato:
                    type: string
                    example: nuova
        '400':
          description: Errori di validazione
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  errors:
                    type: object
  /endemica/api/mymap.geojson:
    get:
      tags:
      - POI
      summary: Proxy My Maps (Google) -> GeoJSON
      description: 'Quarto layer dell''atlante: proxy del KML di una Google My Map configurata dall''admin del tenant (vedi EndemicaTenantConfig.mymap_kml_url). Cache server-side.'
      responses:
        '200':
          description: FeatureCollection GeoJSON
          content:
            application/json:
              schema: *id002
        '204':
          description: Nessun KML configurato per il tenant
  /endemica/api/stats/:
    get:
      tags:
      - Statistiche
      summary: KPI aggregati piattaforma
      description: 'Statistiche aggregate in tempo reale (cache 1h): conteggi POI, praterie, ZSC, segnalazioni per stato e categoria, heatmap geografica. Pensato per widget esterni e portali di rendicontazione.'
      responses:
        '200':
          description: Statistiche aggregate
          content:
            application/json:
              schema:
                type: object
                properties:
                  kpi:
                    type: object
                  by_category:
                    type: object
                  by_status:
                    type: object
                  timestamp:
                    type: string
                    format: date-time
  /endemica/api/v1/poi/download.kml:
    get:
      tags:
      - Download
      - POI
      summary: Download POI in formato KML
      description: File KML (Google Earth / QGIS / OpenCPN).
      responses:
        '200':
          description: File KML dataset POI
          content:
            application/vnd.google-earth.kml+xml:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/poi/download.csv:
    get:
      tags:
      - Download
      - POI
      summary: Download POI in formato CSV
      description: File CSV UTF-8 con BOM (compatibile Excel italiano). Geometria come colonna WKT.
      responses:
        '200':
          description: File CSV dataset POI
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/praterie/download.kml:
    get:
      tags:
      - Download
      - Praterie
      summary: Download Praterie in formato KML
      description: File KML (Google Earth / QGIS / OpenCPN).
      responses:
        '200':
          description: File KML dataset Praterie
          content:
            application/vnd.google-earth.kml+xml:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/praterie/download.csv:
    get:
      tags:
      - Download
      - Praterie
      summary: Download Praterie in formato CSV
      description: File CSV UTF-8 con BOM (compatibile Excel italiano). Geometria come colonna WKT.
      responses:
        '200':
          description: File CSV dataset Praterie
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/zsc/download.kml:
    get:
      tags:
      - Download
      - ZSC
      summary: Download ZSC in formato KML
      description: File KML (Google Earth / QGIS / OpenCPN).
      responses:
        '200':
          description: File KML dataset ZSC
          content:
            application/vnd.google-earth.kml+xml:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/zsc/download.csv:
    get:
      tags:
      - Download
      - ZSC
      summary: Download ZSC in formato CSV
      description: File CSV UTF-8 con BOM (compatibile Excel italiano). Geometria come colonna WKT.
      responses:
        '200':
          description: File CSV dataset ZSC
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/segnalazioni/download.kml:
    get:
      tags:
      - Download
      - Segnalazioni
      summary: Download Segnalazioni in formato KML
      description: File KML (Google Earth / QGIS / OpenCPN).
      responses:
        '200':
          description: File KML dataset Segnalazioni
          content:
            application/vnd.google-earth.kml+xml:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string
  /endemica/api/v1/segnalazioni/download.csv:
    get:
      tags:
      - Download
      - Segnalazioni
      summary: Download Segnalazioni in formato CSV
      description: File CSV UTF-8 con BOM (compatibile Excel italiano). Geometria come colonna WKT.
      responses:
        '200':
          description: File CSV dataset Segnalazioni
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: attachment; filename="endemica_<dataset>.<ext>"
              schema:
                type: string