Developer API
Chess Rating API Documentation
The Chess Rating API provides programmatic access to the same Elo calculation engine that powers the calculators on this site. Developers building club management tools, tournament reporting dashboards, coaching platforms, or editorial products can integrate rating calculations directly into their workflows without reimplementing the formula logic. This documentation covers available endpoints, request and response formats, authentication requirements, and the versioning approach that keeps integrations stable. You can continue with Widget documentation for closely related guidance.
Available Calculation Endpoints
The API supports three primary calculation workflows: single-game rating change (given two ratings, a result, and a K-factor), batch processing (multiple game records in one request), and initial rating estimation (given average opponent rating, score, and game count). Each endpoint returns the same detailed output shown on the calculator pages, including expected score, rating delta, and projected new rating. For implementation details and validation notes, review Methodology and validation.
Tournament-mode endpoints accept an ordered array of opponent ratings and results, returning per-round breakdowns and cumulative totals. All responses include metadata about which rules profile was applied so downstream consumers can verify the calculation assumptions.
Authentication and Rate Limits
API access requires an API key passed as a bearer token in the Authorization header. Keys are available in free and premium tiers. The free tier allows up to 100 requests per day with a maximum of 10 games per batch request. Premium keys unlock higher throughput, priority support, and access to bulk tournament processing endpoints.
Rate limits are enforced per key, not per IP address. Exceeding the limit returns a 429 status with a Retry-After header indicating when the next request window opens. All limits are documented in the response headers of every successful request.
Rules Profiles and Versioning
Every API response includes a rules_profile field indicating which set of assumptions was used for the calculation (e.g., fide_2024, us_chess_current, generic_elo). When federation regulations change, the API adds a new profile version rather than modifying existing ones. This means downstream systems can pin to a specific profile version and upgrade on their own schedule.
Breaking changes are communicated at least 30 days in advance through the API changelog and developer mailing list. Non-breaking additions (new optional fields, new profiles) are deployed continuously without disrupting existing integrations.
Response Format and Error Handling
- All responses return JSON with Content-Type: application/json. Successful calculations return 200 with the full result payload.
- Validation errors (missing fields, out-of-range ratings, invalid K-factor) return 422 with a human-readable error array.
- Authentication failures return 401. Expired or revoked keys return 403 with a reactivation URL.
- Server errors return 500 with a request ID for support escalation. All error responses follow the same { error, message, request_id } structure.
Integration Best Practices
Cache repeated calculations locally whenever possible to minimize API calls. For tournament workflows, use the batch endpoint rather than making sequential single-game requests. Always include the rules_profile parameter explicitly rather than relying on the server default, so your integration remains deterministic even when the API adds new profiles.
For club software and coaching dashboards, consider storing both the calculated results and the rules_profile version so you can audit or recalculate later if federation rules change. This is especially important for official reporting workflows where historical accuracy matters.