リクエスト/レスポンス仕様
APIリクエストとレスポンスの形式について解説します。
HTTPメソッド
すべてのエンドポイントは POST メソッドを使用します。
POST https://dev.api.bigtime.world/v1/{endpoint}?api_key=API_KEYリクエストヘッダー
| ヘッダー名 | 必須 | 値 | 説明 |
|---|---|---|---|
| Content-Type | 必須 | application/json | リクエストボディの形式 |
| x-user-key | 必須 | YOUR_AUTH_KEY | 認証キー (x-user-key) — ダッシュボードで取得 |
リクエストパラメータ
リクエストボディはJSON形式で送信します。エンドポイントの種類によって使用するパラメータが異なります。
今週データ（t_*）
| パラメータ | 型 | 形式 | 説明 |
|---|---|---|---|
| racedate | string | YYYYMMDD | 開催日（例: "20251129"） |
| racekey | string | 8桁 | レースキー（例: "05250101"） |
※ racedate または racekey のいずれかを指定します。
過去データ（d_*）— /dse・/dra・/dky・/dzk・/dpd
| パラメータ | 型 | 形式 | 説明 |
|---|---|---|---|
| start_racedate | string | YYYYMMDD | 期間開始日（例: "20251101"） |
| end_racedate | string | YYYYMMDD | 期間終了日（例: "20251130"） |
| racekey | string | 8桁 | レースキー（例: "05250101"） |
| limit | integer | 1〜50000 | 最大取得件数（省略時 10000、上限 50000） |
- ※
start_racedate（+ 任意でend_racedate）またはracekeyのいずれかを指定します。end_racedateを省略すると、データベース上の最新日付までが対象になります。 - ※ 期間指定は 365日 までです。これを超えると 400 エラーになります。
- ※ 1リクエストの返却件数は
limitで制御します（既定 10000 / 最大 50000）。長期間を取る場合は年単位などに分割してください。
マスタデータ（m_*）
| エンドポイント | パラメータ | 形式 | 説明 |
|---|---|---|---|
| /muk | horse_id | 12桁 | 馬ID（例: "2328aaa95a05"） |
| /mjk | jockey_cd | 5桁 | 騎手コード（例: "01234"） |
| /mtn | trainer_cd | 5桁 | 調教師コード（例: "01234"） |
キー形式の詳細
レースキー（racekey）
8桁の数字で、レースを一意に識別します。
05250101
競馬場
(01-10)
(01-10)
年
(西暦下2桁)
(西暦下2桁)
回/日
(第N回M日)
(第N回M日)
レース番号
(01-12)
(01-12)
例: 05250101 = 東京競馬場（05）、2025年、第1回1日目、1R
競馬場コード
01: 札幌
02: 函館
03: 福島
04: 新潟
05: 東京
06: 中山
07: 中京
08: 京都
09: 阪神
10: 小倉
競走成績キー（resultkey）
16桁の数字で、馬の各レース出走を一意に識別します。
1910181420240210
競走馬ID（8桁）
開催日（8桁・YYYYMMDD）
例: 1910181420240210 = 競走馬ID「19101814」の2024年2月10日のレース
レスポンス形式
すべてのエンドポイントは統一されたJSON形式でレスポンスを返します。
成功レスポンス
{
"request": {
"racedate": "20251129"
},
"result": {
"status": "success",
"data": [
{
"racekey": "05250101",
"race_name": "3歳未勝利",
"distance": "1600",
// ... 他のフィールド
},
// ... 他のレコード
]
}
}レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
| request | object | 送信されたリクエストパラメータ |
| result.status | string | "success" または "error" |
| result.data | array | 取得したレコードの配列 |
エラーレスポンス
{
"error": {
"code": "INVALID_PARAMETER",
"message": "racedate または racekey を指定してください"
}
}データ型について
nullable フィールド
多くの数値フィールドは null になる可能性があります。 データが存在しない場合（例: 未発表のオッズ、未計測の調教タイム）は null が返されます。
日付・時刻
日付は YYYYMMDD 形式の文字列、 時刻は HHMM 形式の文字列で返されます。
コード値
天候、馬場状態、脚質などのコード値は文字列で返されます。 各コードの意味は各エンドポイントのドキュメントを参照してください。
リクエスト例
日付指定で取得
curl -X POST "https://dev.api.bigtime.world/v1/tra?api_key=API_KEY" \
-H "Content-Type: application/json" \
-H "x-user-key: YOUR_AUTH_KEY" \
-d '{"racedate": "20251129"}'レースキー指定で取得
curl -X POST "https://dev.api.bigtime.world/v1/tky?api_key=API_KEY" \
-H "Content-Type: application/json" \
-H "x-user-key: YOUR_AUTH_KEY" \
-d '{"racekey": "05250101"}'期間指定で取得（過去データ）
curl -X POST "https://dev.api.bigtime.world/v1/dse?api_key=API_KEY" \
-H "Content-Type: application/json" \
-H "x-user-key: YOUR_AUTH_KEY" \
-d '{"start_racedate": "20251101", "end_racedate": "20251130"}'注意事項
- •過去データの期間指定は最大1ヶ月までを推奨します。大量データの取得はレスポンスが遅くなる可能性があります。
- •今週データは木曜日の情報更新後から取得可能になります。
- •直前情報（/tpd）はレース当日の朝以降に更新されます。
- •レート制限があります。短時間での大量リクエストは避けてください。