포메이션 및 엔트리 조회 (Match Entry)
GET
/api/matchEntry.do
특정 경기에 출전한 양 팀의 선발/대기 명단과 시각화용 포메이션 좌표 데이터를 제공합니다.
전술판(세로 하프코트) vs 경기장(가로 전체) 좌표 활용 가이드
세로형 하프코트 (PLAYER_FORMATION_PLACE)
중앙선 (Center Line)
9
우리팀 골대 (Goal)
- 참조: 하단 [전술 포메이션 레이아웃] 이미지 내 번호 매칭
- 기준: 세로형 하프코트 (하단:우리팀 골대 / 상단:중앙선)
가로형 전체 경기장 (XPOS, YPOS)
(0,0) Origin
Full Pitch (가로형)
- 기준: 경기장 좌측 상단 코너가 (0,0) 기준
- 용도: 전체 피치상에서의 정밀 선수 위치 시각화
요청 파라미터 (Request Parameters)
| 파라미터명 | 타입(Size) | 필수여부 | 설명 |
|---|---|---|---|
| authKey | varchar |
Y | API 인증키 (Header 전송 권장) |
| meet_year | varchar(4) |
Y | 대회년도 (예: 2026) |
| meet_seq | varchar(2) |
Y | 대회순번 (예: 1) |
| game_id | varchar(3) |
Y | 경기번호 (예: 1) |
전술 포메이션 레이아웃 (세로형 하프코트 가이드)
* PLAYER_FORMATION_PLACE 데이터 값은 아래 이미지들의 노란색 동그라미 번호를 의미합니다.
343
343d
352
433
442
451
523
532
541
4231
4141
응답 필드 상세 명세 (Response Fields)
| 필드명 | 데이터 타입 | 설명 및 가이드 |
|---|---|---|
| [Common] 공통 응답 필드 (JSON Header) | ||
| meet_year | varchar(4) | 요청한 대회년도 |
| meet_seq | varchar(2) | 요청한 대회순번 |
| apiName | varchar(30) | 호출된 API 명칭 (matchEntry) |
| 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 / TEAM_NAME | varchar(3) / varchar(30) | 구단 코드 / 구단명 (약칭) |
| PLAYER_ID / PLAYER_NAME / PLAYER_NAME_ENG | varchar(8) / varchar(20) / varchar(50) | 선수 코드 / 선수 성명 / 영문 성명 (풀네임) |
| PLAYER_SEQ | int | 선수 일련번호 (선발: 1~11, 대기: 12~) |
| BACK_NO | int | 등번호 (배번) |
| POSITION_CODE / POSITION_NAME | numeric(4,0) / varchar(40) | 포지션 코드 / 포지션 명칭 (GK, DF, MF, FW / 공통코드:42) |
| CAPTAIN_YN | char(1) | 주장 여부 ('Y' / 'N') |
| [Section 2] 포메이션 및 시각화 좌표 데이터 (방향성 주의) | ||
| PLAYER_FORMATION_PLACE | varchar(10) |
세로 하프코트 가이드 이미지 내 노란 번호 매칭 (전술 배치 번호) |
| XPOS / YPOS | numeric(5,2) |
가로 전체 경기장 기준 정밀 시각화 좌표 (피치 좌상단 0,0 기준) |
JSON 응답 샘플 (Set-Piece & Formation Data)
{
"response": {
"meet_year": "2026",
"apiName": "matchEntry",
"resultCode": "00",
"meet_seq": "1",
"list": [
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20200301",
"PLAYER_NAME": "구성윤",
"PLAYER_NAME_ENG": "Sungyun GU",
"PLAYER_SEQ": 1,
"BACK_NO": 25,
"POSITION_CODE": 1,
"POSITION_NAME": "GK",
"CAPTAIN_YN": "N",
"XPOS": 0.00,
"YPOS": 50.00,
"PLAYER_FORMATION_PLACE": "1"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20170185",
"PLAYER_NAME": "김진수",
"PLAYER_NAME_ENG": "Jinsu KIM",
"PLAYER_SEQ": 2,
"BACK_NO": 22,
"POSITION_CODE": 2,
"POSITION_NAME": "DF",
"CAPTAIN_YN": "Y",
"XPOS": 9.17,
"YPOS": 19.23,
"PLAYER_FORMATION_PLACE": "5"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20260048",
"PLAYER_NAME": "로스",
"PLAYER_NAME_ENG": "Juan Antonio ROS MARTINEZ",
"PLAYER_SEQ": 3,
"BACK_NO": 37,
"POSITION_CODE": 2,
"POSITION_NAME": "DF",
"CAPTAIN_YN": "N",
"XPOS": 9.17,
"YPOS": 39.20,
"PLAYER_FORMATION_PLACE": "4"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20220163",
"PLAYER_NAME": "박성훈",
"PLAYER_NAME_ENG": "Seonghoon PARK",
"PLAYER_SEQ": 4,
"BACK_NO": 40,
"POSITION_CODE": 2,
"POSITION_NAME": "DF",
"CAPTAIN_YN": "N",
"XPOS": 9.17,
"YPOS": 59.18,
"PLAYER_FORMATION_PLACE": "3"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20200041",
"PLAYER_NAME": "최준",
"PLAYER_NAME_ENG": "Jun CHOI",
"PLAYER_SEQ": 5,
"BACK_NO": 16,
"POSITION_CODE": 2,
"POSITION_NAME": "DF",
"CAPTAIN_YN": "N",
"XPOS": 9.17,
"YPOS": 79.15,
"PLAYER_FORMATION_PLACE": "2"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20180034",
"PLAYER_NAME": "송민규",
"PLAYER_NAME_ENG": "Minkyu SONG",
"PLAYER_SEQ": 6,
"BACK_NO": 34,
"POSITION_CODE": 3,
"POSITION_NAME": "MF",
"CAPTAIN_YN": "N",
"XPOS": 23.84,
"YPOS": 19.23,
"PLAYER_FORMATION_PLACE": "9"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 1,
"GAME_ID": 1,
"TEAM_ID": "K09",
"TEAM_NAME": "서울",
"PLAYER_ID": "20260045",
"PLAYER_NAME": "바베츠",
"PLAYER_NAME_ENG": "Hrvoje BABEC",
"PLAYER_SEQ": 7,
"BACK_NO": 6,
"POSITION_CODE": 3,
"POSITION_NAME": "MF",
"CAPTAIN_YN": "N",
"XPOS": 23.84,
"YPOS": 39.20,
"PLAYER_FORMATION_PLACE": "8"
}
],
"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/matchEntry.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/matchEntry.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/matchEntry.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/matchEntry.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' } });