콘텐츠로 이동

도움 받기

원하시는 도움을 선택해주세요.

섹션 제목: “원하시는 도움을 선택해주세요.”

Base URL은 https://api.chizumulu.net입니다. 모든 경로는 엔드포인트에 나열되어 있으며, 거기 없는 경로는 404 {"error":"not found"}를 반환합니다. 오타, 누락된 경로 값(rawUpdateId, matchId, teamId), /v1/ 접두사를 확인하세요.

모든 공개 경로는 GET만 지원합니다. 실제 존재하는 경로에 다른 메서드를 쓰면 405가 아니라, 알 수 없는 경로와 똑같이 404 {"error":"not found"}가 반환됩니다. 실용적인 참고을 참고하세요.

쿼리 파라미터가 잘못되었나요?

섹션 제목: “쿼리 파라미터가 잘못되었나요?”

인식하지 못하는 쿼리 파라미터 이름은 조용히 무시됩니다. 인식은 하지만 검증에 실패한 값은 문제를 설명하는 메시지와 함께 400이 됩니다(예: cursor is invalid, status must be one of ...). 각 경로의 파라미터 표는 엔드포인트에서 확인할 수 있습니다.

항상 {"error":"<message>"} 형태입니다. 흔한 원인: 잘못된 cursor, since, after, rawUpdateId, matchId; 빈 필터 값(team=, status=); /v1/matches에서 닫힌 열거형을 벗어난 status. 이 메시지는 사람이 읽기 위한 것이지 코드로 비교하기 위한 것이 아니므로, 정확한 문구보다는 엔드포인트 문서와 요청 형태를 비교해 보세요.

알 수 없는 경로, 알 수 없는 rawUpdateId/matchId/teamId, 또는 아직 아무것도 저장되지 않은 /v1/latest인 경우입니다.

요청이 너무 빈번하면 API 앞단의 네트워크 또는 요청 제한 계층에서 요청이 제한될 수 있습니다. 잠시 기다린 뒤 요청 빈도를 낮춰 다시 시도해 주세요. 지속적으로 발생하면 요청 시각, 엔드포인트, 요청 빈도와 함께 Developer Support로 문의해 주세요.

500 {"error":"internal error"}는 예기치 못한 오류가 있을 때 어느 경로에서든 나올 수 있습니다. 502 {"error":"video feed unavailable"}는 YouTube에 접속할 수 없고 캐시된 것도 없을 때 /v1/videos와 /v1/videos/latest에서만 나옵니다. 503은 수집기와 API 사이의 내부 경로에서만 나타나며, 공개된 /v1/* 경로에서는 절대 나오지 않습니다.

/v1/*, /openapi.json, /llms.txt의 공개 GET 응답은 Access-Control-Allow-Origin: *를 보냅니다. 이 경로들의 OPTIONS 프리플라이트는 GET과 OPTIONS만 허용하며, 커스텀 요청 헤더나 인증 정보는 허용하지 않습니다. 헤더를 추가하거나 다른 메서드를 쓰거나 인증 정보를 실어 보내는 요청은 설계상 프리플라이트에서 실패합니다. 실용적인 참고을 참고하세요.

/v1/live는 왜 빈 목록을 반환하나요?

섹션 제목: “/v1/live는 왜 빈 목록을 반환하나요?”

의도된 동작입니다. 이 경로는 지금 진행 중이라고 믿을 만한 경기만 보여줍니다(최신 갱신, 그럴듯한 분, 모순 없음). 결과가 비어 있다면 그 기준을 지금 충족하는 경기가 없다는 뜻이지 서비스 장애가 아닙니다. GET /v1/live를 참고하세요.

/v1/live는 보수적으로 필터링된, 화면에 바로 보여줘도 안전한 부분집합입니다. /v1/matches는 프로젝션이 아는 모든 파생 경기(오래되거나 과거의 것 포함)를 필터와 함께 검색하는 경로입니다. GET /v1/matches를 참고하세요.

cursor는 불투명한 값입니다. nextCursor가 준 값을, 그것을 만든 필터와 함께 그대로 돌려보내세요. 수정되었거나 직접 만든 커서는 400 cursor is invalid가 됩니다. 페이지네이션을 참고하세요.

GET /v1/teams가 표준화된 모든 id와 그 표시 이름, 별칭을 나열합니다. GET /v1/teams와 팀 식별자를 참고하세요.

matchId는 직접 만드는 것이 아니라 /v1/live나 /v1/matches가 반환하는 각 항목의 필드입니다. /v1/structured에는 이 식별자가 없습니다 - 별도의 파생 경기 계층에만 속합니다. 파생 경기를 참고하세요.

GET /v1/status가 수집기, 전달, 데이터 최신성, 처리, 미디어 상태를 보여줍니다. 상태를 참고하세요.

https://api.chizumulu.net/openapi.json (OpenAPI 3.1)입니다. 필드 이름, 열거값, 응답 모양의 기준이 되는 문서이며, 에이전트를 위한 기계 판독용 요약은 https://api.chizumulu.net/llms.txt에 있습니다.

minuteText는 원본에 적힌 그대로의 시계("45+2'")입니다. minute은 거기서 결정적으로 정규화한 값(기본 분에 적힌 추가 시간을 더함)이며, 해석 가능한 시계가 없으면 null입니다. 절대 추정값이 아닙니다. minuteText와 minute을 참고하세요.

지원하는 필터는 status, competitionCode, teamId, teamAlias, updatedSince이며 limit/cursor와 함께 씁니다. status는 닫힌 열거형이라 지원하지 않는 값은 400이고, 나머지는 아무것도 일치하지 않으면 빈 페이지를 줍니다. GET /v1/matches를 참고하세요.

잘 쓰던 연동이 갑자기 다르게 동작해요

섹션 제목: “잘 쓰던 연동이 갑자기 다르게 동작해요”

먼저 /openapi.json을 확인하세요. 거기 적힌 필드 이름과 모양이 기준이며, 새 필드는 통보 없이 추가될 수 있습니다(추가적 변경). processing.error, korean.text, error 메시지의 정확한 문구처럼 자유 텍스트 값은 안정적인 계약이 아니라서 바뀔 수 있습니다. /openapi.json으로 설명되지 않는 방식으로 모양 자체가 바뀌었다면 아래 메일로 알려주세요.

API는 수집기가 관찰한 것과 그 시점을 그대로 반영합니다. 상위 소스가 조용한 것은 정상이며 장애가 아닙니다. 문제라고 단정하기 전에 /v1/status에서 수집기·전달 상태를 확인하세요. 완전성과 시점을 참고하세요.

/v1/live는 지금 믿을 만하게 진행 중이지 않은 것을 의도적으로 제외합니다. 오래되었거나, 모호하거나, 끝난 경기는 삭제된 것이 아니라 그저 거기 나열되지 않을 뿐입니다. 대신 /v1/matches나 /v1/matches/{matchId}에서 찾으세요. GET /v1/live를 참고하세요.

파생 경기에 quality: conflict가 있어요

섹션 제목: “파생 경기에 quality: conflict가 있어요”

프로젝션이 어떤 observation을 붙이지 않고 따로 둔 경우입니다. 그 observation이 원래 붙었을 경기와 모순되기 때문입니다(예: 상태나 점수가 뒤로 갔음). 이는 의도된 동작입니다. 잘못 합치는 것을 놓치는 것보다 나쁘게 봅니다. 파생 경기를 참고하세요.

homeTeam/awayTeam은 항상 원본에 적힌 표기 그대로입니다. teamId는 같은 클럽의 알려진 표기들을 묶어줄 뿐입니다. 검토되지 않았거나 모호한 이름은 그냥 아직 id가 없는 것이며, 절대 추측하지 않습니다. 팀 식별자와 팀 별칭을 참고하세요.

아무것도 수정하지 않습니다. 원본의 실수(잘못된 점수, 이상한 상태)도 고치지 않고 적힌 그대로 반환합니다. API가 추론하지 않는 것을 참고하세요.

구조화 데이터와 파생 데이터의 차이

섹션 제목: “구조화 데이터와 파생 데이터의 차이”

/v1/structured는 observation 하나당 항목 하나로, 그 게시물 하나에만 충실합니다. /v1/live와 /v1/matches는 여러 observation을 하나의 matchId 아래 보수적으로 엮는 별도의 파생 프로젝션입니다. 두 계층은 각자 나타내는 바에 대해 둘 다 옳으면서도 서로 다른 말을 할 수 있습니다. Raw와 Structured와 파생 경기를 참고하세요.

  • 새 엔드포인트나 필터 요청. 원하는 엔드포인트/필터와 그 대상 필드를 알려주세요.
  • 추가 경기/팀 데이터 요청. 어떤 필드가 어느 경로에 없는지 알려주세요.
  • 연동 과정에서의 불편함 제보. 현재 모양이나 동작 때문에 연동이 필요 이상으로 어려운 지점을 알려주세요.
  • 활용 사례 설명. 무엇을 만들고 있고, 왜 지금 동작으로는 부족한지 알려주세요. 일반적인 설명보다 구체적인 요청/응답 예시가 더 도움이 됩니다.
  • 재현 가능한 API 버그. 문서나 OpenAPI대로라면 이래야 하는데 실제로는 다르게 동작하는 요청.
  • 문서 버그. 이 문서, /openapi.json, /llms.txt 중 잘못되었거나 빠졌거나 실제 API와 어긋나는 부분.
  • 잘못된 응답 모양. /openapi.json 대비 필드가 없거나, 더 있거나, 타입이 다른 경우.
  • 잘못된 데이터 동작. API 자신이 문서화한 규칙과 어긋나는 값을 반환한 경우(원본 소스 데이터 자체가 잘못된 경우는 다릅니다. 그 경우는 예상치 못한 동작을 참고하세요).
  • 포함할 정보. 정확한 요청(메서드, URL, 쿼리 파라미터), 전체 응답 본문, 발생 시각, 관련된 matchId/rawUpdateId/teamId — 진단 보고 형식을 참고하세요.
  • 연동. Chizumulu API 위에 제품이나 서비스를 만드는 경우.
  • 데이터·프로젝트 협업. 데이터, 프로젝트, 주변 도구를 함께 만들어가는 경우.
  • 연구·미디어·구단 관련 문의. 연구, 보도, 구단 쪽 목적으로 데이터를 쓰는 경우.
  • 포함할 내용: 소속 프로젝트나 조직, 생각하고 있는 범위, 데이터의 구체적인 활용 목적, 연락 방법.

위 항목에 해당하지 않는 문의라면, 필요한 내용을 최대한 명확하게 알려주세요.

문의 성격에 따라 두 가지 템플릿이 있습니다. 맞는 것을 골라 채운 뒤 dev-support@chizumulu.net으로 보내주세요.

API 호출 오류, 예상치 못한 동작, 버그 제보에 사용하세요.

Subject / 제목:
Category / 카테고리: (API request errors / Unexpected behavior / Report a bug)
Endpoint / 엔드포인트:
Request / 요청: (method, full URL, query parameters, headers if relevant)
Observed behavior / 실제 동작:
Expected behavior / 예상 동작:
Timestamp / 발생 시각: (UTC if possible)
Relevant IDs / 관련 ID:
matchId:
rawUpdateId:
teamId:
other:
Response or error / 응답 또는 오류: (full response body/status if available)
Reproduction steps / 재현 방법:
Additional context / 추가 정보:

기능 추가 및 개선 요청, 협업 요청, 기타에 사용하세요.

Subject / 제목:
Category / 카테고리: (Feature request / Collaboration / Other)
Project or organization / 프로젝트 또는 조직:
Description / 설명: (the use case, or what you'd like added/changed, and why)
Scope and intended use / 범위 및 활용 목적: (for collaboration inquiries)
Contact details / 연락처:
Additional context / 추가 정보: