세트피스 상세 기록 (Match Set-Piece Record)
GET
/api/playerSetPiece.do
경기에 발생한 세트피스(코너킥, 프리킥, PK 등)의 지점, 실행 선수, 도움 및 득점 상세 정보를 제공합니다.
요청 파라미터 (Request Parameters)
| 파라미터명 | 타입(Size) | 필수여부 | 설명 |
|---|---|---|---|
| authKey | varchar |
Y | API 인증키 (Header 전송 권장) |
| meet_year | varchar(4) |
Y | 대회년도 (예: 2026) |
| meet_seq | varchar(2) |
Y | 대회순번 (예: 1) |
| game_id | varchar(3) |
N | 경기번호 (0 또는 미입력 시 해당 대회의 전체 경기 조회) |
응답 필드 상세 명세 (Response Fields)
| 필드명 | 데이터 타입 | 설명 및 비고 |
|---|---|---|
| [Common] 공통 응답 필드 (JSON Header) | ||
| meet_year | varchar(4) | 요청한 대회년도 |
| meet_seq | varchar(2) | 요청한 대회순번 |
| apiName | varchar(30) | 호출된 API 명칭 (playerSetPiece) |
| 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) | 대회년도 / 대회순번 / 경기번호 |
| GROUP_SEQ / SEQ | int / int | 세트피스 발생 그룹순번 / 진행단계 상세 번호 |
| TEAM_ID / TEAM_NAME | varchar(3) / varchar(30) | 세트피스 얻은 측 구단 코드 / 구단명 (약칭) |
| [Section 2] 실행 선수, 시간 및 세트피스 패턴 정보 | ||
| PLAYER_ID_RUN / PLAYER_NAME | varchar(8) / varchar(20) | 세트피스 실행 선수 코드 / 선수 성명 |
| HALF_TYPE / HALF_TYPE_NAME | numeric(4,0) / varchar(40) | 전후반 구분 코드 / 명칭 (전반, 후반 등 / 공통코드:47) |
| TIME_MIN / TIME_SEC | numeric(2,0) / numeric(2,0) | 발생 시간 분 / 초 (원천 기록) |
| OFFICIAL_TIME | varchar(30) | 공식 시간 표기 (2026년부터 초 단위 올림 및 45+N분 가공 반영) |
| AST_POS / AST_POS_NAME | numeric(4,0) / varchar(40) | 도움 발생 위치 코드 / 위치명 (공통코드:71) |
| AST_WAY / AST_WAY_NAME | numeric(4,0) / varchar(40) | 도움 방법 코드 / 도움 방법명 (공통코드:46) |
| GOAL_WAY / GOAL_WAY_NAME | numeric(4,0) / varchar(40) | 득점 방법 코드 / 득점 방법명 (공통코드:45) |
| FAIL_CD / FAIL_CD_NAME | numeric(4,0) / varchar(40) | 실패 사유 코드 / 실패 사유명 (공통코드:105) |
| [Section 3] 슈팅 결과, 성공 여부 및 좌표 데이터 | ||
| GOAL_YN / ASSIST_YN | char(1) / varchar(1) | 득점 성공 여부 ('Y' / 'N') / 도움 인정 여부 ('Y' / 'N') |
| GOAL_POS / GOAL_POS_NAME | numeric(4,0) / varchar(40) | 슈팅 방향 코드 / 방향명 (공통코드:92) |
| GOAL_TYPE / GOAL_TYPE_NAME | numeric(4,0) / varchar(40) | 슈팅 종류 코드 / 슈팅 종류명 (공통코드:60) |
| X_POS / Y_POS | numeric(7,2) | 가로형 경기장 기준 세트피스 발생 정밀 좌표 |
| LINKSEQ / RELATION_NO / GOAL_TOUCH | int / varchar(12) / numeric(4,0) | 다음 단계 번호 / 득점 연결 고유 번호 / 골 터치 횟수 |
JSON 응답 샘플 (Set-Piece Data)
{
"response": {
"meet_year": "2026",
"apiName": "playerSetPiece",
"resultCode": "00",
"meet_seq": "2",
"list": [
{
"MEET_YEAR": "2026",
"MEET_SEQ": 2,
"GAME_ID": 3,
"GROUP_SEQ": 1,
"SEQ": 1,
"TEAM_ID": "K38",
"TEAM_NAME": "천안",
"PLAYER_ID_RUN": "20210314",
"PLAYER_NAME": "라마스",
"HALF_TYPE": 1,
"HALF_TYPE_NAME": "전반",
"TIME_MIN": 18,
"TIME_SEC": 10,
"AST_POS": 24,
"AST_POS_NAME": "PA정면",
"AST_WAY": 0,
"AST_WAY_NAME": "",
"GOAL_WAY": 0,
"GOAL_WAY_NAME": "",
"FAIL_CD": 5,
"FAIL_CD_NAME": "기타슈팅",
"GOAL_YN": "N",
"GOAL_POS": 0,
"GOAL_POS_NAME": "",
"GOAL_TYPE": 0,
"GOAL_TYPE_NAME": "",
"ASSIST_YN": "N",
"X_POS": 2700.00,
"Y_POS": 3900.00,
"LINKSEQ": 2,
"RELATION_NO": "20260200301S",
"GOAL_TOUCH": 0,
"OFFICIAL_TIME": "전반 19분"
},
{
"MEET_YEAR": "2026",
"MEET_SEQ": 2,
"GAME_ID": 3,
"GROUP_SEQ": 2,
"SEQ": 1,
"TEAM_ID": "K38",
"TEAM_NAME": "천안",
"PLAYER_ID_RUN": "20210314",
"PLAYER_NAME": "라마스",
"HALF_TYPE": 2,
"HALF_TYPE_NAME": "후반",
"TIME_MIN": 4,
"TIME_SEC": 20,
"AST_POS": 28,
"AST_POS_NAME": "AKR",
"AST_WAY": 0,
"AST_WAY_NAME": "",
"GOAL_WAY": 2,
"GOAL_WAY_NAME": "L-ST-G",
"FAIL_CD": 0,
"FAIL_CD_NAME": "",
"GOAL_YN": "Y",
"GOAL_POS": 1,
"GOAL_POS_NAME": "오른쪽",
"GOAL_TYPE": 2,
"GOAL_TYPE_NAME": "FK",
"ASSIST_YN": "N",
"X_POS": 8700.00,
"Y_POS": 5025.00,
"LINKSEQ": 2,
"RELATION_NO": "20260200302S",
"GOAL_TOUCH": 1,
"OFFICIAL_TIME": "후반 5분"
}
],
"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/playerSetPiece.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/playerSetPiece.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/playerSetPiece.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/playerSetPiece.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' } });