규칙: 엔벨로프, 카테고리, 페이징, 오류

이 규칙을 한 번만 익히면 모든 엔드포인트가 예상대로 동작합니다.

응답 엔벨로프

성공 응답은 모두 두 개의 키를 가진 JSON 객체입니다.

키	내용
data	객체(단일 리소스) 또는 배열(목록)
meta	total, page, size, total_pages — 페이징되지 않는 엔드포인트에서는 페이징 필드가 null입니다

{
  "data": { "year": 2026, "status": "ACTIVE" },
  "meta": { "total": 1, "page": null, "size": null, "total_pages": null }
}

필드 이름은 전체에서 snake_case를 사용합니다(rider_number, total_points, season_year).

카테고리: MotoGP, Moto2, Moto3

시즌 단위 엔드포인트는 MOTOGP, MOTO2, MOTO3 중 하나를 값으로 하는 category 쿼리 매개변수를 받습니다. class는 같은 값을 갖는 별칭이므로, 둘 중 하나만 보내세요.

GET /standings/seasons/2026/riders?category=MOTO2
GET /races/seasons/2026?category=MOTO3

결과가 기본값에 좌우되지 않도록 category를 명시적으로 전달하세요.

페이징

“전체 조회” 엔드포인트인 /riders, /teams, /races, /standings는 page(1부터 시작)와 size(1–200, 기본값 20)로 페이징됩니다.

GET /riders?page=2&size=50

"meta": { "total": 118, "page": 2, "size": 50, "total_pages": 3 }

page가 total_pages에 도달할 때까지 반복하세요.

async function getAll(path) {
  const rows = [];
  for (let page = 1; ; page++) {
    const { data, meta } = await getEnvelope(`${path}?page=${page}&size=200`);
    rows.push(...data);
    if (!meta.total_pages || page >= meta.total_pages) return rows;
  }
}

/riders/seasons/{year}처럼 시즌 단위 목록은 한 번의 응답으로 시즌 전체를 반환합니다.

정렬

순위표는 position 순으로 반환됩니다. 캘린더와 레이스 결과는 정렬이 보장되지 않으므로 직접 정렬하세요.

races.sort((a, b) => a.round_number - b.round_number);
results.sort((a, b) => a.position - b.position);

식별자

리소스	조회 방법
라이더	레이스 넘버: /riders/{rider_number} (예: 93)
팀	팀 목록에서 얻은 불투명 ID: /teams/{id}, 또는 이름: /teams/name/{name}
레이스	시즌 + 라운드: /races/seasons/{year}/round/{round}, 또는 불투명 ID: /races/{race_id}/results
시즌	연도: /seasons/{year}

불투명 ID("82MQRdM5q7ub4OSm6Jhx")는 하드코딩하지 말고 목록 응답에서 가져오세요. 스폰서 이름은 시즌마다 바뀌므로 팀은 이름이 아니라 ID로 매칭하세요.

순위표 유형

전용 경로(/riders, /teams, /manufacturers, /bmw-m) 외에도 유형을 지정해 순위표를 요청할 수 있습니다.

GET /standings/seasons/2026/type/MANUFACTURER?category=MOTOGP

유형은 RIDER, TEAM, MANUFACTURER, BMW_M입니다.

오류

오류는 표준 HTTP 상태 코드와 JSON 본문으로 반환됩니다.

{
  "timestamp": "2026-01-27T19:18:29",
  "status": 404,
  "error": "Not Found",
  "message": "Rider not found with number: 99",
  "path": "/riders/99"
}

상태	의미	대응 방법
400	잘못된 매개변수(잘못된 연도, 알 수 없는 카테고리)	요청을 수정하세요. 있는 경우 validation_errors에 문제 목록이 담깁니다
401 / 403	RapidAPI 키가 없거나 유효하지 않거나, 구독이 없음	두 헤더와 플랜을 확인하세요
404	라이더, 팀, 레이스 또는 시즌이 존재하지 않음	”찾을 수 없음” 상태를 표시하세요
429	플랜의 요청 제한 또는 할당량 도달	잠시 후 다시 시도하거나 플랜을 업그레이드하세요
5xx	일시적인 서버 문제	지수 백오프로 재시도하고 상태 페이지를 확인하세요

캐싱

결과와 순위는 레이스 주말마다 바뀌고, 프로필은 시즌 사이에 바뀝니다. 할당량을 아끼고 페이지를 빠르게 유지하려면 적극적으로 캐싱하세요.

데이터	권장 캐시 시간
시즌, 라이더, 팀, 커리어 통계	24시간
캘린더	12시간
결과와 순위	레이스 주말에는 1시간, 그 외에는 12시간

키는 서버에 보관하세요

RapidAPI 키는 과금에 사용되는 자격 증명입니다. API는 백엔드, 서버리스 함수 또는 빌드 단계에서 호출하세요. 키가 사용자에게 그대로 배포되는 브라우저나 모바일 코드에서는 절대 호출하지 마세요. 순위표 가이드에서 캐싱이 포함된 작은 프록시 예제를 볼 수 있습니다.