REST API · v1

เอกสาร API ข้อมูลกีฬา

เอกสารสำหรับเชื่อมต่อ REST API ของ dooball-api ระบุวิธียืนยันตัวตน พารามิเตอร์ รูปแบบข้อมูล และรหัสข้อผิดพลาดของแต่ละ API

Base URLhttps://ballive-api.yuier-4xy.com/api/v1/sport

ข้อกำหนดทั่วไป
การเชื่อมต่อ	HTTPS
รูปแบบข้อมูล	JSON · UTF-8
การยืนยันตัวตน	`X-API-Key`
HTTP method	`GET` สำหรับเรียกข้อมูล และ `POST` สำหรับสร้าง session สตรีม
สิทธิ์การใช้งาน	ขึ้นอยู่กับแพ็กเกจและบริการที่บัญชีของคุณมีสิทธิ์ใช้งาน

การยืนยันตัวตน

หลังสมัครใช้บริการ dooball-api ให้ใช้ API Key ที่ได้รับยืนยันตัวตนทุกครั้งที่เรียกข้อมูล โดยส่งผ่าน header X-API-Key

Header สำหรับเรียกข้อมูล

X-API-Key: <YOUR_API_KEY>
Accept: application/json

ส่ง header X-API-Key เพียงหนึ่งรายการ ความยาวไม่เกิน 512 ตัวอักษร ไม่รองรับ Bearer token คุกกี้เข้าสู่ระบบ หรือ API Key ใน query parameter ควรเก็บ Key ไว้ฝั่งเซิร์ฟเวอร์ และไม่ใส่ในซอร์สโค้ดสาธารณะ โค้ดที่ส่งให้เบราว์เซอร์ หรือ log

หาก Key ไม่ถูกต้องหรือถูกเพิกถอน ระบบจะตอบ 401 หากสิทธิ์หมดอายุหรือแพ็กเกจไม่ครอบคลุมบริการที่เรียก ระบบจะตอบ 403 ติดต่อทีมดูแลเมื่อต้องการ Key ใหม่หรือปรับสิทธิ์การใช้งาน

เริ่มต้นใช้งาน

ตัวอย่างนี้เรียกรายการแข่งขันฟุตบอล บัญชีของคุณต้องมีสิทธิ์ใช้งานข้อมูลฟุตบอล ก่อนเริ่ม ให้กำหนดตัวแปรสภาพแวดล้อมด้วย API Key ของคุณ

กำหนด API Key

export BALLIVE_API_KEY='<YOUR_API_KEY>'

เรียกรายการแข่งขันฟุตบอล

curl --fail-with-body --silent --show-error \
  --max-time 20 \
  --header "X-API-Key: $BALLIVE_API_KEY" \
  --header "Accept: application/json" \
  'https://ballive-api.yuier-4xy.com/api/v1/sport/football/matches'

cURL ต้องเป็นเวอร์ชัน 7.76 ขึ้นไปเพื่อใช้ --fail-with-body ตัวอย่าง JavaScript ใช้ Node.js 20 ขึ้นไป ส่วน Python ใช้เวอร์ชัน 3.10 ขึ้นไปและติดตั้ง requests ด้วย pip install requests ทุกตัวอย่างอ่าน Key จากตัวแปร BALLIVE_API_KEY

อ่านข้อมูลที่ได้รับ

เมื่อเรียกสำเร็จจะได้รับ HTTP 200 และ success: true รายการแข่งขันอยู่ในอาร์เรย์ responseObject.data หากไม่มีรายการ ระบบอาจส่งอาร์เรย์ว่าง ซึ่งเป็นผลลัพธ์ที่ถูกต้อง

HTTP 200 · ตัวอย่างผลตอบกลับ

{
  "success": true,
  "message": "Sport data retrieved",
  "responseObject": {
    "data": [
      {
        "id": "12345",
        "sport": "football",
        "league": "ลีกตัวอย่าง",
        "homeTeam": {
          "name": "ทีมเหย้า"
        },
        "awayTeam": {
          "name": "ทีมเยือน"
        },
        "status": "live",
        "rawStatus": "2H",
        "isLive": true,
        "score": {
          "home": 2,
          "away": 1,
          "display": "2-1"
        },
        "startsAt": null,
        "displayTime": "20:00",
        "channels": [
          {
            "id": "ch1",
            "name": "ช่องกีฬาตัวอย่าง"
          }
        ],
        "streamResource": {
          "type": "match",
          "id": "12345"
        }
      }
    ],
    "meta": {
      "count": 1,
      "fetchedAt": "2026-10-23T12:00:00.000Z",
      "cache": "miss",
      "isStale": false
    }
  },
  "statusCode": 200
}

ข้อมูลและรหัสในตัวอย่างใช้เพื่ออธิบายรูปแบบ เมื่อต้องการเรียกรายละเอียดหรือเหตุการณ์ ให้แทนรหัสตัวอย่างด้วยรหัสที่ได้รับจาก API รายการข้อมูลที่เกี่ยวข้อง และเก็บรหัสเป็นสตริง

รูปแบบการตอบกลับ

API ข้อมูลทุกเส้นทางใช้โครงสร้างผลตอบกลับชั้นนอกแบบเดียวกัน ส่วนข้อมูลใน responseObject.data จะแตกต่างตามที่ระบุในแต่ละ API ควรตรวจ HTTP status และ success ก่อนนำข้อมูลไปใช้

ฟิลด์หลักของผลตอบกลับ
ฟิลด์	ชนิดข้อมูล	คำอธิบาย
`success`	boolean	true เมื่อสำเร็จ และ false เมื่อเกิดข้อผิดพลาด
`message`	string	ข้อความสรุปผล หรือรหัสข้อผิดพลาด
`responseObject.data`	array / object	ข้อมูลตามรูปแบบที่ระบุในแต่ละ API
`responseObject.meta`	object	จำนวนรายการ เวลาของข้อมูล และข้อมูลแบ่งหน้าเมื่อมี
`statusCode`	integer	รหัส HTTP status ของคำขอ

responseObject.meta
ฟิลด์	คำอธิบาย
`count`	จำนวนรายการในอาร์เรย์ data ของคำขอนี้ ไม่มีฟิลด์นี้เมื่อ data เป็นออบเจ็กต์
`fetchedAt`	เวลาที่ระบบดึงข้อมูล รูปแบบ ISO 8601 (UTC) ไม่ใช่เวลาเริ่มการแข่งขัน
`cache`	hit = ข้อมูลจากแคช, miss = ข้อมูลที่ดึงใหม่, stale = ข้อมูลแคชที่เก่ากว่ารอบอัปเดต
`isStale`	Boolean ระบุว่าข้อมูลเก่ากว่ารอบอัปเดตหรือไม่ หากเป็น true ควรแสดงเวลาที่อัปเดตล่าสุด
`page / pageSize`	เลขหน้าและจำนวนรายการต่อหน้าที่ขอ ใช้กับรายการบทวิเคราะห์
`total`	จำนวนบทวิเคราะห์ทั้งหมด ไม่ใช่จำนวนรายการในหน้าปัจจุบัน
`sourceDate`	วันที่ของข้อมูลผลฟุตบอลหรือบทวิเคราะห์ อาจเป็น null สำหรับบทวิเคราะห์

ฟิลด์ที่ไม่ส่งกลับกับค่าที่เป็น null มีความหมายต่างกัน ไม่ควรแทนคะแนนที่ยังไม่มีด้วยศูนย์ ส่วนเวลาที่ไม่มีวันที่หรือเขตเวลากำกับเป็นข้อความสำหรับแสดงผล ไม่ควรใช้เพียงอย่างเดียวเพื่อคำนวณเวลาเริ่มแข่ง

รายการ API

API ข้อมูลทั้ง 14 เส้นทางด้านล่างใช้ GET และต้องส่ง X-API-Key โดยนำเส้นทางมาต่อท้าย Base URL ส่งเฉพาะพารามิเตอร์ที่ระบุในแต่ละ API เท่านั้น หากส่งพารามิเตอร์ที่ไม่รองรับจะได้รับ 400

ค้นหา API

GETสิทธิ์ข้อมูล: ฟุตบอล

รายการแข่งขันฟุตบอล

/api/v1/sport/football/matches

เรียกดูรายการแข่งขันฟุตบอล พร้อมรหัสแมตช์ ชื่อทีม คะแนน สถานะ และข้อมูลช่อง นำรหัสแมตช์ที่ได้รับไปใช้เรียกรายละเอียดหรือเหตุการณ์การแข่งขันได้

รอบอัปเดตเริ่มต้น: 10 วินาที

พารามิเตอร์

ไม่มีพารามิเตอร์ ไม่ต้องส่ง query parameter เพิ่ม

ตัวอย่างคำขอ

cURL · GET

curl --fail-with-body --silent --show-error \
  --max-time 20 \
  --header "X-API-Key: $BALLIVE_API_KEY" \
  --header "Accept: application/json" \
  'https://ballive-api.yuier-4xy.com/api/v1/sport/football/matches'

ฟิลด์ข้อมูลที่ส่งกลับ

responseObject.data เป็นอาร์เรย์ ตารางด้านล่างอธิบายฟิลด์ของแต่ละรายการ และอาจได้รับอาร์เรย์ว่างเมื่อไม่มีข้อมูล

ฟิลด์	ชนิดข้อมูล	คำอธิบาย
`id`	`string`	รหัสการแข่งขัน เก็บและส่งต่อเป็นสตริง
`sport`	`string`	ชื่อประเภทกีฬา
`league`	`string`	ชื่อลีกหรือรายการแข่งขัน
`homeTeam.name / awayTeam.name`	`string`	ชื่อทีมเหย้าและทีมเยือน
`status`	`"live" \| "unknown"`	live คือกำลังแข่งขัน ส่วน unknown ยังไม่ระบุว่าเป็นรายการที่รอแข่งหรือจบแล้ว
`rawStatus`	`string \| null`	ข้อความสถานะการแข่งขันเพิ่มเติม หากไม่มีจะเป็น null
`isLive`	`boolean`	ระบุว่ากำลังแข่งขันอยู่หรือไม่
`score.home / score.away`	`integer \| null`	คะแนนของแต่ละทีม หากยังไม่มีคะแนนที่อ่านเป็นตัวเลขได้จะเป็น null
`score.display`	`string`	ข้อความคะแนนสำหรับแสดงผล
`startsAt`	`string \| null`	เวลาเริ่มแข่งในรูปแบบ ISO 8601 เมื่อมีข้อมูล ปัจจุบันส่งกลับเป็น null
`displayTime`	`string \| null`	ข้อความเวลาแข่งขัน ไม่ควรใช้ค่านี้เพียงอย่างเดียวเพื่อระบุวันที่หรือเขตเวลา
`channels`	`array`	รายการช่องที่เกี่ยวข้อง อาจเป็นอาร์เรย์ว่าง และไม่มี URL สำหรับเล่นวิดีโอ
`channels[].id / channels[].name`	`string`	รหัสและชื่อช่อง
`streamResource`	`object`	ข้อมูลอ้างอิงสำหรับสร้าง session สตรีมของแมตช์ ต้องมีสิทธิ์สตรีมเพิ่มเติม
`streamResource.type / streamResource.id`	`"match" / string`	ชนิดและรหัสรายการที่ใช้กับ API สร้าง session สตรีม

ตัวอย่างผลตอบกลับ

HTTP 200 · application/json

{
  "success": true,
  "message": "Sport data retrieved",
  "responseObject": {
    "data": [
      {
        "id": "12345",
        "sport": "football",
        "league": "ลีกตัวอย่าง",
        "homeTeam": {
          "name": "ทีมเหย้า"
        },
        "awayTeam": {
          "name": "ทีมเยือน"
        },
        "status": "live",
        "rawStatus": "2H",
        "isLive": true,
        "score": {
          "home": 2,
          "away": 1,
          "display": "2-1"
        },
        "startsAt": null,
        "displayTime": "20:00",
        "channels": [
          {
            "id": "ch1",
            "name": "ช่องกีฬาตัวอย่าง"
          }
        ],
        "streamResource": {
          "type": "match",
          "id": "12345"
        }
      }
    ],
    "meta": {
      "count": 1,
      "fetchedAt": "2026-10-23T12:00:00.000Z",
      "cache": "miss",
      "isStale": false
    }
  },
  "statusCode": 200
}

รหัสและข้อมูลในตัวอย่างใช้เพื่ออธิบายรูปแบบ ให้ใช้รหัสจริงจาก API รายการข้อมูลที่เกี่ยวข้อง หากเรียกไม่สำเร็จจะใช้รหัสข้อผิดพลาดตามตารางด้านล่าง ดูรหัสข้อผิดพลาด →

โควตาและการอัปเดตข้อมูล

โควตาคำขอคิดเป็นจำนวนครั้งต่อนาทีตามที่กำหนดให้บัญชี API Key ทุกอันในบัญชีเดียวกันใช้โควตาร่วมกัน การเรียกข้อมูลจากแคชยังนับโควตา และคำขอที่พารามิเตอร์ไม่ถูกต้องอาจใช้โควตาด้วย ตรวจสอบจำนวนที่เหลือได้จาก header ของผลตอบกลับ

Header ของผลตอบกลับ
Header	ความหมาย
`RateLimit-Limit`	จำนวนคำขอที่บัญชีเรียกได้ต่อนาที
`RateLimit-Remaining`	จำนวนคำขอที่เหลือในช่วงนาทีปัจจุบัน
`RateLimit-Reset`	จำนวนวินาทีก่อนเริ่มโควตารอบนาทีใหม่ เป็นระยะเวลา ไม่ใช่ Unix timestamp
`Retry-After`	หากมีในผลตอบกลับที่ผิดพลาด คือจำนวนวินาทีที่ควรรอก่อนเรียกใหม่
`X-Request-Id`	รหัสอ้างอิงคำขอสำหรับแจ้งปัญหากับทีมดูแล
`Cache-Control`	private, no-store ไม่ควรเก็บผลตอบกลับที่ยืนยันตัวตนแล้วในแคชสาธารณะที่ใช้ร่วมกัน

คำขอที่ไม่สำเร็จอาจไม่มี header โควตา ควรเว้นช่วงเรียกข้อมูลอย่างน้อยตามรอบอัปเดตของแต่ละ API และไม่เกินโควตาบัญชี เมื่อบริการขัดข้องชั่วคราว ระบบอาจส่งข้อมูลแคชที่เก่ากว่ารอบอัปเดต ให้ตรวจ meta.isStale และ meta.fetchedAt แทนการถือว่าทุกคำขอเป็นข้อมูลที่ดึงใหม่

รอบอัปเดตข้อมูลเริ่มต้น
ข้อมูล	รอบอัปเดต
แมตช์ฟุตบอล รายละเอียด และเหตุการณ์	10 วินาที
ผลการแข่งขันฟุตบอล	60 วินาที
มวย วัวชน ไก่ชน กีฬาอื่น ๆ และรายการพิเศษ	15 วินาที
ตารางคะแนน บทวิเคราะห์ และช่องทีวี	300 วินาที

ช่วงเวลานี้เป็นค่าแคชเริ่มต้น ไม่ได้รับประกันว่าข้อมูลทุกรายการจะเปลี่ยนในทุกรอบ บัญชีหรือบริการของคุณอาจใช้ค่าที่ต่างออกไป

รหัสข้อผิดพลาด

เมื่อเกิดข้อผิดพลาด success จะเป็น false และรหัสข้อผิดพลาดอยู่ที่ responseObject.error.code ให้ใช้ร่วมกับ HTTP status เพื่อจัดการคำขอ

HTTP 401 · ตัวอย่างข้อผิดพลาด

{
  "success": false,
  "message": "INVALID_API_KEY",
  "responseObject": {
    "error": {
      "code": "INVALID_API_KEY"
    }
  },
  "statusCode": 401
}

HTTP / code	ความหมายและวิธีแก้ไข
400`INVALID_REQUEST`	ตรวจสอบชื่อและค่าพารามิเตอร์ วันที่ และรูปแบบรหัส พร้อมลบพารามิเตอร์ที่เส้นทางนั้นไม่รองรับ
401`INVALID_API_KEY`	ไม่พบ API Key หรือ Key ไม่ถูกต้อง ถูกปิดใช้ หรือถูกเพิกถอน ตรวจสอบ header X-API-Key หรือขอ Key ใหม่
403`MEMBER_SUSPENDED`	บัญชีถูกระงับการใช้งาน กรุณาติดต่อทีมดูแล dooball-api
403`SPORT_ACCESS_DENIED`	สิทธิ์ใช้งานหมดอายุ หรือแพ็กเกจไม่ครอบคลุมบริการที่เรียก กรุณาตรวจสอบแพ็กเกจและสิทธิ์ของบัญชี
404`RESOURCE_NOT_FOUND`	ตรวจสอบเส้นทางและรหัสรายการ โดยใช้รหัสที่ได้รับจาก API รายการข้อมูลที่เกี่ยวข้อง
429`RATE_LIMIT_EXCEEDED`	จำนวนคำขอเกินโควตา กรุณารอตามจำนวนวินาทีใน header Retry-After ก่อนเรียกใหม่
502`UPSTREAM_BAD_RESPONSE`	ระบบไม่สามารถส่งข้อมูลที่ถูกต้องได้ กรุณาเว้นช่วงก่อนเรียกใหม่ หากยังพบปัญหาให้ติดต่อทีมดูแล
503`SPORT_SERVICE_UNAVAILABLE`	บริการไม่พร้อมใช้งานชั่วคราว หรือยังไม่ได้เปิดใช้งาน หากมี Retry-After ให้รอตามที่ระบุ หรือติดต่อทีมดูแล
504`UPSTREAM_TIMEOUT`	ระบบประมวลผลคำขอไม่ทันภายในเวลาที่กำหนด กรุณาเว้นช่วงก่อนเรียกใหม่และจำกัดจำนวนครั้ง
401`INVALID_STREAM_SESSION`	ลิงก์เริ่มเล่นไม่ถูกต้อง หมดอายุ หรือถูกใช้แล้ว กรุณาสร้าง session สตรีมใหม่

สำหรับ 429, 502, 503 และ 504 ให้เว้นช่วงก่อนเรียกใหม่ รอตาม Retry-After หากมี เพิ่มเวลารอระหว่างครั้ง และจำกัดจำนวนครั้ง เช่น ไม่เกิน 3 ครั้ง ส่วน 400, 401 และ 403 ควรแก้คำขอ Key หรือสิทธิ์ก่อนเรียกซ้ำ แอปควรจัดการกรณีหมดเวลา ปัญหาเครือข่าย และผลตอบกลับที่ไม่ใช่ JSON ด้วย

เมื่อติดต่อทีมดูแล ให้แจ้งเส้นทาง API, HTTP status, รหัสข้อผิดพลาด, X-Request-Id และเวลาที่เรียก โดยไม่ส่ง API Key หรือ token สำหรับเล่นวิดีโอ

API สตรีมวิดีโอ

บริการสตรีมวิดีโอต้องมีสิทธิ์สตรีมและสิทธิ์ข้อมูลของรายการที่เรียก แพ็กเกจข้อมูลอย่างเดียวไม่รวมสิทธิ์เล่นวิดีโอ กรุณาตรวจสอบบริการที่เปิดใช้กับบัญชีของคุณก่อนเชื่อมต่อ

สร้าง session สตรีม

POST /api/v1/sport/streams/sessions

ส่ง X-API-Key พร้อม Content-Type: application/json โดย body เป็น JSON และรับเฉพาะสองฟิลด์ด้านล่าง ใช้รหัสรายการที่ได้รับจาก API รายการข้อมูลที่เกี่ยวข้อง

ฟิลด์	การระบุ / ค่าที่รับได้
`resourceType` string	จำเป็น ระบุ match สำหรับแมตช์ฟุตบอล, tv สำหรับช่องทีวี หรือ wuachon สำหรับวัวชน
`resourceId` string	จำเป็น รหัสยาว 1–128 ตัวอักษร ใช้ A–Z, a–z, 0–9, _ และ - โดยต้องเป็นรหัสรายการของชนิดที่เลือก

ตัวอย่างคำขอสร้าง session

curl --fail-with-body --silent --show-error \
  --max-time 20 --request POST \
  --header "X-API-Key: $BALLIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"resourceType":"match","resourceId":"12345"}' \
  'https://ballive-api.yuier-4xy.com/api/v1/sport/streams/sessions'

HTTP 201 · ตัวอย่างผลตอบกลับ

{
  "success": true,
  "message": "Stream session created",
  "responseObject": {
    "playbackUrl": "/api/v1/sport/streams/play/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "bootstrapExpiresAt": "2026-10-23T12:01:00.000Z",
    "providerExpiresAt": null
  },
  "statusCode": 201
}

responseObject
ฟิลด์	คำอธิบาย
`playbackUrl`	เส้นทางเริ่มเล่นแบบ relative ให้นำไปต่อกับโดเมน API ไม่ใช่ Base URL ของข้อมูล
`bootstrapExpiresAt`	เวลาหมดอายุของลิงก์เริ่มเล่น รูปแบบ ISO 8601 ลิงก์มีอายุ 60 วินาทีหลังสร้าง
`providerExpiresAt`	ยังไม่ระบุเวลาสิ้นสุดการเล่น ปัจจุบันเป็น null ไม่ได้หมายถึงเล่นได้โดยไม่จำกัดเวลา

ใช้ลิงก์เริ่มเล่น

GET /api/v1/sport/streams/play/{token}

นำ playbackUrl ไปต่อกับ https://ballive-api.yuier-4xy.com แล้วส่ง URL เต็มให้ผู้ชมคนนั้นเป็นการส่วนตัว ผู้ชมต้องเรียก GET ภายใน 60 วินาที token ใช้ได้ครั้งเดียว ระบบตอบ HTTP 303 พร้อม header Location เพื่อเริ่มเล่น ไม่ได้ส่งผลตอบกลับ JSON แบบ API ข้อมูล

GET นี้ไม่ต้องส่ง X-API-Key เพราะ URL ให้สิทธิ์เริ่มเล่นได้หนึ่งครั้ง ห้าม prefetch ทดลองเปิด บันทึกใน log สาธารณะ หรือนำ URL กลับมาใช้ซ้ำ ให้สร้าง session ใหม่สำหรับผู้ชมแต่ละคน หรือเมื่อลิงก์หมดอายุหรือถูกใช้แล้ว

อายุ 60 วินาทีเป็นเวลาสำหรับเปิดลิงก์ ไม่ใช่ระยะเวลาที่เล่นวิดีโอ การเพิกถอน Key จะปิดการสร้าง session ใหม่และลิงก์ที่ยังไม่ใช้ แต่ไม่หยุดวิดีโอที่เริ่มเล่นไปแล้ว อุปกรณ์ player และเงื่อนไขการเล่นที่รองรับขึ้นอยู่กับบริการสตรีมที่เปิดใช้