마라톤 API 문서

시작하기

별도의 인증 없이 아래 경로로 GET 요청을 보내 테스트할 수 있습니다. 모든 응답은 UTF-8 JSON 형식입니다.

Base URL

/api/v1

Content-Type

application/json

마라톤 목록 조회

GET/api/v1/marathons

전체 대회 목록을 반환하며 쿼리 파라미터를 조합해 결과를 필터링할 수 있습니다.

Query parameters

이름	타입	필수	설명
`year`	`number`	선택	개최 연도. 예: 2026, 2027
`month`	`number`	선택	개최 월. 1부터 12까지 입력
`region`	`string`	선택	지역명 일부 또는 전체. 예: 서울, 경기
`distance`	`string`	선택	종목명. 예: FULL, HALF, 10KM
`query`	`string`	선택	대회명, 설명, 장소와 유형을 통합 검색

요청 예시

GET /api/v1/marathons?year=2027&month=3&region=서울

마라톤 상세 조회

GET/api/v1/marathons/{id}

대회의 id 또는 slug를 경로에 넣어 단일 데이터를 조회합니다.

요청 예시

GET /api/v1/marathons/2027-seoul-marathon

응답 구조

목록 응답은 성공 여부, 결과 개수, 데이터 배열과 요청 메타 정보를 포함합니다. 상세 응답은 data에 단일 객체를 반환합니다.

{
  "success": true,
  "count": 1,
  "data": [
    {
      "id": "2027-seoul-marathon",
      "slug": "2027-seoul-marathon",
      "name": "2027 서울 마라톤",
      "event": {
        "startDate": "2027-03-21",
        "endDate": "2027-03-21",
        "startTime": "07:30",
        "endTime": null
      },
      "registration": {
        "startDate": "2026-06-01",
        "endDate": "2026-06-03",
        "price": {
          "10KM": 100000,
          "FULL": 150000
        }
      },
      "location": {
        "country": "KR",
        "region": "서울",
        "venue": "광화문광장"
      }
    }
  ],
  "meta": {
    "requestedAt": "2026-07-30T00:00:00.000Z",
    "nextCursor": null
  }
}

데이터 타입

Marathon

마라톤 한 건을 표현하는 최상위 객체입니다.

이름	타입	설명
`id`	`string`	대회를 식별하는 고유 ID
`slug`	`string`	URL과 상세 조회에 사용할 수 있는 식별자
`name`	`string`	대회명
`description`	`string`	대회 소개
`info`	`MarathonInfo`	행사 유형, 규모, 공식 사이트 및 부가 정보
`event`	`EventSchedule`	대회 시작·종료 날짜와 시간
`registration`	`Registration`	접수 기간과 종목별 참가비
`location`	`Location`	지역, 장소, 주소 및 좌표
`hosts`	`Hosts`	주최·주관 기관과 연락처

MarathonInfo

대회의 기본 운영 정보

이름	타입	설명
`type`	`string \| null`	대회 유형
`scale`	`number \| null`	예상 또는 모집 인원
`site`	`string \| null`	공식 사이트 URL
`park`	`string \| null`	주차 안내
`souvenir`	`string \| null`	기념품 안내
`program`	`string \| null`	프로그램 안내
`memo`	`string \| null`	추가 안내 사항

EventSchedule

대회 개최 일정

이름	타입	설명
`startDate`	`string`	시작일, YYYY-MM-DD
`endDate`	`string`	종료일, YYYY-MM-DD
`startTime`	`string \| null`	시작 시간, HH:mm
`endTime`	`string \| null`	종료 시간, HH:mm

Registration

접수 일정과 참가비

이름	타입	설명
`startDate`	`string \| null`	접수 시작일
`endDate`	`string \| null`	접수 종료일
`startTime`	`string \| null`	접수 시작 시간
`endTime`	`string \| null`	접수 종료 시간
`price`	`Record<string, number>`	종목명을 키로 사용하는 참가비 객체

Location

대회 개최 장소

이름	타입	설명
`country`	`string`	ISO 국가 코드. 국내 데이터는 KR
`region`	`string`	시·도 단위 지역
`venue`	`string`	행사장 또는 출발 장소
`address`	`string \| null`	도로명 또는 지번 주소
`latitude`	`number \| null`	위도
`longitude`	`number \| null`	경도

Hosts

주최 기관과 문의 정보

이름	타입	설명
`organizer`	`string \| null`	주최 기관
`manager`	`string \| null`	주관 기관
`sponsor`	`string \| null`	후원 기관
`phone`	`string \| null`	문의 전화
`email`	`string \| null`	문의 이메일
`instagram`	`string \| null`	인스타그램 계정

오류 응답

요청한 대회를 찾을 수 없으면 HTTP 404와 함께 오류 객체를 반환합니다.

{
  "success": false,
  "error": {
    "code": "MARATHON_NOT_FOUND",
    "message": "해당 마라톤 대회를 찾을 수 없습니다."
  }
}

제공되는 일정과 참가비는 실제 내용과 다를 수 있습니다. 참가 신청 전 각 대회의 공식 사이트에서 최신 정보를 확인해 주세요.

직접 확인해 보세요

API Playground에서 조건을 선택하고 실제 응답을 확인할 수 있습니다.

Playground 열기