{ "openapi": "3.1.0", "info": { "title": "Cycling API", "version": "1.0.0", "description": "Cycling results, riders, jersey leaders and the race calendar since 1869." }, "servers": [ { "url": "https://api.cyclingapi.com" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "paths": { "/v1/today/races": { "get": { "operationId": "races_today", "summary": "Every sanctioned competition running today", "tags": [ "Free key and up" ], "parameters": [ { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "discipline": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "country": { "type": "string" }, "venue": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/today/results": { "get": { "operationId": "results_today", "summary": "Results posted today, as they land", "tags": [ "Free key and up" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/today/jerseys": { "get": { "operationId": "jerseys_today", "summary": "Who leads each jersey in the stage races running today", "tags": [ "Free key and up" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "race": { "type": "object" }, "after_stage": { "type": "integer" }, "jersey": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "value": { "type": "string" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/yesterday/races": { "get": { "operationId": "races_yesterday", "summary": "Every sanctioned competition that ran yesterday", "tags": [ "Free key and up" ], "parameters": [ { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "discipline": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "country": { "type": "string" }, "venue": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/yesterday": { "get": { "operationId": "results_yesterday", "summary": "Latest results of every race run yesterday", "tags": [ "Free key and up" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "rank": { "type": "integer" }, "stage": { "type": "integer" }, "classification": { "type": "string" }, "rider": { "type": "object" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/usage": { "get": { "operationId": "usage", "summary": "Your plan, calls used and limits (never counted)", "tags": [ "Free key and up" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "string" }, "calls_today": { "type": "integer" }, "calls_this_month": { "type": "integer" }, "limits": { "type": "object" }, "window": { "type": "object" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/coverage": { "get": { "operationId": "coverage", "summary": "How much the archive holds, by discipline", "tags": [ "Free key and up" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "result_rows": { "type": "integer" }, "competitions": { "type": "integer" }, "countries": { "type": "integer" }, "first_season": { "type": "integer" }, "disciplines": { "type": "array", "items": {} } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/coverage/decades": { "get": { "operationId": "coverage_decades", "summary": "Editions and result rows held for each decade", "tags": [ "Free key and up" ], "parameters": [ { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "discipline": { "type": "string" }, "decade": { "type": "integer" }, "editions": { "type": "integer" }, "result_rows": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/coverage/seasons": { "get": { "operationId": "coverage_seasons", "summary": "Editions and result rows held for each season, by discipline, gender, class and region", "tags": [ "Free key and up" ], "parameters": [ { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "year", "in": "query", "required": false, "description": "One season", "schema": { "type": "integer" } }, { "name": "gender", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "men", "women" ] } }, { "name": "category", "in": "query", "required": false, "description": "Class, such as elite, u23 or junior", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Where the races were held, such as Europe or South America", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "discipline": { "type": "string" }, "year": { "type": "integer" }, "gender": { "type": "string" }, "category": { "type": "string" }, "region": { "type": "string" }, "editions": { "type": "integer" }, "result_rows": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/coverage/races": { "get": { "operationId": "coverage_races", "summary": "Which seasons of a race we hold, and how deep", "tags": [ "Free key and up" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Part of the race name (three letters or more)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "first_year": { "type": "integer" }, "last_year": { "type": "integer" }, "editions": { "type": "integer" }, "result_rows": { "type": "integer" }, "editions_with_stages": { "type": "integer" }, "editions_with_jerseys": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/calendar": { "get": { "operationId": "calendar", "summary": "Sanctioned competitions between two dates", "tags": [ "Paid plans" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day (defaults to today)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last day (defaults to 30 days after from)", "schema": { "type": "string", "format": "date" } }, { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "country", "in": "query", "required": false, "description": "Three-letter country code", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "discipline": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "country": { "type": "string" }, "continent": { "type": "string" }, "venue": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/calendar/upcoming": { "get": { "operationId": "calendar_upcoming", "summary": "Competitions starting in the next days", "tags": [ "Paid plans" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days ahead (default 30, at most 120)", "schema": { "type": "integer" } }, { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "country", "in": "query", "required": false, "description": "Three-letter country code", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "discipline": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "country": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/calendar/countries": { "get": { "operationId": "calendar_countries", "summary": "Competitions hosted by each country in a season", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "country": { "type": "string" }, "competitions": { "type": "integer" }, "first_date": { "type": "string", "format": "date" }, "last_date": { "type": "string", "format": "date" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races": { "get": { "operationId": "races", "summary": "Race editions in a season, with dates, place and discipline", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } }, { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "gender", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "men", "women" ] } }, { "name": "category", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "elite", "u23", "junior", "amateur" ] } }, { "name": "q", "in": "query", "required": false, "description": "Part of the race name", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "year": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "country": { "type": "string" }, "discipline": { "type": "string" }, "gender": { "type": "string" }, "category": { "type": "string" }, "stages": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}": { "get": { "operationId": "race", "summary": "One race edition: dates, stages and the agreed podium", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Season (defaults to the latest held)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "year": { "type": "integer" }, "stages": { "type": "array", "items": {} }, "podium": { "type": "array", "items": {} }, "seasons": { "type": "array", "items": {} } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/history": { "get": { "operationId": "race_history", "summary": "Every edition of a race with dates and podium", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "stages": { "type": "integer" }, "podium": { "type": "array", "items": {} } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/stages": { "get": { "operationId": "race_stages", "summary": "Each stage: date, start and finish, distance, type and altitude", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "finish": { "type": "string" }, "distance_km": { "type": "number" }, "start_place": { "type": "object" }, "finish_place": { "type": "object" }, "height_gain_m": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/podium": { "get": { "operationId": "race_podium", "summary": "The agreed top three, with how many records agree", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "place": { "type": "integer" }, "rider": { "type": "string" }, "records_agreeing": { "type": "integer" }, "records_holding": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/winners": { "get": { "operationId": "race_winners", "summary": "Every winner of a race, most wins first", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rider": { "type": "object" }, "wins": { "type": "integer" }, "years": { "type": "array", "items": {} } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results": { "get": { "operationId": "results", "summary": "Results of a race edition, by stage and classification", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": false, "description": "A stage number, prologue or final (all when left out)", "schema": { "type": "string" } }, { "name": "classification", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "general", "stage", "points", "mountains", "youth", "team", "combative", "other" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" }, "stage_type": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/stage": { "get": { "operationId": "results_stage", "summary": "The finish order of one stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": true, "description": "A stage number or prologue", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/general": { "get": { "operationId": "results_general", "summary": "Overall standings: final, or after a given stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": false, "description": "Standings after this stage (final when left out)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/points": { "get": { "operationId": "results_points", "summary": "Points standings: final, or after a given stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": false, "description": "Standings after this stage", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/mountains": { "get": { "operationId": "results_mountains", "summary": "Climbers standings: final, or after a given stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": false, "description": "Standings after this stage", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/youth": { "get": { "operationId": "results_youth", "summary": "Best young rider standings: final, or after a given stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": false, "description": "Standings after this stage", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/teams": { "get": { "operationId": "results_teams", "summary": "Team standings: final, or after a given stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": false, "description": "Standings after this stage", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "rank_status": { "type": "string" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "time_s": { "type": "number" }, "gap_s": { "type": "number" }, "points": { "type": "integer" }, "ranking_points": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/non-finishers": { "get": { "operationId": "non_finishers", "summary": "Who left the race, on which stage and how", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "status": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/classifications": { "get": { "operationId": "classifications", "summary": "Jersey leaders after each stage of a race edition", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "jersey", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "leader", "points", "mountains", "youth" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "after_stage": { "type": "integer" }, "jersey": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "value": { "type": "string" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/jerseys/winners": { "get": { "operationId": "jersey_winners", "summary": "Who took each jersey home in every stage race of a season", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "race": { "type": "object" }, "jersey": { "type": "string" }, "rider": { "type": "object" }, "team": { "type": "string" }, "value": { "type": "string" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders": { "get": { "operationId": "riders", "summary": "Find riders by name or nation", "tags": [ "Paid plans" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Part of the rider name (two letters or more)", "schema": { "type": "string" } }, { "name": "nation", "in": "query", "required": false, "description": "Three-letter nation code", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nation": { "type": "string" }, "sex": { "type": "string" }, "born": { "type": "string", "format": "date" }, "first_year": { "type": "integer" }, "last_year": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/compare": { "get": { "operationId": "riders_compare", "summary": "Two riders in the same results, and who finished ahead", "tags": [ "Paid plans" ], "parameters": [ { "name": "a", "in": "query", "required": true, "description": "First rider id (rd_...)", "schema": { "type": "string" } }, { "name": "b", "in": "query", "required": true, "description": "Second rider id (rd_...)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "year": { "type": "integer" }, "stage": { "type": "integer" }, "stage_kind": { "type": "string" }, "classification": { "type": "string" }, "rank_a": { "type": "integer" }, "rank_b": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}": { "get": { "operationId": "rider", "summary": "One rider: profile, career span, wins and podiums", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nation": { "type": "string" }, "born": { "type": "string", "format": "date" }, "birth_place": { "type": "string" }, "height_cm": { "type": "number" }, "weight_kg": { "type": "number" }, "starts": { "type": "integer" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/results": { "get": { "operationId": "rider_results", "summary": "Every result of one rider, newest first", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "year": { "type": "integer" }, "rank": { "type": "integer" }, "stage": { "type": "integer" }, "classification": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/wins": { "get": { "operationId": "rider_wins", "summary": "Every stage, classification and race one rider won", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "year": { "type": "integer" }, "stage": { "type": "integer" }, "classification": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/seasons": { "get": { "operationId": "rider_seasons", "summary": "One line per season: race days, wins, podiums, top 10s and teams", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "year": { "type": "integer" }, "race_days": { "type": "integer" }, "races": { "type": "integer" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" }, "top_10": { "type": "integer" }, "teams": { "type": "array", "items": {} } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/teams": { "get": { "operationId": "rider_teams", "summary": "The teams a rider raced for, season by season", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "year": { "type": "integer" }, "team": { "type": "string" }, "race_days": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/teams": { "get": { "operationId": "teams", "summary": "Registered teams in a season", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } }, { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "country", "in": "query", "required": false, "description": "Three-letter country code", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string" }, "category": { "type": "string" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/teams/{id}": { "get": { "operationId": "team", "summary": "One team: registration, category and its season of racing", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Season", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string" }, "category": { "type": "string" }, "discipline": { "type": "string" }, "year": { "type": "integer" }, "riders": { "type": "array", "items": {} } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/season": { "get": { "operationId": "stats_season", "summary": "A season at a glance: editions, stages, kilometres, winners, speed and abandons", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "year": { "type": "integer" }, "editions": { "type": "integer" }, "stages": { "type": "integer" }, "distance_km": { "type": "integer" }, "different_winners": { "type": "integer" }, "winning_nations": { "type": "integer" }, "winning_teams": { "type": "integer" }, "stage_wins": { "type": "integer" }, "avg_stage_winner_kmh": { "type": "number" }, "abandons": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/leaders": { "get": { "operationId": "stats_leaders", "summary": "Riders ranked by wins, podiums or top 10s in a season", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } }, { "name": "metric", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "wins", "podiums", "top_10" ] } }, { "name": "discipline", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "road", "track", "mtb", "cyclocross", "bmx", "gravel" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "rider": { "type": "object" }, "team": { "type": "string" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" }, "top_10": { "type": "integer" }, "races": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/teams": { "get": { "operationId": "stats_teams", "summary": "Teams ranked by wins and podiums in a season", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "string" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" }, "top_10": { "type": "integer" }, "riders_placing": { "type": "integer" }, "races": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/closest-finishes": { "get": { "operationId": "stats_closest", "summary": "Stage races won by the smallest overall margins", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (every season your plan reads when left out)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "year": { "type": "integer" }, "winner": { "type": "string" }, "second": { "type": "string" }, "margin_s": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/fastest-stages": { "get": { "operationId": "stats_fastest", "summary": "Stages ranked by the winner's average speed", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "stage": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "distance_km": { "type": "number" }, "time_s": { "type": "number" }, "avg_kmh": { "type": "number" }, "stage_type": { "type": "string" }, "winner": { "type": "object" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/stage-types": { "get": { "operationId": "stats_stage_types", "summary": "Flat, hilly, mountain and time trial stages: how many, how long, how fast", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stage_type": { "type": "string" }, "stages": { "type": "integer" }, "avg_distance_km": { "type": "number" }, "avg_winner_kmh": { "type": "number" }, "different_winners": { "type": "integer" }, "top_nation": { "type": "string" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stats/winner-ages": { "get": { "operationId": "stats_youngest", "summary": "Every win of a season by the winner's age on the day", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } }, { "name": "order", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "youngest", "oldest" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "number" }, "rider": { "type": "object" }, "race": { "type": "object" }, "stage": { "type": "integer" }, "win": { "type": "string" }, "date": { "type": "string", "format": "date" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/records": { "get": { "operationId": "race_records", "summary": "Most wins, top nations, youngest and oldest winner, fastest edition, closest margin", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "race": { "type": "object" }, "editions": { "type": "integer" }, "most_wins": { "type": "array", "items": {} }, "top_nations": { "type": "array", "items": {} }, "youngest_winner": { "type": "object" }, "oldest_winner": { "type": "object" }, "fastest_edition_kmh": { "type": "object" }, "closest_margin_s": { "type": "object" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/margins": { "get": { "operationId": "race_margins", "summary": "The gap from winner to second in every edition", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "winner": { "type": "object" }, "second": { "type": "string" }, "margin_s": { "type": "number" }, "winner_time_s": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/speeds": { "get": { "operationId": "race_speeds", "summary": "Distance, winning time and average speed of every edition", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "distance_km": { "type": "number" }, "winner_time_s": { "type": "number" }, "avg_kmh": { "type": "number" }, "winner": { "type": "object" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/winner-ages": { "get": { "operationId": "race_winner_ages", "summary": "How old every winner of a race was on the day", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "winner": { "type": "object" }, "age": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/attrition": { "get": { "operationId": "race_attrition", "summary": "Starters, finishers and the finish rate of every edition", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "starters": { "type": "integer" }, "finishers": { "type": "integer" }, "non_finishers": { "type": "integer" }, "finish_rate": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/stats": { "get": { "operationId": "rider_stats", "summary": "Win, podium and top 10 rates, average rank and a split by kind of result", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rider": { "type": "object" }, "seasons": { "type": "integer" }, "races": { "type": "integer" }, "race_days": { "type": "integer" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" }, "top_10": { "type": "integer" }, "win_rate": { "type": "number" }, "podium_rate": { "type": "number" }, "top_10_rate": { "type": "number" }, "avg_rank": { "type": "number" }, "best_rank": { "type": "integer" }, "wins_per_season": { "type": "number" }, "by_kind": { "type": "array", "items": {} } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/terrain": { "get": { "operationId": "rider_terrain", "summary": "A rider's results split by stage type: flat, hilly, mountain, time trial", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stage_type": { "type": "string" }, "race_days": { "type": "integer" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" }, "top_10": { "type": "integer" }, "win_rate": { "type": "number" }, "avg_rank": { "type": "number" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/nations/{id}/history": { "get": { "operationId": "nation_history", "summary": "One nation's wins, stage wins and podiums season by season", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "wins": { "type": "integer" }, "stage_wins": { "type": "integer" }, "podiums": { "type": "integer" }, "different_winners": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/weather": { "get": { "operationId": "race_weather", "summary": "The weather at the start and finish of every stage", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stage": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "finish": { "type": "string" }, "distance_km": { "type": "number" }, "start_weather": { "type": "object" }, "finish_weather": { "type": "object" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/weather/stage": { "get": { "operationId": "weather_stage", "summary": "One stage: the weather at both ends and the top 10 who raced in it", "tags": [ "Paid plans" ], "parameters": [ { "name": "race", "in": "query", "required": true, "description": "Race id (rc_...)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Season", "schema": { "type": "integer" } }, { "name": "stage", "in": "query", "required": true, "description": "A stage number or prologue", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "race": { "type": "object" }, "stage": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "finish": { "type": "string" }, "start_weather": { "type": "object" }, "finish_weather": { "type": "object" }, "top_10": { "type": "array", "items": {} } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/weather/extremes": { "get": { "operationId": "weather_extremes", "summary": "The hottest, coldest, wettest, windiest and snowiest stages, with their winners", "tags": [ "Paid plans" ], "parameters": [ { "name": "metric", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "hottest", "coldest", "wettest", "windiest", "snowiest" ] } }, { "name": "year", "in": "query", "required": false, "description": "Season (every season your plan reads when left out)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "year": { "type": "integer" }, "stage": { "type": "integer" }, "finish": { "type": "string" }, "distance_km": { "type": "number" }, "winner": { "type": "object" }, "weather": { "type": "object" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/races/{id}/weather-history": { "get": { "operationId": "weather_history", "summary": "Each edition's heat, rain and wind, side by side", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "stages_with_weather": { "type": "integer" }, "avg_temp_max_c": { "type": "number" }, "hottest_c": { "type": "number" }, "coldest_c": { "type": "number" }, "total_precip_mm": { "type": "number" }, "wet_stages": { "type": "integer" }, "max_gust_kmh": { "type": "number" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/riders/{id}/weather": { "get": { "operationId": "rider_weather", "summary": "A rider's win rate and average rank in rain, heat, cold and wind", "tags": [ "Paid plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conditions": { "type": "string" }, "race_days": { "type": "integer" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" }, "top_10": { "type": "integer" }, "win_rate": { "type": "number" }, "top_10_rate": { "type": "number" }, "avg_rank": { "type": "number" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/weather/specialists": { "get": { "operationId": "weather_specialists", "summary": "Riders with the most stage wins in rain, heat, cold, wind or snow", "tags": [ "Paid plans" ], "parameters": [ { "name": "condition", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "rain", "heat", "cold", "wind", "snow" ] } }, { "name": "year", "in": "query", "required": false, "description": "Season (every season your plan reads when left out)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rider": { "type": "object" }, "stage_wins": { "type": "integer" }, "first_year": { "type": "integer" }, "last_year": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/places": { "get": { "operationId": "places", "summary": "Start and finish towns with coordinates and altitude", "tags": [ "Paid plans" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Part of the town name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "country": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "altitude_m": { "type": "integer" }, "stage_starts": { "type": "integer" }, "stage_finishes": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/stages/summit-finishes": { "get": { "operationId": "summit_finishes", "summary": "Stages that finished high, with the height gained", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (all when left out)", "schema": { "type": "integer" } }, { "name": "min_altitude", "in": "query", "required": false, "description": "Lowest finish altitude in metres (default 1000)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 50, at most 200)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous answer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "race": { "type": "object" }, "stage": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "finish": { "type": "string" }, "distance_km": { "type": "number" }, "finish_altitude_m": { "type": "integer" }, "height_gain_m": { "type": "integer" } } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/nations": { "get": { "operationId": "nations", "summary": "Wins and podiums by nation in a season", "tags": [ "Paid plans" ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Season (defaults to this year)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "nation": { "type": "string" }, "wins": { "type": "integer" }, "podiums": { "type": "integer" } } }, "meta": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "responses": { "Error": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "docs": { "type": "string" } } } } } } } } } } }