API för utvecklare

Schack Rating API dokumentation

Chess Rating API ger programmatisk åtkomst till samma Elo-beräkningsmotor som driver räknarna på den här webbplatsen. Utvecklare som bygger klubbledningsverktyg, instrumentpaneler för turneringsrapportering, coachningsplattformar eller redaktionella produkter kan integrera betygsberäkningar direkt i sina arbetsflöden utan att omimplementera formellogiken. Den här dokumentationen täcker tillgängliga slutpunkter, förfrågnings- och svarsformat, autentiseringskrav och versionsmetoden som håller integrationer stabila. Du kan fortsätta med Inbäddningsbara widgets för schackbetyg för närliggande vägledning.

Tillgängliga beräkningsslutpunkter

API:et stöder tre primära beräkningsarbetsflöden: ändring av betyg i ett spel (med två betyg, ett resultat och en K-faktor), batchbearbetning (flera spelrekord i en begäran) och initial uppskattning av betyg (givet genomsnittligt motståndarbetyg, poäng och antal spel). Varje slutpunkt returnerar samma detaljerade utdata som visas på räknarens sidor, inklusive förväntat resultat, betygsdelta och projicerad ny rating. För implementerings- och valideringsdetaljer, granska metodiken.

Slutpunkter i turneringsläge accepterar en ordnad uppsättning motståndarbetyg och resultat, returnerande uppdelningar per runda och kumulativa totaler. Alla svar inkluderar metadata om vilken regelprofil som tillämpades så att nedströmskonsumenter kan verifiera beräkningsantagandena.

Autentisering och hastighetsgränser

API-åtkomst kräver en API-nyckel som skickas som bärartoken i auktoriseringshuvudet. Nycklar finns i gratis- och premiumnivåer. Den kostnadsfria nivån tillåter upp till 100 förfrågningar per dag med maximalt 10 spel per batchförfrågan. Premiumnycklar låser upp högre genomströmning, prioriterat stöd och tillgång till slutpunkter för bulkturneringsbearbetning.

Prisgränser tillämpas per nyckel, inte per IP-adress. Överskridande av gränsen returnerar en 429-status med en Försök-efter-rubrik som anger när nästa förfrågningsfönster öppnas. Alla gränser dokumenteras i svarsrubriker för varje lyckad begäran.

Regler Profiler och versionering

Varje API-svar inkluderar ett rule_profile-fält som anger vilken uppsättning antaganden som användes för beräkningen (t.ex. fide_2024, us_chess_current, generic_elo). När federationsbestämmelser ändras lägger API:et till en ny profilversion istället för att ändra befintliga. Detta innebär att nedströmssystem kan fästa till en specifik profilversion och uppgradera enligt sitt eget schema.

Brytande ändringar meddelas minst 30 dagar i förväg via API-ändringsloggen och utvecklarens e-postlista. Icke-avbrytande tillägg (nya valfria fält, nya profiler) distribueras kontinuerligt utan att avbryta befintliga integrationer.

Svarsformat och felhantering

Alla svar returnerar JSON med Content-Type: application/json. Framgångsrika beräkningar returnerar 200 med full nyttolast.
Valideringsfel (saknade fält, värderingar utanför intervallet, ogiltig K-faktor) returnerar 422 med en läsbar felmatris.
Autentiseringsfel returnerar 401. Utgångna eller återkallade nycklar returnerar 403 med en återaktiverings-URL.
Serverfel returnerar 500 med ett begäran-ID för supporteskalering. Alla felsvar följer samma struktur för { error, message, request_id }.

Bästa metoder för integration

Cachelagra upprepade beräkningar lokalt när det är möjligt för att minimera API-anrop. För turneringsarbetsflöden, använd batchslutpunkten istället för att göra sekventiella enspelsförfrågningar. Inkludera alltid parametern rules_profile uttryckligen i stället för att förlita sig på serverns standard, så att din integration förblir deterministisk även när API:et lägger till nya profiler.

För klubbprogramvara och tränarinstrumentpaneler, överväg att lagra både de beräknade resultaten och versionen av reglerprofilen så att du kan granska eller räkna om senare om förbundsreglerna ändras. Detta är särskilt viktigt för officiella rapporteringsarbetsflöden där historisk noggrannhet är viktig.