{
 "openapi": "3.1.0",
 "info": {
  "title": "calcio.it — API pubblica di lettura",
  "version": "v1+ff2fe8033a96d075deced900e21e455f48022ba9",
  "description": "Classifiche, risultati, marcatori e previsioni pre-partita confrontate con l'esito, serviti dall'archivio di calcio.it. Sola lettura, nessuna autenticazione. Le previsioni sono frequenze naturali: non quote, non consigli di giocata. Uso consentito con citazione della fonte. Si pubblicano le nostre registrazioni: valori normalizzati nel nostro schema, con identificativi interni e istante di cattura. Le risposte integrali dei fornitori non sono ridistribuite.",
  "license": {
   "name": "Uso consentito con citazione della fonte (calcio.it)",
   "url": "https://calcio.it/api/v1"
  }
 },
 "servers": [
  {
   "url": "https://calcio.it"
  }
 ],
 "security": [],
 "paths": {
  "/api/v1/competizioni": {
   "get": {
    "operationId": "elenca_competizioni",
    "summary": "Competizioni coperte",
    "description": "Elenco delle competizioni in archivio con codice, nome, paese, genere e categoria (assoluto/giovanile). I codici servono come parametro `competizione` degli altri strumenti.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/classifica": {
   "get": {
    "operationId": "classifica",
    "summary": "Classifica",
    "description": "Classifica della stagione mostrata sul sito, dal nostro archivio, con l'istante a cui risale.",
    "parameters": [
     {
      "name": "competizione",
      "in": "query",
      "required": false,
      "description": "Codice della competizione, come compare in `competizioni` (es. it-serie-a, de-bundesliga). Senza, Serie A. Un codice sconosciuto risponde 404, mai un ripiego.",
      "schema": {
       "type": "string"
      },
      "example": "it-serie-a"
     }
    ],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/marcatori": {
   "get": {
    "operationId": "marcatori",
    "summary": "Classifica marcatori",
    "description": "Classifica marcatori (solo gol). Sulle competizioni giovanili non contiene nomi di persona, per scelta dichiarata nella risposta.",
    "parameters": [
     {
      "name": "competizione",
      "in": "query",
      "required": false,
      "description": "Codice della competizione, come compare in `competizioni` (es. it-serie-a, de-bundesliga). Senza, Serie A. Un codice sconosciuto risponde 404, mai un ripiego.",
      "schema": {
       "type": "string"
      },
      "example": "it-serie-a"
     }
    ],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/giornata": {
   "get": {
    "operationId": "ultima_giornata",
    "summary": "Ultima giornata",
    "description": "Ultima giornata conclusa, con risultati e stato di ogni partita (`conclusa: false` se nessuna lo è ancora: è allora il turno in corso). Orari `inizio` in UTC. Il campo `id` di ogni partita è quello da passare a `previsioni_partita`.",
    "parameters": [
     {
      "name": "competizione",
      "in": "query",
      "required": false,
      "description": "Codice della competizione, come compare in `competizioni` (es. it-serie-a, de-bundesliga). Senza, Serie A. Un codice sconosciuto risponde 404, mai un ripiego.",
      "schema": {
       "type": "string"
      },
      "example": "it-serie-a"
     }
    ],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/proiezioni": {
   "get": {
    "operationId": "proiezioni_fine_stagione",
    "summary": "Proiezioni di fine stagione",
    "description": "Probabilita' di fine stagione per squadra (posizione finale, titolo, promozione, play-off, play-out, retrocessione) da migliaia di finali simulate col nostro modello, solo per i campionati italiani in cui il modello ha superato la prova a ritroso; altrove `pubblicabile: false` col motivo. Non sono quote ne' consigli di giocata; sotto il 2% e sopra il 98% vanno presentate come «meno del 2%» e «oltre il 98%». Porta `aggiornatoIl`.",
    "parameters": [
     {
      "name": "competizione",
      "in": "query",
      "required": false,
      "description": "Codice della competizione, come compare in `competizioni` (es. it-serie-a, de-bundesliga). Senza, Serie A. Un codice sconosciuto risponde 404, mai un ripiego.",
      "schema": {
       "type": "string"
      },
      "example": "it-serie-a"
     }
    ],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/archivio": {
   "get": {
    "operationId": "stato_archivio",
    "summary": "Stato dell'archivio",
    "description": "Quante previsioni pre-partita sono registrate e quante sono già state confrontate con l'esito.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/archivio/previsioni": {
   "get": {
    "operationId": "previsioni_partita",
    "summary": "Previsioni di una partita",
    "description": "Previsioni registrate per una partita, con l'istante di cattura. Sono frequenze naturali, non quote e non consigli di giocata; quelle marcate come ricostruite sono state lette dopo il fischio finale.",
    "parameters": [
     {
      "name": "partita",
      "in": "query",
      "required": true,
      "description": "Identificativo della partita, come compare nel campo `id` di `ultima_giornata`.",
      "schema": {
       "type": "string"
      },
      "example": "19713572"
     }
    ],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  },
  "/api/v1/archivio/accuratezza": {
   "get": {
    "operationId": "accuratezza_previsioni",
    "summary": "Accuratezza delle previsioni",
    "description": "Verifiche aggregate per competizione e mercato (Brier, log-loss, skill contro la frequenza storica: più bassi Brier e log-loss, meglio è). Le righe ricostruite dopo la partita non sono un track record.",
    "parameters": [
     {
      "name": "lega",
      "in": "query",
      "required": false,
      "description": "Codice della competizione per filtrare le verifiche, come in `competizioni`. Senza, tutte.",
      "schema": {
       "type": "string"
      },
      "example": "brazil-serie-a"
     }
    ],
    "responses": {
     "200": {
      "description": "Il dato, con l'istante a cui risale.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Errore"
     },
     "404": {
      "$ref": "#/components/responses/Errore"
     },
     "503": {
      "$ref": "#/components/responses/Errore"
     }
    }
   }
  }
 },
 "components": {
  "responses": {
   "Errore": {
    "description": "Errore dichiarato: il motivo e' nel campo `errore`.",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "errore": {
         "type": "string"
        }
       },
       "required": [
        "errore"
       ]
      }
     }
    }
   }
  }
 }
}