K리그 API 명세서

K LEAGUE Official Open API

파트너사가 K리그 데이터를 안정적이고 효율적으로 연동할 수 있도록 제공되는 표준 기술 명세서입니다.

Base URL

                                https://api.kleague.com/v1
                            

공통 응답 구조 (Common Response)

K LEAGUE API의 모든 응답은 response 최상위 객체로 감싸져 반환됩니다. resultCode: "00"은 성공을 의미하며, 실제 데이터는 list 배열에 담깁니다.

{
  "response": {
    "apiName": "comCode",      // 호출된 API 명칭 (varchar(30))
    "resultCode": "00",        // 결과 코드 ("00": 성공, 그 외: 에러) (varchar(3))
    "resultMsg": "success",    // 결과 메시지 (varchar(100))
    "list": [                  // 실제 데이터 결과 배열 (Array)
      {
        "COM_CODE": 1,
        "CODE_NAME": "방송사",
        "USE_YN": "Y"
      }
    ]
  }
}

공통 에러 코드 매핑표 (Result Codes)

코드(code)	메시지(resultMsg)	상세 원인 및 대응 조치
00	호출 성공	정상적으로 데이터를 반환하였습니다. (resultMsg: "success")
01	authKey를 입력하세요.	요청 헤더(Authorization) 또는 파라미터에 인증키가 누락되었습니다.
02	존재하는 authKey가 없습니다.	유효하지 않거나 등록되지 않은 인증키입니다.
03	권한이 없는 api를 호출했습니다.	해당 인증키로 접근할 수 없는 API 엔드포인트입니다.
04	권한이 없습니다.	사용 정지 상태 등 서버 보안 정책 위반입니다.
05	하루 요청 횟수 초과	일일 할당된 API 호출 쿼터(Call Count)를 초과하였습니다.
06	허용 가능한 IP가 아닙니다.	사전 등록되지 않은 IP 주소에서 접근을 시도하였습니다.
07	허용 가능한 도메인이 아닙니다.	사전 등록되지 않은 도메인(Referer)에서 호출되었습니다.
08	사용 정지 업체	계약 만료 또는 정책 위반으로 인해 API 사용이 정지된 파트너사입니다.
09	사용정지 API	시스템 점검 또는 폐기된 API 엔드포인트 호출입니다.

성능 최적화 및 통신 가이드

ETag 캐싱 지원

데이터 변경이 없을 시 304 Not Modified 응답을 통해 트래픽을 절감합니다.

If-None-Match: "W/5b3c-123456"

Gzip 데이터 압축

대규모 경기/선수 기록 연동 시 빠른 전송 속도를 위해 Gzip 압축을 권장합니다.

Accept-Encoding: gzip, deflate

경기 시간 데이터 연동 및 표출 가이드 (2026 시즌 기준)

연맹 공식 기록과의 일관성을 위해 2026 시즌부터 제공되는 OFFICIAL_TIME 컬럼의 데이터를 그대로 노출할 것을 강력히 권장합니다.

시간 데이터 구성 및 적용 로직

참조 컬럼	`OFFICIAL_TIME` 권장
기존 데이터	`TIME_MIN` / `SEC` (원천값)
가공 방식	초 단위 올림 + 한국어 공식 시간 가공

OFFICIAL_TIME 상황별 변환 예시

Standard Rules

상황 구분	원천 시간 (Min:Sec)	OFFICIAL_TIME 출력값
전반 정규시간	12분 20초	전반 13분
전반 추가시간	47분 02초	전반 45+3분
후반 추가시간	51분 56초	후반 45+7분
연장전	16분 05초	연장전반 15+2분

외부 채널 시스템 대응 주의사항

자체 재계산 금지: TIME_MIN 등을 이용해 임의로 계산할 경우 공식 기록과 1~2분 오차가 발생할 수 있습니다.
UI 레이아웃 점검: "후반 45+7분"과 같이 텍스트 길이가 늘어남에 따라 웹/모바일 앱의 줄바꿈 현상을 사전에 점검하십시오.
데이터 단일화: 연맹 공식 리포트, 전광판, 중계 자막과의 일관성을 위해 반드시 제공된 텍스트 데이터를 그대로 사용하십시오.

참고: 본 API의 response 객체 내 공통 정보는 HTTP 프로토콜의 Header와 별개로, K리그 API 서버에서 정의한 어플리케이션 레벨의 공통 규격입니다. 성공 여부 판단은 HTTP Status Code(200 OK)와 별개로 JSON 내의 resultCode를 기준으로 합니다.

Roadmap: 2027 시즌 대비 대개편 및 통합 포털 구축

안정적인 서비스 제공과 보안 강화를 위해 아래와 같이 개편을 준비 중입니다.

인증 방식 Header 기반 전환

2027 시즌부터 URL 파라미터 방식이 종료되고 HTTP Header 인증으로 단일화됩니다.

준비중

개발자 데이터 포털 오픈 예정

온라인 신청 및 자동 키 발급을 지원하는 portal.kleague.com을 준비 중입니다.