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.