Data & Integration
배구 API
남녀 V리그와 KOVO컵의 시즌 구분, 세트 점수, 중계 이벤트, 선수 프로필과 데이터 제공 범위입니다.
배구는 네 개의 대회 ID를 사용합니다. 모든 요청에는 정확한 season이 필요하며 정규리그, 포스트시즌, 컵대회를 구분합니다. 스키마는 구현된 읽기 계약을 설명합니다. 운영 데이터 수집 여부는 운영 설정과 실제 수집 근거로 확인해야 합니다.
| 대회 ID | 허용 시즌 | 기본 phase | 추가 phase |
|---|---|---|---|
vleaguemen |
2025-26, 2026-27 |
regular |
postseason |
vleaguewomen |
2025-26, 2026-27 |
regular |
postseason |
kovocupmen |
2025, 2026 |
cup |
없음 |
kovocupwomen |
2025, 2026 |
cup |
없음 |
컵대회 stage는 group, semifinal, final입니다. V리그 포스트시즌은 semi-playoff, playoff, championship입니다. 시즌 누락이나 대회와 맞지 않는 phase는 400 오류이며 다른 시즌으로 대체하지 않습니다.
경기와 관련 기록
Section titled “경기와 관련 기록”curl -H "Authorization: Bearer $SPORTQUANTA_API_TOKEN" \ 'https://api.sportquanta.com/v1/vleaguewomen/games?season=2025-26&phase=postseason'응답의 canonicalId를 관련 리소스 조회에 사용합니다. 배구 데이터 필드는 externalIds, scheduleDate, homeSetsWon처럼 camelCase를 유지하고 외부 응답의 data, _meta 봉투는 기존 계약을 따릅니다.
/v1/{competition} 아래 경로 |
내용 |
|---|---|
/games, /games/{id} |
경기 상태, 한국 기준 일정, 세트 승수와 세트별 랠리 득점 |
/games/by-external-id/{source}/{externalId} |
같은 시즌·phase의 제공자 경기 ID 조회 |
/games/{id}/sets |
최신 기본 경기 스냅샷의 세트 기록 |
/games/{id}/events, /games/{id}/play-by-play |
스냅샷 기반 커서로 조회하는 순서 있는 중계 이벤트 |
/games/{id}/lineups |
세트별 제공자 라인업 슬롯; 코트 로테이션은 미검증 |
/games/{id}/box-score, /games/{id}/team-stats |
제공자가 발표한 경기별 팀 기록 |
/games/{id}/player-stats |
최신 기록 스냅샷의 선수 출전·박스스코어 |
/games/{id}/extended |
기본 경기 필드, 항목별 제공 상태, 근거와 미제공 항목 |
/teams, /players, /venues |
과거 소속 명단을 보장하지 않는 식별 디렉터리 |
/teams/{id}/roster |
해당 시즌 기록 또는 출전 기록으로 확인된 선수 |
/standings |
V리그 정규리그 순위 또는 공식 컵대회 조별 순위 |
/team-season-stats, /player-season-stats, /leaders |
발표된 phase별 집계와 수치 기준 리더 |
/statistic-definitions |
지표 네임스페이스, 단위, 분모와 검증 제한 |
관련 요청에는 같은 season, phase를 전달합니다. 목록의 기본 limit은 100, 최대값은 1000입니다. 커서는 이벤트 조회에만 제공됩니다. 다른 목록은 제한 개수에서 잘릴 수 있으므로 목록 길이로 완전한 수집을 판단하면 안 됩니다. /sets, /lineups, /box-scores는 범위를 지정한 컬렉션 조회도 지원합니다.
점수와 중계 수정
Section titled “점수와 중계 수정”homeSetsWon, awaySetsWon은 승리한 세트 수입니다. sets[].homePoints, sets[].awayPoints는 랠리 득점입니다. 경기 결과 3–1과 세트 점수 25–18을 구분해야 합니다. 5세트는 듀스로 18–16처럼 15점을 넘을 수 있습니다. 경기 전의 0–0 표시는 완료된 세트가 아닙니다.
이벤트는 sourcePage, sourceIndex, eventType, textType, 원문과 점수 상태를 보존합니다. ET는 한 세트의 종료이며 그것만으로 경기 종료를 결정하지 않습니다. 등번호와 원문만 있는 선수는 playerId: null을 유지합니다. videoOffsetSeconds는 영상 위치입니다. 실제 발생 시각이 없으면 occurredAt은 null입니다.
hasMore, nextCursor를 확인하고 같은 범위와 setNumber 조건으로 다음 페이지를 요청합니다. 제공자 수정으로 내용이나 이벤트 목록이 바뀌면 409 snapshot_changed_restart_pagination이 반환됩니다. 커서를 버리고 첫 페이지부터 다시 조회하십시오. 잘못된 커서는 400입니다. 불완전한 중계 재조회는 이전의 유효한 스냅샷을 보존하며 실패 항목을 coverage에 표시합니다.
선수와 지표
Section titled “선수와 지표”선수 상세에는 생년월일, cm 단위 키, kg 단위 몸무게, 학교, 경력 원문, 수상 내역, 공식 이력과 시즌별 경력 기록이 포함될 수 있습니다. 현재 프로필·명단의 소속과 과거 시즌 기록의 팀은 다를 수 있습니다. 경력 원문을 정규화된 이적 거래나 감독 이력으로 해석하면 안 됩니다.
네이버 지표는 metricNamespace: "naver"와 원래 키를 유지합니다. 선수 득점 point, 팀 랠리 득점 totalPoint, 순위 승점 points는 서로 다릅니다. 음수 리시브 효율도 보존합니다. 비율은 제공자 발표값이며 누락은 0이 아닙니다. 리더의 기본 지표는 point이며 값의 내림차순, canonical ID 순서로 동률을 처리합니다.
official에는 확인된 관중 수, 경기 관계자, 경기장과 실제 플레이 시간이 들어갈 수 있습니다. 플레이 시간은 휴식 등을 포함한 벽시계 경과 시간이 아닙니다. officialRecords.namespace는 kovo이며 축약된 팀·선수 지표와 세트 출전 플래그는 배율 검증 전까지 원문으로 보존합니다. 네이버 지표와 비교하기 전에 지표 정의를 확인하십시오. 이 필드는 기본 경기 상세에도 포함될 수 있고 /extended는 제공 범위 봉투를 덧붙입니다.
provenance=true는 필드별 원문 _prov를 포함합니다. evidence, fieldObservedAt은 수집 근거의 나이를 설명하고 updatedAt은 문서 쓰기 시각입니다. 한 프로필 필드가 갱신되었다고 오래된 경기 점수까지 최신이 되는 것은 아닙니다.
이미지는 자체 저장소에 복제된 logoAssetKey, headshotAssetKey를 SportQuanta 자산 해석기로 처리합니다. 이미지가 없으면 자리표시자를 사용하십시오. 외부 ID로 제공자 이미지 URL을 만들거나 외부 이미지를 직접 서비스하지 마십시오.
네이버가 기본 소스이고 검증된 KOVO 보완 데이터는 독립된 소스 제어와 출처를 가집니다. 검증된 소스 경로는 준비되어 있지만 네 대회의 마스터 수집 스위치는 기본 비활성입니다. 구현만으로 배포·활성화 또는 운영 데이터 수집 완료를 주장하지 않습니다.
| 데이터 | 확인된 소스 범위 | 제한 |
|---|---|---|
| 일정·기본 경기 | 8개 대회·시즌 범위 | 조건부 포스트시즌 일정은 예정 경기로 유지 |
| 중계·라인업 슬롯·박스스코어 | 제공자가 발표한 경기별 기록 | 항목 실패 시 이전 유효 스냅샷과 재시도 근거 유지 |
| 팀·선수 시즌 통계 | V리그 정규리그 | 2026-27은 미발표일 수 있고 컵·포스트시즌으로 대체하지 않음 |
| 컵 순위 | 공식 조별리그 | 랠리 득점은 승점이 아니며 토너먼트는 조별 순위가 아님 |
| 현재 명단·프로필 | 확인된 현재 또는 제공자 식별 정보 | 완전한 과거 선수 명단을 보장하지 않음 |
| 감독·전체 심판 디렉터리·사이드아웃·로테이션 효율·배당 | 미검증 또는 미제공 | 추정 지표와 미검증 북메이커 매핑을 생성하지 않음 |
2026-10-17 소스 조사에서 2025-26은 남녀 각각 정규리그 126경기와 남자 포스트시즌 8경기, 여자 6경기를 확인했습니다. 2026-27은 남녀 각각 정규리그 126경기와 조건부 포스트시즌 9일정입니다. 2025·2026 컵대회는 남녀 각 12일정이며 2025-26 정규리그 선수 통계 행은 남자 149, 여자 134명이 관측되었습니다. 이는 소스 목록의 수치이며 운영 수집 건수나 명단 완전성 보장이 아닙니다.