K리그 API 명세서

GET

/api/unOfficialMatchPlayerRecordDetail.do

특정 경기의 선수별 이벤트 좌표(X, Y, Z), 기대득점(xG), 패스 및 수비 세부 지표 데이터를 타임라인순으로 제공합니다.

요청 파라미터 (Request Parameters)

파라미터명	타입(Size)	필수여부	설명
authKey	`varchar`	Y	API 인증키 (Header 전송 권장)
meet_year	`varchar(4)`	Y	대회년도 (예: 2026)
meet_seq	`varchar(2)`	Y	대회순번 (예: 1)
team_id	`varchar(3)`	Y	구단 코드 (예: K05)
game_id	`varchar(3)`	Y	경기번호 (예: 1)

슈팅 탄착 구역 시각화 (SHOT_GOALPOST_SITE)

Goal Post Matrix

골포스트 탄착 코드 매핑:
* 골대 안쪽 (Inside): HL(좌상), HC(중상), HR(우상) / LL(좌하), LC(중하), LR(우하)
* 골대 바깥쪽 (Outside/Close): CHL(좌상 밖), CH(상단 밖), CHR(우상 밖) / CL(좌측 밖), CR(우측 밖)

응답 필드 상세 명세 (Response Fields)

필드명	데이터 타입	설명 및 비고
[Common] 공통 응답 필드 (JSON Header)
apiName	`varchar(30)`	호출된 API 명칭 (unOfficialMatchPlayerRecordDetail)
resultCode	`varchar(3)`	결과 코드 (00: 성공, 그 외 에러는 API 개요 참조)
resultMsg	`varchar(100)`	결과 메시지 ("success")
[Section 1] 경기 및 선수 마스터 정보
MEET_YEAR / MEET_SEQ / GAME_ID	`varchar(4)` / `numeric(2,0)` / `numeric(3,0)`	대회년도 / 대회순번 / 경기번호
TEAM_ID / PLAYER_ID / PLAYER_NM	`varchar(3)` / `varchar(8)` / `varchar(20)`	구단 코드 / 선수 코드 / 선수 성명
[Section 2] 시간, 피치 위치 좌표 및 구역 (Pitch Coordinates)
PERIOD_ID / OFFICIAL_TIME	`numeric(5,0)` / `varchar(30)`	전후반 구분 코드 (1:전반, 2:후반, 3:연장전반...) / 공식 표기 시간
MIN_TIME / SEC_TIME	`numeric(5,0)`	이벤트 발생 시점 분 / 초
START_POINT_X / START_POINT_Y	`numeric(6,1)`	축구장 시작 X / Y 좌표 (단위: m)
END_POINT_X / END_POINT_Y / END_POINT_Z	`numeric(6,1)` / `numeric(5,0)`	축구장 종료 X / Y / Z 좌표 (단위: m)
HA_CODE / START_POINT	`varchar(3)` / `varchar`	홈/어웨이 구분 ('H': Home, 'A': Away) / 시작 지점 코드
[Section 3] 이벤트 타입 분류 및 패스 상세 분석
TYPE_ID / TYPE_CD / TYPE_DETAIL_CD	`varchar` / `varchar(8)` / `varchar(5)`	이벤트 ID / 이벤트 대분류 코드 / 세부 유형 코드
TYPE_DETAIL_CD2	`varchar(5)`	특수 상황 구분 코드 (세트피스 및 특수 슈팅/패스) * KEYPASS_YN_CD: Y (키패스) * FRONT_PASS_YN_CD: Y (전방), N (후방), T (횡) * ASSIST_YN_CD: Y (어시스트)
PASS_YN_CD / KEYPASS_YN_CD / ASSIST_YN_CD	`varchar(3)`	패스 성공 여부 ('Y' / 'N') / 키패스 여부 ('Y' / 'N') / 어시스트 여부 ('Y' / 'N')
PA_AREA_YN_CD / FRONT_PASS_YN_CD	`varchar(3)`	PA 영역 내 발생 여부 ('Y' / 'N') / 패스 방향 구분 ('Y': 전방, 'N': 후방, 'T': 횡패스)
PASS_LENGTH	`numeric(5,1)`	패스 이동 거리 (단위: m)
[Section 4] 경합, 슈팅 탄착점 및 xG (기대득점)
DUELS_CD	`varchar(5)`	경합 구분 코드 (ADW, ADL, GDW, GDL)
SHOT_GOALPOST_SITE	`varchar(5)`	골포스트 탄착 구역 코드
OWN_GOAL_CODE	`varchar(3)`	자책골 여부 코드 ('Y')
EXPECTED_GOAL	`numeric(4,3)`	기대득점 수치 (xG Value)

이벤트 세부 코드 매핑 참조표 (TYPE_CD / TYPE_DETAIL_CD)

대분류 (TYPE_CD)	세부코드 (TYPE_DETAIL_CD)	특수구분 (TYPE_DETAIL_CD2)	이벤트명 (EVENT NAME)	세부 플래그 조건 (DUELS_CD / KEYPASS / FRONT 등)
DU (Duels)	ADW / ADL	-	공중경합 성공 / 실패	DUELS_CD: `ADW` (공중 성공), `ADL` (공중 실패) DUELS_CD: `GDW` (지상 성공), `GDL` (지상 실패)
DU (Duels)	GDW / GDL	-	지상경합 성공 / 실패
PS (Pass)	PSS / PSU	FK : 프리킥 TH : 스로인 CK : 코너킥 PK : 페널티킥	패스 성공 / 실패	KEYPASS_YN_CD: `Y` (키패스) FRONT_PASS_YN_CD: `Y` (전방), `N` (후방), `T` (횡) ASSIST_YN_CD: `Y` (어시스트)
	OPCS / OPCU		오픈플레이 크로스 성공 / 실패
	STCS / STCU		세트피스 크로스 성공 / 실패
	PSS (Ball Received)		패스 수신 (Ball Received) 이벤트 연동
ST (Shooting)	GL / AST / BT / MST	FK (프리킥) TH : 스로인 CK : 코너킥 PK : 페널티킥	득점(GL) / 유효슈팅(AST) / 블록된슈팅(BT) / 벗어난슈팅(MST)	슈팅 세부 기록 및 xG(기대득점) 계산 이벤트
DF (Defense)	TKS / TKU / INT / CLG / RCV / STB / CUT / MISS	-	태클, 인터셉트, 클리어링, 리커버리, 블록(STB), 인터벤션(CUT), 수비에러(MISS)	수비 액션 및 빌드업 차단/실수 이벤트
SR (Dribble)	DS / DU	-	드리블 성공(DS) / 드리블 실패(DU)	돌파 및 1대1 드리블 시도
FO (Foul)	FOW / FOC / OFS / YLC / RDC	-	피반칙, 반칙, 오프사이드, 경고(YLC), 퇴장(RDC)	파울 및 징계 카드 정보
GK (Goalkeeper)	CT / PC / GC / GKS / GKU / ARS / ARU	-	캐칭, 펀칭, 실점, 골킥(성공/실패), 공중클리어링(성공/실패)	골키퍼 수비 및 리스타트 액션

[비고] 세트피스 속성 결합 및 패스·수신(RCV) 데이터 정제 메커니즘 안내

세트피스 속성 결합 및 크로스 보정 (TYPE_DETAIL_CD2):
코너킥(CK), 프리킥(FK), 스로인(TH) 상황은 원천 데이터에서 '세트피스 종류 로그'와 '슈팅/패스 로그'가 분리되어 유입됩니다[cite: 1, 2, 3]. 프로시저 후처리 단에서 동일 이벤트 번호(EVENT_BEPRO)를 기준으로 병합하여, 슈팅(ST) 및 패스(PS) 행에 세트피스 속성을 공통으로 이식하며, 이 과정에서 오픈플레이 크로스(OPCS/OPCU)는 세트피스 크로스(STCS/STCU)로 자동 보정됩니다[cite: 1, 2, 3].
패스 수신 및 리커버리 연계 (PS + RCV):
원천 데이터의 Recovery 및 연계 이벤트가 패스 세션과 결합될 때 부여되는 세부 코드입니다. 단순 수비 리커버리와는 다르게, 소유권 탈환 직후에 전방으로 곧바로 이어진 긴급 연계 패스 성공 성격을 동시에 내포하고 있습니다.
순수 패스 성공 vs 연계 패스 구분 조회:
* 순수 빌드업 패스 성공: TYPE_CD = 'PS' AND TYPE_DETAIL_CD = 'PSS' AND PASS_YN_CD = 'Y'
* 크로스 및 리커버리 연계 포함 전체 성공: TYPE_CD = 'PS' AND TYPE_DETAIL_CD IN ('PSS', 'OPCS', 'STCS', 'RCV') AND PASS_YN_CD = 'Y'

JSON 응답 샘플 (Match Player Record Detail)

{
    "response": {
        "meet_year": "2026",
        "apiName": "unOfficialMatchPlayerRecordDetail",
        "resultCode": "00",
        "meet_seq": "1",
        "list": [
            {
                "MEET_YEAR": "2026",
                "MEET_SEQ": 1,
                "GAME_ID": 1,
                "TEAM_ID": "K05",
                "PLAYER_ID": "20060011",
                "PLAYER_NM": "최철순",
                "PERIOD_ID": 1,
                "MIN_TIME": 0,
                "SEC_TIME": 18,
                "START_POINT_X": 39.5,
                "START_POINT_Y": 91.5,
                "HA_CODE": "H",
                "TYPE_CD": "DF",
                "TYPE_DETAIL_CD": "INT",
                "OFFICIAL_TIME": "전반 0분"
            }
        ],
        "resultMsg": "success"
    }
}

호출 샘플 소스 (Sample Code)

Auth: Header or QueryString

인증 로드맵: 현재 authKey 기반 인증을 지원하며, 2027년부터 표준 Bearer Token 인증 체계로 통합 확장될 예정입니다.

OkHttpClient client = new OkHttpClient();

String url2 = "https://api.kleague.com/api/unOfficialMatchPlayerRecordDetail.do?meet_year=2026&meet_seq=1&team_id=K05&game_id=1";
Request request2 = new Request.Builder()
  .url(url2)
  .addHeader("authKey", "YOUR_API_KEY") 
  .build();

import requests

url = "https://api.kleague.com/api/unOfficialMatchPlayerRecordDetail.do"
params = { "meet_year": "2026", "meet_seq": "1", "team_id": "K05", "game_id": "1" }
headers = { "authKey": "YOUR_API_KEY" }
response = requests.get(url, headers=headers, params=params)

const url = 'https://api.kleague.com/api/unOfficialMatchPlayerRecordDetail.do';
axios.get(url, {
    params: { meet_year: '2026', meet_seq: '1', team_id: 'K05', game_id: '1' },
    headers: { 'authKey': 'YOUR_API_KEY' }
});