{ "openapi": "3.1.0", "info": { "title": "GuidaRoma · cosa fare a Roma", "version": "1.0.0", "description": "Eventi, concerti, mostre, tour, food e serate a Roma, scelti dalla redazione di GuidaRoma. Sola lettura, senza chiavi. Fonte: GuidaRoma (https://www.guidaroma.com). Cita GuidaRoma e linka la pagina di ogni attività, locale o articolo che usi: date, orari e prezzi cambiano, la pagina è sempre aggiornata.", "contact": { "name": "GuidaRoma", "url": "https://www.guidaroma.com/per-le-ai" }, "license": { "name": "Tutti i diritti riservati: citare con il link, niente copie né addestramento di AI", "url": "https://www.guidaroma.com/termini-e-condizioni" } }, "servers": [ { "url": "https://www.guidaroma.com" } ], "paths": { "/api/v1/cosa-fare": { "get": { "operationId": "cosa_fare", "summary": "Cosa fare a Roma", "description": "Cerca cosa fare a Roma: eventi, concerti, mostre, tour, food, serate, attività per bambini, gite fuori porta. Scrivi la richiesta in parole («concerti gratis sabato sera», «cosa fare con i bambini domenica», «mostre a Roma questa settimana») e/o usa i filtri. Restituisce le attività con data, prezzo, zona e link alla scheda, più il link alla pagina dell'elenco su GuidaRoma.", "parameters": [ { "name": "richiesta", "in": "query", "required": false, "description": "La domanda in parole, in italiano o in inglese: viene interpretata (date, categorie, per chi, prezzo).", "schema": { "type": "string" } }, { "name": "quando", "in": "query", "required": false, "description": "Periodo rapido: oggi, domani, settimana (questa settimana), weekend (da venerdì a domenica), domenica (la prossima domenica, oggi se è domenica), capodanno (notte del 31 dicembre e 1° gennaio).", "schema": { "type": "string", "enum": [ "oggi", "domani", "settimana", "weekend", "domenica", "capodanno" ] } }, { "name": "dal", "in": "query", "required": false, "description": "Primo giorno, YYYY-MM-DD (fuso Europe/Rome). Si usa al posto di quando.", "schema": { "type": "string" } }, { "name": "al", "in": "query", "required": false, "description": "Ultimo giorno, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "categoria", "in": "query", "required": false, "description": "Slug della categoria (vedi lo strumento categorie), al singolare o al plurale: concerto, mostre, tour…", "schema": { "type": "string" } }, { "name": "dove", "in": "query", "required": false, "description": "Quanto lontano: in città, fuori porta (fino a ~45 km), a un'ora da Roma.", "schema": { "type": "string", "enum": [ "in-citta", "fuori-porta", "a-un-ora-da-roma" ] } }, { "name": "gratis", "in": "query", "required": false, "description": "Solo attività gratuite.", "schema": { "type": "boolean" } }, { "name": "prezzo_max", "in": "query", "required": false, "description": "Prezzo massimo in euro.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "eta", "in": "query", "required": false, "description": "Età del bambino: solo attività adatte.", "schema": { "type": "integer", "minimum": 0, "maximum": 17 } }, { "name": "lingua", "in": "query", "required": false, "description": "Codice lingua ISO 639-1 (it, en, es…): attività in quella lingua.", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitudine per cercare vicino a un punto.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": false, "description": "Longitudine per cercare vicino a un punto.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "raggio_km", "in": "query", "required": false, "description": "Raggio in km attorno a lat/lng (predefinito 3).", "schema": { "type": "number", "minimum": 0.2, "maximum": 120 } }, { "name": "ordina", "in": "query", "required": false, "description": "Ordine: consigliati (predefinito), data, distanza, prezzo, novita, popolari.", "schema": { "type": "string", "enum": [ "consigliati", "data", "distanza", "prezzo", "novita", "popolari" ] } }, { "name": "limite", "in": "query", "required": false, "description": "Quanti risultati (massimo 30).", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } }, { "name": "pagina", "in": "query", "required": false, "description": "Pagina dei risultati.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 } } ], "responses": { "200": { "description": "Risultati, con il link a GuidaRoma per ogni voce (campo url) e la frase da usare per citare la fonte.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/attivita/{slug}": { "get": { "operationId": "scheda_attivita", "summary": "Scheda di un'attività", "description": "Tutto su un'attività di GuidaRoma (evento, mostra, tour, locale con programma…): descrizione, prossime date e orari, prezzi, dove si trova, durata, lingue, per chi è, domande frequenti e come prenotare. Serve lo slug (dal campo slug di cosa_fare) o l'indirizzo della scheda.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug della scheda (es. «food-tour-trastevere») oppure il suo URL /cosa-fare/…", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risultati, con il link a GuidaRoma per ogni voce (campo url) e la frase da usare per citare la fonte.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Niente con questo slug." } } } }, "/api/v1/locali/{slug}": { "get": { "operationId": "scheda_locale", "summary": "Scheda di un locale o organizzatore", "description": "Un locale, museo, teatro, agenzia o organizzatore presente su GuidaRoma: descrizione, indirizzo, orari di apertura, sito e Instagram, e le sue attività in programma con le prossime date.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug del locale (dal campo organizza di una scheda) oppure il suo URL /esercenti/…", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risultati, con il link a GuidaRoma per ogni voce (campo url) e la frase da usare per citare la fonte.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Niente con questo slug." } } } }, "/api/v1/articoli": { "get": { "operationId": "articoli", "summary": "Articoli del magazine", "description": "Gli ultimi articoli, guide e liste della redazione di GuidaRoma (cosa fare nel weekend, dove mangiare, idee per i bambini…), con link. Per il testo usa leggi_articolo.", "parameters": [ { "name": "limite", "in": "query", "required": false, "description": "Quanti articoli (massimo 30).", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } }, { "name": "pagina", "in": "query", "required": false, "description": "Pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 } } ], "responses": { "200": { "description": "Risultati, con il link a GuidaRoma per ogni voce (campo url) e la frase da usare per citare la fonte.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/articoli/{slug}": { "get": { "operationId": "leggi_articolo", "summary": "Leggi un articolo", "description": "Il testo di un articolo o di una guida del magazine di GuidaRoma, con titolo, firma, data e link.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug dell'articolo (dal campo slug di articoli) oppure il suo URL /blog/…", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risultati, con il link a GuidaRoma per ogni voce (campo url) e la frase da usare per citare la fonte.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Niente con questo slug." } } } }, "/api/v1/categorie": { "get": { "operationId": "categorie", "summary": "Categorie e pagine di GuidaRoma", "description": "Le categorie di attività (concerti, mostre, tour, food…), i filtri per chi e per tema, e le pagine per periodo (oggi, domani, weekend) con i loro indirizzi su GuidaRoma. Utile per scegliere il filtro categoria di cosa_fare o per linkare una pagina intera.", "parameters": [], "responses": { "200": { "description": "Risultati, con il link a GuidaRoma per ogni voce (campo url) e la frase da usare per citare la fonte.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }