Stai organizzando il sabato in funzione della trasferta dell’Arsenal a Newcastle. Un amico a New York ha bisogno dell’ora del calcio d’inizio. Poi qualcuno nella chat di gruppo chiede com’è andata l’ultima trasferta dell’Arsenal. La prima risposta si trova nel calendario delle partite. Per la seconda, devi sapere a chi appartiene il gol dell’1 in “Liverpool 0, Arsenal 1”.
Costruirai Matchday Notebook, un chatbot sul calcio che cerca le prossime tre partite di Premier League, legge gli ultimi cinque risultati di campionato dell’Arsenal e trova la sua posizione in classifica. L’esempio è fissato al 18 novembre 2026. La trasferta a Newcastle era prevista per sabato 21 novembre alle 17:30 UTC, ovvero le 12:30 a New York.
La pagina della partita del fornitore e l’Agente privato concordano sull’orario del calcio d’inizio. La conversazione in Quickchat AI è stata eseguita su una replica datata di dati pubblici, che puoi riprodurre qui sotto.
Controlla la partita contro il Newcastle o scarica il kit Matchday Notebook. Decomprimilo ed esegui python3 replay.py per vedere le tre partite, i cinque risultati e la riga della classifica senza un account. Lo stesso kit include le impostazioni dell’Azione e il Main Prompt per collegare il tuo feed.
1. Quale club e competizione seguirà il chatbot?
Per prima cosa, definisci il club e il campionato. L’andamento in campionato dell’Arsenal può cambiare a seconda che si conti o meno una partita europea del martedì sera. In questo taccuino Arsenal significa squadra 57 e campionato significa Premier League 2021, nota anche con il suo codice PL.
- Apri il modulo di registrazione di football-data.org. Inserisci il tuo nome e l’indirizzo email, accetta i termini e seleziona Create account. Controlla la tua competizione nell’elenco di copertura. Il piano gratuito include la Premier League, con calendari e punteggi ritardati.
Usa un indirizzo email che puoi controllare. football-data.org invia la chiave API a quell’indirizzo dopo la registrazione. Il piano gratuito consente 10 richieste al minuto.
Se hai già un account, accedi con la tua email e il token API. Se ti serve un’altra copia del token, richiedila via email usando l’indirizzo con cui ti sei registrato. Conserva il token per l’header protetto nel Passaggio 2.
Controlla il tuo piano in Subscription e cerca il tuo campionato in Available competitions. Questo estratto mostra la UEFA Champions League (CL) e la Bundesliga (BL1).
- Per seguire un altro club, cercalo nell’elenco delle squadre della competizione, ad esempio
GET /v4/competitions/PL/teams. Usa l’ID della squadra e l’ID della competizione restituiti nelle richieste delle partite qui sotto. La guida rapida v4 contiene entrambe le ricerche. - Crea un Agente Quickchat AI, chiamalo Matchday Notebook, e mantienilo privato mentre testi. Hai bisogno di crediti disponibili per conversazioni e simulazioni. Apri Identity → AI Persona → Main Prompt e incolla le istruzioni qui sotto. Gli screenshot e le impostazioni copiabili usano l’inglese.
Mantieni lo stesso club in entrambi i posti. Nel prodotto, le istruzioni dell’Agente si trovano sotto Identity.
Copia il Matchday Notebook Main Prompt
You are Matchday Notebook, an Arsenal Premier League companion. Use get_club_fixtures for the schedule, get_recent_results for form and get_league_standings for the league table. For match reads, use an inclusive UTC start date and an exclusive end date. Ask for dates when the window is unclear.
List up to the requested number of TIMED or SCHEDULED fixtures in kickoff order. Give the date, time and timezone; say when the hour is unconfirmed. Flag postponed or cancelled games separately. For form, sort FINISHED matches newest first, take up to five and read full-time scores home first. Judge wins, draws and losses from Arsenal's side. For standings, find Arsenal (team 57) in the TOTAL table. Give the season, position, games played and points.
Keep answers short. Link a match to https://native-stats.org/match/ID using its returned ID, and the Premier League table to https://native-stats.org/competition/PL/. Attribute football-data.org, give the relevant date and identify any snapshot as a snapshot. Quote a retrieval time only if supplied. Keep null scores unknown. Report empty windows, missing scores and failed reads accurately. Stop after a rate limit. Do not predict scores.
2. Come si ottiene la prossima partita dell’Arsenal?
Inizia con l’Azione che risponde alla domanda della chat di gruppo sul calcio d’inizio. Una singola richiesta restituisce entrambi i club, l’orario programmato e lo stato della partita. Lascia il filtro dello stato aperto in modo che un eventuale rinvio possa comunque essere visualizzato. Un record TIMED ha un orario di calcio d’inizio. Per SCHEDULED, comunica al lettore che l’orario deve ancora essere confermato.
- Apri Actions & MCPs → Add Action → API Action → Create manually. Imposta API Action Name su
get_club_fixturese When to run su AI decides. Sotto What to ask the user first, aggiungi gli input Text richiestidate_fromedate_to, entrambi con No default. Le loro descrizioni sono “Prima data UTC da includere, YYYY-MM-DD” e “Prima data UTC da escludere, YYYY-MM-DD”. - Per API Endpoint, scegli GET e inserisci l’URL qui sotto. Apri Query Params e imposta
competitionssul letterale2021. AggiungidateFromedateTo. Per ogni valore, usa Add AI Data → Parameters per inserire l’input di data corrispondente. Lascia Body vuoto. - Incolla la descrizione qui sotto sotto API Action Description e salva l’Azione. Sotto Headers, la credenziale andrà in una riga
X-Auth-Tokendi sola scrittura. Configurala prima della tua prima richiesta. Aggiungi una seconda intestazione ordinaria conAcceptcome chiave eapplication/jsoncome valore. Usa le stesse due intestazioni su tutte e tre le Azioni.
https://api.football-data.org/v4/teams/57/matches
Segui il percorso delle partite della squadra dalla documentazione di riferimento del fornitore all’interno dell’Azione. L’Arsenal è fissato nell’URL, il campionato in Query Params e le due date provengono dalla conversazione.
Copia la descrizione dell'Azione relativa alla partita
Use for Arsenal's upcoming Premier League fixtures in the requested date window. Sort by utcDate ascending. Show TIMED or SCHEDULED matches and flag postponements or cancellations separately. State the window if fewer fixtures are returned.
Gli esempi di richiesta del fornitore inseriscono la chiave API in X-Auth-Token. Usa lo stesso nome di header in Headers su get_club_fixtures.
Il modulo di accesso richiede la tua email e il token API. In Quickchat AI, solo il token va nella riga protetta X-Auth-Token.
Inserisci il token privatamente. La dashboard può sostituire un segreto salvato. Per rendere quell’intestazione di sola scrittura, usa la connessione dell’account una volta per Azione. Connetti il tuo account usando la guida di configurazione Quickchat AI in ChatGPT o Claude. Chiedi all’assistente connesso di preparare l’intestazione con un marcatore innocuo usando l’istruzione qui sotto. Quindi apri tu stesso la scheda Headers dell’Azione, sostituisci il valore in quella stessa riga con il tuo token football-data.org grezzo e seleziona Save changes. Riapri l’editor e controlla che visualizzi [redacted]. Mantieni il token nella dashboard e fuori dalla conversazione.
On Matchday Notebook, set the X-Auth-Token header of get_club_fixtures to the literal value REPLACE_IN_DASHBOARD with is_secret=true. Preserve the rest of the settings. Read the Action back and confirm that the header is secret and the value is [redacted]. Stop before testing.
Questa è l’intestazione salvata. Il fornitore si aspetta il token da solo, senza un prefisso Bearer.
Fai la prima prova di lettura. In Test Response → Test the API, fornisci una data di inizio e il giorno successivo all’ultima data desiderata. Quindi, abilita l’Azione e chiedi in AI Preview le prossime tre partite di campionato in quell’intervallo di tempo. Per una build in tempo reale, scegli date future. L’esempio d’archivio ha usato 2026-11-18 e 2026-12-03, quindi la sera del 2 dicembre è stata inclusa. Controlla la partita più vicina aprendo il relativo link di origine. La documentazione di riferimento v4 sui filtri data spiega perché la data di fine è esclusa.
Nell’esempio, la trasferta contro il Newcastle è capitata il 21 novembre, la partita in casa contro il Manchester City il 29 novembre e la trasferta contro il Brentford il 2 dicembre. Se la richiesta fosse terminata il 2 dicembre, la partita contro il Brentford sarebbe stata esclusa.
3. Come leggere gli ultimi cinque risultati dell’Arsenal?
La partita più significativa in questo esempio è finita Liverpool 0, Arsenal 1. Se il chatbot considerasse sempre il primo numero come il punteggio dell’Arsenal, trasformerebbe una vittoria in trasferta in una sconfitta. Mantieni ogni punteggio nell’ordine casa-trasferta e usa l’ID della squadra per stabilire il risultato dell’Arsenal.
- Crea una seconda API Action chiamata
get_recent_results. Usa lo stesso endpoint GET, gli stessi input e chip per le date e lo stesso filtro per la competizione. Aggiungi la riga di querystatuscon il valore letteraleFINISHED. - Imposta la descrizione qui sotto. Ripeti la configurazione dell’intestazione di sola scrittura per
get_recent_results, controlla la maschera e abilita l’Azione. - Chiedi le cinque partite di campionato più recenti in un intervallo specificato. Per l’esempio, usa dal 1° ottobre al 17 novembre 2026. Ordina per
utcDateprima di prenderne cinque. Se l’intervallo restituisce solo tre, mostra quelle tre e offriti di cercare più indietro.
Copia la descrizione dell'azione dei risultati
Use for Arsenal's recent Premier League form in the requested date window. Sort FINISHED matches newest first, then take up to five. Use both full-time goals and the home and away team IDs to judge each result from Arsenal's perspective.
Per prima cosa individua l’Arsenal come squadra in trasferta, poi leggi il gol segnato in trasferta. Lo zero del Liverpool indica la porta inviolata.
Leggi la serie di risultati dalla più recente. L’Arsenal ha battuto l’Hull 1-0, ha vinto 1-0 in casa del Liverpool, ha battuto l’Everton 2-0, ha vinto 1-0 in casa del Nottingham Forest e ha battuto il Leeds 2-1. Il bilancio è di cinque vittorie, sette gol fatti e uno subito. Il tabellino della partita contro il Liverpool è un buon test perché la squadra vincente è la seconda.
Nei dati di prova salvati, l’elenco restituito inizia deliberatamente con la partita del Leeds e finisce con quella dell’Hull. L’ordinamento in base all’orario di calcio d’inizio sposta l’Hull in cima alla risposta. Apri la risposta dell’Azione accanto alla chat e confronta la prima e l’ultima partita in entrambi gli elenchi.
Cinque vittorie possono nascondere un dettaglio importante. Due di queste erano in trasferta, quindi il gol della vittoria si trova a destra.
4. Da dove vengono la posizione in classifica e i punti?
Cinque vittorie ti dicono com’è stato l’andamento delle ultime settimane. La posizione in classifica dipende anche da tutte le partite precedenti e dai risultati delle altre squadre. Fornisci all’Agente un’Azione separata per la classifica.
- Chiamala
get_league_standings. Scegli GET, incolla l’endpoint qui sotto e lascia vuoti gli input, i parametri di query e il corpo. Usa AI decides, aggiungi la descrizione qui sotto e ripeti la configurazione dell’intestazione di sola scrittura per questa Action. - In Test Response, cerca in
standingsla voce il cuitypeèTOTAL. All’interno della suatable, trova la riga in cuiteam.idè uguale a57. Abilita l’Azione e chiedi “In che posizione è l’Arsenal nella classifica della Premier League?” - Confronta
position,playedGamesepointscon la fonte per la stessa stagione e data. Il 18 novembre la classifica della Premier League su Native Stats mostrava 1° posto, 10 partite giocate, 27 punti. La classifica attuale cambierà man mano che le altre squadre giocano.
https://api.football-data.org/v4/competitions/PL/standings
Copia la descrizione dell'Azione per la classifica
Use for the current Premier League table. Find team ID 57 in standings where type is TOTAL. Report season, position, playedGames and points. If the row is missing, say the position is unavailable.
Leggi una singola riga in TOTAL. I 27 punti coprono tutte e dieci le partite di campionato nello snapshot.
5. È possibile risalire alle fonti del resoconto pre-partita?
Avvia una nuova conversazione in AI Preview. Chiedi le prossime tre partite, poi prosegui con “Com’è stato il nostro andamento nelle ultime cinque partite di campionato?”, fornisci l’intervallo di date e infine chiedi “Questo che posizione ci dà in classifica?”. In Inbox, apri il marcatore dell’Azione richiamata per ogni risposta. La sezione View logs dell’Azione ti permette di confrontare i parametri e la risposta con ciò che ha visto il tifoso. La guida alla creazione di un’API Action mostra dove trovare questi controlli.
Per ottenere il riepilogo combinato della giornata mostrato all’inizio dell’articolo, poni la domanda qui sotto usando le date dell’esempio salvato. Per un riepilogo aggiornato, usa le date future per le prossime partite e le date recenti per i risultati.
Arsenal briefing for 18 Nov 2026: next away kickoff this week (UTC), last five since 1 Oct, and table position. Three short lines.
Ispeziona le date e l’ID della partita nella chiamata. Nell’esempio locale, 560651 è la partita contro il Newcastle.
Per un controllo ripetibile, apri Conversations → Testing, crea un dataset e salva le tre domande. Aggiungi le due domande limite mostrate di seguito. Esegui il dataset dopo aver modificato la descrizione di un’Action e controlla le chiamate insieme alle risposte. Usa una risposta controllata per esercitare uno stato raro o un errore. Una domanda ipotetica da sola testa la formulazione di una risposta.
Usa le stesse domande dopo ogni modifica. Il risultato in trasferta permette di individuare un errore nel punteggio che un test con sole partite in casa non noterebbe.
| Caso di test | Cosa dovrebbe sentire il tifoso |
|---|---|
Una partita è stata rinviata ed entrambi i gol sono null. È stato un pareggio? | La partita è stata rinviata. Non c’è un punteggio registrato. |
Una ricerca riuscita restituisce una lista matches vuota. L’intera stagione è vuota? | Nessuna partita trovata in quell’intervallo di tempo. Specifica le date che hai cercato. |
| Il provider restituisce 401 o 403. | La ricerca non è andata a buon fine. Controlla il token salvato e la copertura della competizione. |
| Il provider restituisce 429. | Limite di richieste raggiunto. Fermati e riprova più tardi. |
Una finestra vuota ha comunque una richiesta riuscita. L’assistente può offrire di ampliare le date.
Per un secondo parere su un calcio d’inizio modificato, confrontalo con le modifiche al calendario pubblicate dalla lega. Tieni insieme la data programmata, il fuso orario e la data in cui hai controllato. Il feed gratuito può avere dei ritardi rispetto a una modifica della programmazione televisiva, un dettaglio importante se qualcuno sta pianificando il proprio sabato in base alla risposta.
Football data provided by the Football-Data.org API. L’esempio datato utilizza le pagine pubbliche Native Stats del provider. Consulta i piani dei feed e i limiti di richieste per la copertura e l’aggiornamento attuali.
Domande frequenti
Quale API di calcio posso usare per un chatbot sulle partite?
L’API v4 di football-data.org fornisce calendario, risultati e classifiche per le competizioni coperte. Usa l’endpoint delle partite della squadra per il calendario e l’andamento recente e l’endpoint della classifica della competizione per la posizione in campionato.
I punteggi football-data.org sono in diretta con il piano gratuito?
Il piano gratuito include risultati e calendari non in diretta, classifiche per le competizioni coperte e 10 richieste al minuto. Includi la fonte e la data in ogni risposta e controlla il tuo piano se hai bisogno di risultati in tempo reale.
Come cambio l’Arsenal con un’altra squadra?
Trova l’ID della squadra e della competizione del club su football-data.org. Sostituisci la squadra 57 in entrambe le Azioni relative alle partite, cambia il filtro numerico della competizione e l’URL della classifica, quindi aggiorna il nome del club e l’ID della squadra nelle istruzioni. Fai una prova con una partita che conosci.
Come ottengo le ultime cinque partite dal punto di vista della squadra?
Filtra le partite di campionato terminate in un intervallo di date specificato, ordina per calcio d’inizio dalla più recente alla meno recente e selezionane fino a cinque. Per ogni risultato, controlla se la tua squadra ha giocato in casa o in trasferta prima di assegnare una vittoria, un pareggio o una sconfitta. Se ne trovi meno di cinque, indica il numero trovato.
Cosa significa un punteggio vuoto per una partita rinviata?
Un punteggio vuoto significa che il fornitore non ha fornito un totale di gol per quella squadra. Mantieni visibile lo stato della partita e lascia il punteggio sconosciuto. Un pareggio a reti inviolate richiede una partita terminata con due zeri registrati.
Come converto l’orario del calcio d’inizio di una partita nel mio fuso orario?
Inizia con il calcio d’inizio UTC della partita, usa un fuso orario nominato come America/New_York e mantieni la data nella risposta. L’ora legale e un cambio di giorno del calendario possono entrambi influenzare l’ora visualizzata.