{"openapi":"3.0.3","info":{"title":"Piazza in Festa · API eventi","description":"API REST read-only sugli eventi pubblicati su piazzainfesta.it: sagre, feste patronali, concerti, mostre e manifestazioni dei comuni italiani. Autenticazione con API key nell'header X-Api-Key (per averne una scrivici da https://piazzainfesta.it/contatti). Rate limit: 120 richieste/minuto per chiave. Una chiave puo' essere limitata ad alcune regioni: in quel caso vede solo i loro dati e le richieste esplicite fuori scope rispondono 403.","version":"1.0.0","contact":{"name":"Richiedi una API key","url":"https://piazzainfesta.it/contatti"}},"servers":[{"url":"https://api.piazzainfesta.it"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Evento":{"type":"object","properties":{"id":{"type":"string","example":"482"},"titolo":{"type":"string","nullable":true},"categoria":{"type":"string","nullable":true,"enum":["religioso","sagra_enogastronomica","musica_concerto","culturale_mostra","fiera_mercato","sportivo","spettacolo","istituzionale","altro",null]},"descrizione":{"type":"string","nullable":true},"info_utili":{"type":"string","nullable":true},"data_inizio":{"type":"string","nullable":true,"example":"2026-07-18"},"data_fine":{"type":"string","nullable":true,"example":"2026-07-20"},"stato_temporale":{"type":"string","nullable":true,"enum":["futuro","in_corso","passato","incerto",null]},"comune":{"type":"string","description":"Identificativo del comune (slug): la lista dei valori e' in /v1/comuni","example":"genova"},"comune_nome":{"type":"string","nullable":true,"example":"Genova"},"provincia":{"type":"string","nullable":true,"example":"GE"},"regione":{"type":"string","nullable":true,"example":"Liguria"},"luogo":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lon":{"type":"number","nullable":true},"maps_url":{"type":"string","nullable":true},"organizzatore_ente":{"type":"string","nullable":true},"fonte_url":{"type":"string","nullable":true,"description":"Pagina pubblica della fonte originale (tipicamente il sito del comune)"},"locandina_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Comune":{"type":"object","properties":{"comune":{"type":"string","description":"Identificativo (slug): il valore da usare nel filtro comune di /v1/eventi","example":"genova"},"comune_nome":{"type":"string","nullable":true,"example":"Genova"},"provincia":{"type":"string","nullable":true,"example":"GE"},"regione":{"type":"string","nullable":true,"example":"Liguria"},"lat":{"type":"number","nullable":true,"description":"Centroide del comune"},"lon":{"type":"number","nullable":true},"eventi":{"type":"integer","description":"Numero di eventi pubblicati (0 se il comune non ne ha)","example":42}}}}},"paths":{"/v1/eventi":{"get":{"summary":"Lista eventi (paginata, filtrabile)","parameters":[{"name":"regione","in":"query","schema":{"type":"string","enum":["Sicilia","Piemonte","Valle d'Aosta/Vallée d'Aoste","Lombardia","Liguria","Trentino-Alto Adige/Südtirol","Umbria","Veneto","Emilia-Romagna","Toscana"]}},{"name":"comune","in":"query","description":"Identificativo del comune (slug), vedi /v1/comuni","schema":{"type":"string"}},{"name":"categoria","in":"query","schema":{"type":"string","enum":["religioso","sagra_enogastronomica","musica_concerto","culturale_mostra","fiera_mercato","sportivo","spettacolo","istituzionale","altro"]}},{"name":"q","in":"query","description":"Ricerca testuale su titolo e descrizione (min 3 caratteri)","schema":{"type":"string","minLength":3}},{"name":"dal","in":"query","description":"data_inizio >= (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"al","in":"query","description":"data_inizio <= (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"updated_since","in":"query","description":"Solo eventi creati/aggiornati dopo questo istante (ISO 8601): sync incrementale","schema":{"type":"string","format":"date-time"}},{"name":"attivi","in":"query","description":"1 = solo eventi non ancora conclusi","schema":{"type":"string","enum":["1"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Pagina di eventi","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"page_size":{"type":"integer"},"eventi":{"type":"array","items":{"$ref":"#/components/schemas/Evento"}}}}}}},"400":{"description":"Parametro non valido"},"401":{"description":"API key mancante o non valida"},"403":{"description":"Regione o evento fuori dallo scope della chiave"},"429":{"description":"Rate limit superato (120 req/min)"}}}},"/v1/comuni":{"get":{"summary":"Lookup comuni: gli identificativi validi per il filtro comune","parameters":[{"name":"regione","in":"query","schema":{"type":"string","enum":["Sicilia","Piemonte","Valle d'Aosta/Vallée d'Aoste","Lombardia","Liguria","Trentino-Alto Adige/Südtirol","Umbria","Veneto","Emilia-Romagna","Toscana"]}}],"responses":{"200":{"description":"Tutti i comuni delle regioni attive (eventi=0 dove non ce ne sono)","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"comuni":{"type":"array","items":{"$ref":"#/components/schemas/Comune"}}}}}}},"400":{"description":"Regione non valida"},"401":{"description":"API key mancante o non valida"},"403":{"description":"Regione o evento fuori dallo scope della chiave"},"429":{"description":"Rate limit superato (120 req/min)"}}}},"/v1/eventi/{id}":{"get":{"summary":"Dettaglio evento","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Evento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evento"}}}},"401":{"description":"API key mancante o non valida"},"403":{"description":"Regione o evento fuori dallo scope della chiave"},"404":{"description":"Evento non trovato"}}}}}}