API per sviluppatori
Documentazione sull'API di valutazione degli scacchi
L'API Chess Rating fornisce accesso programmatico allo stesso motore di calcolo Elo che alimenta i calcolatori su questo sito. Gli sviluppatori che creano strumenti di gestione dei club, dashboard per la reportistica dei tornei, piattaforme di coaching o prodotti editoriali possono integrare i calcoli delle valutazioni direttamente nei loro flussi di lavoro senza reimplementare la logica della formula. Questa documentazione copre gli endpoint disponibili, i formati di richiesta e risposta, i requisiti di autenticazione e l'approccio al controllo delle versioni che mantiene stabili le integrazioni. Puoi continuare con Widget di valutazione degli scacchi incorporabili per una guida collegata.
Endpoint di calcolo disponibili
L'API supporta tre flussi di lavoro di calcolo principali: modifica della valutazione di una partita singola (date due valutazioni, un risultato e un fattore K), elaborazione batch (più record di partita in una richiesta) e stima della valutazione iniziale (data la valutazione media dell'avversario, il punteggio e il conteggio delle partite). Ciascun endpoint restituisce lo stesso output dettagliato mostrato nelle pagine della calcolatrice, inclusi punteggio previsto, delta di valutazione e nuova valutazione prevista. Per dettagli di implementazione e validazione, consulta la metodologia.
Gli endpoint della modalità torneo accettano una serie ordinata di valutazioni e risultati degli avversari, restituendo suddivisioni per round e totali cumulativi. Tutte le risposte includono metadati su quale profilo di regole è stato applicato in modo che i consumatori a valle possano verificare i presupposti di calcolo.
Autenticazione e limiti di velocità
L'accesso API richiede una chiave API passata come token di connessione nell'intestazione Authorization. Le chiavi sono disponibili nei livelli gratuito e premium. Il livello gratuito consente fino a 100 richieste al giorno con un massimo di 10 giochi per richiesta batch. Le chiavi Premium sbloccano un throughput più elevato, supporto prioritario e accesso agli endpoint di elaborazione di tornei in blocco.
I limiti di velocità vengono applicati per chiave, non per indirizzo IP. Il superamento del limite restituisce uno stato 429 con un'intestazione Retry-After che indica quando si apre la finestra di richiesta successiva. Tutti i limiti sono documentati nelle intestazioni di risposta di ogni richiesta andata a buon fine.
Profili delle regole e controllo delle versioni
Ogni risposta API include un campo rule_profile che indica quale insieme di ipotesi è stato utilizzato per il calcolo (ad esempio, fide_2024, us_chess_current, generic_elo). Quando le normative della federazione cambiano, l'API aggiunge una nuova versione del profilo anziché modificare quelle esistenti. Ciò significa che i sistemi downstream possono collegarsi a una versione del profilo specifica ed eseguire l'aggiornamento secondo la propria pianificazione.
Le modifiche importanti vengono comunicate con almeno 30 giorni di anticipo tramite il registro delle modifiche API e la mailing list degli sviluppatori. Le aggiunte continue (nuovi campi opzionali, nuovi profili) vengono implementate continuamente senza interrompere le integrazioni esistenti.
Formato della risposta e gestione degli errori
- Tutte le risposte restituiscono JSON con Content-Type: application/json. I calcoli riusciti restituiscono 200 con il carico utile del risultato completo.
- Gli errori di convalida (campi mancanti, valutazioni fuori intervallo, fattore K non valido) restituiscono 422 con un array di errori leggibile dall'uomo.
- Gli errori di autenticazione restituiscono 401. Le chiavi scadute o revocate restituiscono 403 con un URL di riattivazione.
- Gli errori del server restituiscono 500 con un ID richiesta per l'escalation del supporto. Tutte le risposte agli errori seguono la stessa struttura {errore, messaggio, richiesta_id}.
Migliori pratiche di integrazione
Memorizza nella cache i calcoli ripetuti localmente quando possibile per ridurre al minimo le chiamate API. Per i flussi di lavoro dei tornei, utilizza l'endpoint batch anziché effettuare richieste sequenziali per partita singola. Includi sempre il parametro rule_profile in modo esplicito anziché fare affidamento sull'impostazione predefinita del server, in modo che l'integrazione rimanga deterministica anche quando l'API aggiunge nuovi profili.
Per il software del club e i dashboard di coaching, prendi in considerazione l'archiviazione sia dei risultati calcolati che della versione rule_profile in modo da poter controllare o ricalcolare in seguito se le regole della federazione cambiano. Ciò è particolarmente importante per i flussi di lavoro di reporting ufficiale in cui l'accuratezza storica è importante.