Dati aperti · CC0 · versione documento aggiornata di continuo

Dataset e API — Ecocanto in formato scaricabile.

La rete Ecocanto pubblica le rilevazioni bioacustiche in formati standard e permanenti: API JSON per integrazioni operative, snapshot mensili CSV per analisi off-line, feed RSS per aggiornamenti in tempo reale, DOI Zenodo trimestrali per la ricerca. Tutto sotto licenza aperta. Nessuna registrazione richiesta.

dati grezzi CC0contenuti editoriali CC BY 4.0CORS abilitatocache 5 min

1 · API JSON

Quattro endpoint pubblici, GET-only, cacheati 5 minuti sul CDN. Payload autodescrittivo con campi _license, _source, _generated_at. Nessuna autenticazione. CORS aperto per uso browser-side. Consigliato anche per integrazioni con LLM: vedi /llms.txt per l'indice completo.

GET/api/public/summary

Snapshot rete: contatori, top specie

Numero device attivi, detection totali, ultimi 30 gg, specie distinte, top 10 specie.

Esempio curl + risposta

curl -s https://ecocanto.it/api/public/summary | jq .network

{
  "network": {
    "public_devices": 4,
    "total_detections": 71234,
    "detections_last_30d": 8104,
    "distinct_species": 118
  },
  "top_species": [ ... ]
}

GET/api/public/species?region=Lombardia&month=2026-07

Specie aggregate filtrabili

Per specie: detection_count, prima/ultima osservazione. Filtri opzionali region (nome esteso, es. Lombardia) e month (YYYY-MM).

Esempio curl + risposta

curl -s "https://ecocanto.it/api/public/species?region=Lombardia&month=2026-07&limit=25" | jq '.species[0]'

{
  "scientific_name": "Turdus merula",
  "common_name_it": "Merlo",
  "is_native_italy": true,
  "biodiversity_impact": 3,
  "detection_count": 412,
  "first_seen": "2026-07-01T04:12:03Z",
  "last_seen":  "2026-07-31T21:44:19Z"
}

GET/api/public/devices

Lista device pubblici della rete

Coordinate, ultima detection, regione, activity. Nessun MAC hardware esposto: usa uno slug SHA-256 stabile.

Esempio curl + risposta

curl -s https://ecocanto.it/api/public/devices | jq '.devices | length'

{
  "devices": [
    {
      "slug": "8e2a1c04b3f7",
      "label": "raspberrypi201-BG",
      "region": "Lombardia",
      "lat": 45.7038, "lng": 10.0838,
      "last_detected_at": "2026-07-12T05:14:03Z"
    }
  ]
}

GET/api/public/detections/recent

Ultime detection validate

Stream delle N rilevazioni più recenti (default 50, max 200). Solo validation_status IN ('valid','replaced').

Esempio curl + risposta

curl -s "https://ecocanto.it/api/public/detections/recent?limit=10" | jq '.detections[0]'

{
  "detected_at": "2026-07-12T05:14:03Z",
  "scientific_name": "Turdus merula",
  "common_name_it": "Merlo",
  "confidence": 0.87,
  "status": "valid",
  "device_slug": "8e2a1c04b3f7",
  "region": "Lombardia"
}

2 · Snapshot mensili

Ogni primo giorno del mese pubblichiamo lo snapshot del mese precedente: CSV UTF-8, header RFC 4180, un file per le detection (chunked in blocchi da 50k righe se superano 100k) e un aggregato per specie. Ogni snapshot ha un manifest.json con sha256, conteggi, licenza e citazione BibTeX/APA. Il MAC hardware del device è anonimizzato via SHA-256 (primi 12 caratteri) — lo slug resta stabile tra snapshot successivi, per seguire lo stesso sensore nel tempo.

Primo snapshot in preparazione per settembre 2026. Lo script di generazione è pronto (scripts/snapshot-monthly.ts) e verrà eseguito al primo giorno del mese, sui dati reali di luglio-agosto.

3 · Feed RSS

Feed RSS 2.0 delle ultime rilevazioni validate. Utile per sistemi di notifica, dashboard esterne, integrazioni Zapier / Make. Parametri di filtro opzionali: species (nome scientifico esatto), region, limit (default 50, max 200).

Endpoint

https://ecocanto.it/feed/rss

Esempi

# Ultime 50 detection della rete
curl -sL https://ecocanto.it/feed/rss

# Solo merlo (Turdus merula), ultimi 20
curl -sL "https://ecocanto.it/feed/rss?species=Turdus%20merula&limit=20"

# Solo Lombardia
curl -sL "https://ecocanto.it/feed/rss?region=Lombardia"

4 · DOI Zenodo trimestrale

Ogni trimestre pubblichiamo un deposito Zenodo con lo snapshot cumulativo dei tre mesi appena chiusi e un identificatore DOI permanente. Il primo DOI ufficiale è previsto per il Q1 2027, in coerenza con la roadmap del metodo v2.0. Il workflow di deposito è già scritto (.github/workflows/zenodo-doi-quarterly.yml) e verrà attivato appena il primo trimestre di dati validati sarà completo.

Primo DOI Zenodo previsto per Q1 2027. Nel frattempo, gli snapshot mensili con sha256 nel manifest sono già citabili come pre-print del dataset.

5 · Licenze

Dati grezzi

CC0 1.0

Detection, aggregati specie, snapshot CSV, endpoint JSON. Public domain: nessuna attribuzione richiesta, ma apprezzata.

creativecommons.org/publicdomain/zero/1.0/

Contenuti editoriali

CC BY 4.0

Testi del magazine, whitepaper, schede specie, diario di Mira. Attribuzione: "Ecocanto — Terra Sense" con link a ecocanto.it.

creativecommons.org/licenses/by/4.0/

La pagina completa con testo legale è a /license.

6 · Come citarci

Per pubblicazioni scientifiche, tesi, report di sostenibilità. Ogni snapshot mensile porta la propria citazione nel manifest, aggiornata con l'etichetta del periodo. Quando il DOI Zenodo sarà attivo, sostituirà l'URL generico.

APA

Terra Sense (2026). Ecocanto — rilevazioni bioacustiche della rete Upupa in Italia. Snapshot pubblico [YYYY-MM]. https://ecocanto.it/data

BibTeX

@dataset{ecocanto_2026,
  author  = {Terra Sense},
  title   = {Ecocanto — rilevazioni bioacustiche della rete Upupa in Italia},
  year    = 2026,
  version = {snapshot YYYY-MM},
  url     = {https://ecocanto.it/data},
  license = {CC0-1.0}
}

Domande, dubbi, richieste specifiche di export (per esempio Darwin Core Archive per GBIF)? Scrivici a info@ecocanto.it.