K리그 API 명세서

GET

/api/matchTimeSheet2.do

득점, 경고, 퇴장, 교체 등 주요 경기 이벤트의 상세 문자 중계 데이터와 비고 정보를 국문/영문으로 제공합니다.

요청 파라미터 (Request Parameters)

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

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

필드명	데이터 타입	설명 및 가이드
[Common] 공통 응답 필드 (JSON Header)
meet_year	`varchar(4)`	요청한 대회년도
meet_seq	`varchar(2)`	요청한 대회순번
apiName	`varchar(30)`	호출된 API 명칭 (matchTimeSheet2)
resultCode	`varchar(3)`	결과 코드 (00: 성공, 그 외 에러는 API 개요 참조)
resultMsg	`varchar(100)`	결과 메시지 ("success")
[Section 1] 이벤트 분류 및 마스터 키 정보
RECTYPE / GUBUN	`varchar(10)` / `varchar(10)`	기록 타입 ('goal', 'warn', 'etc', 'inout') / 세부 구분 코드 ('GL', 'YC', 'RC', 'SY', 'ST', 'PK', 'CH' 등)
MEET_YEAR / MEET_SEQ / GAME_ID	`varchar(4)` / `numeric(2,0)` / `numeric(3,0)`	대회년도 / 대회순번 / 경기번호
SUB_KEY	`varchar(50)`	상세 이벤트 식별 고유 문자 조합 키
[Section 2] 팀 및 해당 이벤트 선수 정보
TEAM_ID / TEAM_NAME / TEAM_NAME_ENG	`varchar(3)` / `varchar(30)` / `varchar(50)`	구단 코드 / 구단 한글명 (약칭) / 구단 영문명
PLAYER_ID / PLAYER_NAME / PLAYER_NAME_ENG	`varchar(8)` / `varchar(20)` / `varchar(50)`	선수 코드 / 성명 (한글) / 성명 (영문 풀네임)
[Section 3] 시간 및 국문/영문 문자 중계 (Text Remark)
HALF_TYPE	`numeric(4,0)`	전후반 구분 코드 (1:전반, 2:후반, 3:연장전반, 4:연장후반 / 공통코드:47)
TIME_MIN / TIME_SEC	`varchar(10)` / `varchar(10)`	발생 시점 분 / 초
REMARK / REMARK_ENG	`varchar(500)`	공식 문자 중계 텍스트 (국문 / 영문 - 2026년부터 초 단위 올림 및 45+N분 정산 표출 적용)
[Section 4] 이벤트별 비고 데이터 (ETC1 ~ ETC10)
ETC1 ~ ETC5	`varchar(30)`	* RECTYPE별 매핑항목: - goal: X좌표(득점) / Y좌표(득점) / X좌표(도움) / Y좌표(도움) / 연결번호 - warn: X좌표 / Y좌표 / 경기퇴장사유 (공통코드:72) / - / - - etc: X좌표 / Y좌표 / 연결번호 / 득점여부(Y/N) / - - inout: 교체In선수 ID / 포지션코드 (공통코드:42) / - / - / -
ETC6 ~ ETC10	`varchar(30)`	* RECTYPE별 매핑항목: - goal: 자책골여부(Y/N) / PK여부(Y/N) / 선제득점여부(Y/N) / 결승골여부(Y/N) / 상대골키퍼 ID - warn / etc / inout: 미사용 (공백 처리)

JSON 응답 샘플 (Timeline Text Detail)

{
    "response": {
        "meet_year": "2026",
        "apiName": "matchTimeSheet2",
        "resultCode": "00",
        "meet_seq": "1",
        "list": [
            {
                "RECTYPE": "goal",
                "GUBUN": "GL",
                "MEET_YEAR": "2026",
                "MEET_SEQ": 1,
                "GAME_ID": 1,
                "SUB_KEY": "1_",
                "TEAM_ID": "K09",
                "TEAM_NAME": "서울",
                "TEAM_NAME_ENG": "SEOUL",
                "PLAYER_ID": "20180034",
                "PLAYER_NAME": "송민규",
                "PLAYER_NAME_ENG": "Minkyu SONG",
                "HALF_TYPE": 2,
                "TIME_MIN": "1",
                "TIME_SEC": "44",
                "REMARK": "후반 2분 송민규 득점",
                "REMARK_ENG": "second half 2 Minkyu SONG Goal",
                "ETC1": "0.00",
                "ETC2": "0.00",
                "ETC3": "0.00",
                "ETC4": "0.00",
                "ETC5": "20260100101G",
                "ETC6": "N",
                "ETC7": "N",
                "ETC8": "Y",
                "ETC9": "N",
                "ETC10": "20190064"
            },
            {
                "RECTYPE": "goal",
                "GUBUN": "GL",
                "MEET_YEAR": "2026",
                "MEET_SEQ": 1,
                "GAME_ID": 1,
                "SUB_KEY": "2_",
                "TEAM_ID": "K09",
                "TEAM_NAME": "서울",
                "TEAM_NAME_ENG": "SEOUL",
                "PLAYER_ID": "20180073",
                "PLAYER_NAME": "조영욱",
                "PLAYER_NAME_ENG": "Youngwook CHO",
                "HALF_TYPE": 2,
                "TIME_MIN": "15",
                "TIME_SEC": "57",
                "REMARK": "후반 16분 조영욱 득점",
                "REMARK_ENG": "second half 16 Youngwook CHO Goal (Anderson DE OLIVEIRA DA SILVA Assist)",
                "ETC1": "1965.00",
                "ETC2": "3240.00",
                "ETC3": "0.00",
                "ETC4": "0.00",
                "ETC5": "20260100102G",
                "ETC6": "N",
                "ETC7": "N",
                "ETC8": "N",
                "ETC9": "Y",
                "ETC10": "20190064"
            },
            {
                "RECTYPE": "warn",
                "GUBUN": "YC",
                "MEET_YEAR": "2026",
                "MEET_SEQ": 1,
                "GAME_ID": 1,
                "SUB_KEY": "K09_1_",
                "TEAM_ID": "K09",
                "TEAM_NAME": "서울",
                "TEAM_NAME_ENG": "SEOUL",
                "PLAYER_ID": "20250331",
                "PLAYER_NAME": "클리말라",
                "PLAYER_NAME_ENG": "Patryk KLIMALA",
                "HALF_TYPE": 1,
                "TIME_MIN": "8",
                "TIME_SEC": "46",
                "REMARK": "전반 9분 클리말라 경고",
                "REMARK_ENG": "first half 9 Patryk KLIMALA Yellow Card",
                "ETC1": "6855.00",
                "ETC2": "2280.00",
                "ETC3": "35",
                "ETC4": "",
                "ETC5": "",
                "ETC6": "",
                "ETC7": "",
                "ETC8": "",
                "ETC9": "",
                "ETC10": ""
            },
            {
                "RECTYPE": "inout",
                "GUBUN": "CH",
                "MEET_YEAR": "2026",
                "MEET_SEQ": 1,
                "GAME_ID": 1,
                "SUB_KEY": "K09_20180034_",
                "TEAM_ID": "K09",
                "TEAM_NAME": "서울",
                "TEAM_NAME_ENG": "SEOUL",
                "PLAYER_ID": "20180034",
                "PLAYER_NAME": "송민규",
                "PLAYER_NAME_ENG": "Minkyu SONG",
                "HALF_TYPE": 2,
                "TIME_MIN": "27",
                "TIME_SEC": "10",
                "REMARK": "후반 28분 송민규 교체 Out 정승원 교체 In",
                "REMARK_ENG": "second half 28 Minkyu SONG change out Seungwon JUNG change in",
                "ETC1": "20160099",
                "ETC2": "3",
                "ETC3": "",
                "ETC4": "",
                "ETC5": "",
                "ETC6": "",
                "ETC7": "",
                "ETC8": "",
                "ETC9": "",
                "ETC10": ""
            }
        ],
        "resultMsg": "success"
    }
}

호출 샘플 소스 (Sample Code)

Auth: Header or QueryString

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

OkHttpClient client = new OkHttpClient();

// [방법 1] Query String 방식
String url1 = "https://api.kleague.com/api/matchTimeSheet2.do?authKey=YOUR_API_KEY&meet_year=2026&meet_seq=1&game_id=1";
Request request1 = new Request.Builder().url(url1).get().build();

// [방법 2] Header 방식 (현재 권장)
String url2 = "https://api.kleague.com/api/matchTimeSheet2.do?meet_year=2026&meet_seq=1&game_id=1";
Request request2 = new Request.Builder()
  .url(url2)
  .addHeader("authKey", "YOUR_API_KEY") 
  .build();

// [방법 3] Bearer Token 방식 (2027년 지원 예정)
Request request3 = new Request.Builder()
  .url(url2)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN") 
  .build();

import requests

url = "https://api.kleague.com/api/matchTimeSheet2.do"
params = { 
    "meet_year": "2026", 
    "meet_seq": "1", 
    "game_id": "1" 
}

# [방법 1] Query String 방식
response1 = requests.get(url, params={**params, "authKey": "YOUR_API_KEY"})

# [방법 2] Header 인증 방식 (현재 추천)
headers2 = { "authKey": "YOUR_API_KEY" }
response2 = requests.get(url, headers=headers2, params=params)

# [방법 3] Bearer Token 방식 (2027년 도입 예정)
# headers3 = { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
# response3 = requests.get(url, headers=headers3, params=params)

const url = 'https://api.kleague.com/api/matchTimeSheet2.do';
const params = { meet_year: '2026', meet_seq: '1', game_id: '1' };

// [방법 1] Query String 방식
axios.get(url, { params: { ...params, authKey: 'YOUR_API_KEY' } });

// [방법 2] Header 방식 (현재 권장)
axios.get(url, {
    params: params,
    headers: { 'authKey': 'YOUR_API_KEY' }
});

// [방법 3] Bearer 방식 (2027년 로드맵 대비)
// axios.get(url, { params: params, headers: { 'Authorization': 'Bearer YOUR_TOKEN' } });