🚧 Beta version - The site is under active development. I am aware of many bugs and fix them daily. Any feedback is welcome - data, functionality, UI, security, or anything else. · feedback welcome Contact

Technical documentation is in English.

Developer guide

Reference language: English. Updated 2026-10-01.

Choose an interface

Interface Purpose Documentation
Statistics API v1 Public results, people, clubs, ratings, statistics and authorized account features Swagger, OpenAPI JSON
Source-aware API v2 Event collections, source provenance and competition participants; complements v1 Swagger, OpenAPI JSON
Club Studio Club website widgets and JSON publishing, included in Club Lite and Club Guide
Personal Showcase Verified dancer/couple results on a personal website, included in Pro Guide
Simple club results embed Existing basic public results iframe; limited customization Use /embed/club/CLUB_ID/results for a known public club ID
Booking API Tenant-specific lessons, availability, members and finance Open /api/v1/booking/docs on your club's subdomain, with its separate Booking credentials

Official federation ranklist snapshots, routine editing, watch management and family management have no dedicated public v1 API. /rankings describes our computed rankings, not an official federation register. Website features do not automatically have a public API. Unversioned website endpoints are internal interfaces and carry no integration compatibility promise.

First request

Public reads need no token. Replace https://YOUR_SITE_DOMAIN with the public site origin. General APIs are designed for server-side clients; unrestricted cross-origin browser access is not enabled. Use the Studio interfaces for supported cross-origin website publishing.

curl --fail-with-body https://YOUR_SITE_DOMAIN/api/v1/federations
{"success":true,"data":{"items":[],"count":0},"meta":{"request_id":"req_example","api_version":"v1","server_time":"2026-10-01T00:00:00Z"}}

The empty list above illustrates the envelope, not current coverage. Consult the operation's schema for the complete data object. V1 errors have success:false, error text, error_code, optional details and meta. V2 errors instead have error:{code,message}. Studio feeds use their own documented ok envelope. Do not parse all products as one response shape.

import os
import requests

origin = os.environ["DANCESTATS_ORIGIN"]
response = requests.get(origin + "/api/v1/federations", timeout=20)
response.raise_for_status()
payload = response.json()
if payload.get("success") is not True:
    raise RuntimeError(payload.get("error", "API request failed"))
data = payload["data"]
// Run on your server or same origin, not an arbitrary third-party browser origin.
const response = await fetch(`${origin}/api/v1/federations`, {
  signal: AbortSignal.timeout(20000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const payload = await response.json();
if (!payload.success) throw new Error(payload.error);
const data = payload.data;

Authentication and privacy

Request a scoped token through Contact, explaining your application, endpoints, expected traffic, refresh interval and reuse purpose. Issuance is currently administered by staff. Send Authorization: Bearer ds_live_... from your server, never a URL, public repository, browser bundle or AI prompt. Tokens are shown once and can expire or be revoked. Rotate a leaked token.

  • read:public: public resources; does not increase quota.
  • read:user_data: authorized account resources and analytics. Ownership, delegation, privacy and subscription checks still apply to each subject.
  • write:user_data: explicitly authorized account mutations.
  • read:admin / write:admin: staff operations, not commercial data access.

Payment never grants access to another person's private analytics. Browser sessions are a separate authentication path; mutating session requests require X-CSRFToken and a permitted write scope. A Bearer caller can inspect or revoke its own token through /me/tokens, never the account's other tokens.

Pagination, filters and values

Use each operation's declared parameters. Paginated list routes generally accept page and per_page, with a maximum per_page of 200; consult its schema because not every route is paginated. Preserve filter and ordering parameters when advancing a page. Do not invent an expand option for an endpoint that does not declare it.

Dates use ISO YYYY-MM-DD; timestamps carry UTC/offset information. A missing optional field and an explicit null are different. Do not infer zero from either. Country codes describe the field's named context: nationality, competition location and represented country are not interchangeable. Federation slugs are identifiers; discover supported values through /federations. Native classes belong to a federation and effective track; letters from different federations are not automatically equal.

Evidence, freshness and citations

An upcoming competition has no final result merely because it has a date. Preserve lifecycle, provisional/final and provenance information. Published class observations differ from computed progression; inferred club membership differs from an explicitly printed affiliation. Elo ratings and predictions are our computations, not official federation results. Source coverage and refresh cadence vary; absence of a record is not proof that it never existed.

Use the returned canonical page URLs for human citations. Preserve the original publisher where provenance supplies it. Store the complete observation_url for a snapshot citation; a mutable local numeric ID is insufficient. V2 provenance supplements v1; its collections and source identities are distinct from governing-body federation identifiers.

On 301, follow the canonical replacement and update your pointer. 410 means a known resource or observation was superseded, retracted or removed; respect its lifecycle details and avoid presenting it as current. 404 means the requested identity was not found. Report suspected errors through Feedback, with the resource URL and X-Request-ID.

Quotas and caching

Production route defaults: ordinary reads 200/minute, moderate computation or mutation routes 30/minute, standard Studio routes 60/minute. Values are configurable. A separate shared attempt ceiling applies across /api/* and paid Studio embeds on one serving application, per resolved client IP: the default tier's 200/minute. Registered legacy Booking API paths share this ceiling on their own serving application. It includes failed requests and cannot be multiplied by switching endpoints. Route-specific lower limits remain in force. Native Booking write quotas additionally share an IP/tier bucket across tenants. Explicit operational health/webhook exemptions remain in place.

There is no independent guaranteed requests-per-second allowance. Spread calls over the minute, start with one concurrent request, and centralize polling in your backend. Authenticated tokens and paid personal plans do not increase the general quota. Anonymous predictor model work has a shared three-per-day limit across both prediction entry points; signing in removes that daily cap, but minute and attempt ceilings remain. Cached model results do not spend a new compute allowance.

Quota headers are present when enforcement is enabled. Development mode deliberately disables enforcement and omits those headers.

X-RateLimit-Limit and X-RateLimit-Remaining describe the selected limiting bucket; X-RateLimit-Reset is its Unix reset timestamp. Retry-After is a delay in seconds. On 429, wait at least that delay plus a small random jitter. On transient 502/503, retry with bounded exponential backoff; do not automatically retry writes without their documented idempotency contract. Retain X-Request-ID for support. A 429 is never cacheable.

Honor Cache-Control, save ETag, then send If-None-Match. A 304 has no JSON body: reuse your cached representation. Conditional requests still consume request quota. Store private responses only within their authorized account. Never share private caches. Studio JSON advertises X-DanceStats-Poll-Interval: 120; poll no faster than once per two minutes.

Shared Redis normally keeps quotas consistent across workers. During a Redis outage a bounded process-local fallback protects availability; fleet totals can then exceed the normal shared allowance. This is an operational degradation, not extra client permission. Direct origins must be restricted to trusted proxies; do not spoof forwarding headers or rotate identities to evade limits.

Versioning and commercial access

V1 is a stable contract. Use the schema on the deployment you call. Preserve unknown additive fields, heed Deprecation/Sunset, and review specifications when upgrading. V2 is a complementary contract with its own error schema.

Read usage and attribution and AI guidance. For existing paid widgets, see pricing. Larger integrations are currently inquiry-only: send intended endpoints, monthly volume, peak rate, concurrency, caching, commercial display/bulk requirements and support needs through Contact. A quote does not enable a higher quota until a specific agreement and enforced allowance are provisioned. No unlimited API access or transferable rights to upstream publications are sold by a personal lifetime plan.

0.0