역 이름으로 역 검색

GET /search/station

요청 파라미터

파라미터 필수여부 설명

stationName

필수

검색할 역 이름 (최소 2자 이상)

요청 예시

GET /search/station?stationName=강남 HTTP/1.1
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

totalCount

Number

NotNull

검색된 역 총 개수

stations

Array

NotNull

역 목록

stations[].stationName

String

NotNull

역 이름

stations[].stationID

String

NotNull

역 ID

stations[].x

Number

NotNull

경도

stations[].y

Number

NotNull

위도

stations[].laneName

String

NotNull

노선 이름

stations[].lineColor

String

NotNull

노선 색상 (hex)

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 361

{
  "totalCount" : 2,
  "stations" : [ {
    "stationName" : "강남",
    "stationID" : "228",
    "x" : 127.0276,
    "y" : 37.4979,
    "laneName" : "2호선",
    "lineColor" : "#00A84D"
  }, {
    "stationName" : "강남구청",
    "stationID" : "734",
    "x" : 127.0435,
    "y" : 37.5172,
    "laneName" : "7호선",
    "lineColor" : "#747F00"
  } ]
}

추천 시간대 조회

GET /search/route

요청 파라미터

파라미터 필수여부 설명

departureStationId

필수

출발역 ID (숫자)

arrivalStationId

필수

도착역 ID (숫자)

searchDate

필수

조회 날짜 (yyyy-MM-dd)

startTime

필수

조회 시작 시간 (HH:mm)

endTime

필수

조회 종료 시간 (HH:mm)

요청 예시

GET /search/route?departureStationId=228&arrivalStationId=150&searchDate=2026-03-21&startTime=09:00&endTime=11:00 HTTP/1.1
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

departureStationId

String

NotNull

출발역 ID

arrivalStationId

String

NotNull

도착역 ID

departureStationName

String

NotNull

출발역 이름

arrivalStationName

String

NotNull

도착역 이름

travelDate

String

NotNull

이동 날짜

dayType

String

NotNull

요일 유형 (평일/주말)

message

String

NotNull

결과 메시지

recommendations

Array

NotNull

추천 시간대 목록

recommendations[].departureTime

String

NotNull

출발 시간 (HH:mm)

recommendations[].arrivalTime

String

NotNull

도착 시간 (HH:mm)

recommendations[].totalTime

Number

NotNull

총 소요 시간 (분)

recommendations[].transferCount

Number

NotNull

환승 횟수

recommendations[].congestionScore

Number

NotNull

혼잡도 점수

recommendations[].congestionLevel

String

NotNull

혼잡도 수준 (LOW/MEDIUM/HIGH)

recommendations[].stationCongestions

Array

NotNull

경유 역별 혼잡도 목록

recommendations[].stationCongestions[].stationId

String

NotNull

역 ID

recommendations[].stationCongestions[].stationName

String

NotNull

역 이름

recommendations[].stationCongestions[].lineName

String

NotNull

노선 이름

recommendations[].stationCongestions[].lineColor

String

NotNull

노선 색상

recommendations[].stationCongestions[].arrivalTime

String

NotNull

도착 시간 (HH:mm)

recommendations[].stationCongestions[].departureTime

String

NotNull

출발 시간 (HH:mm)

recommendations[].stationCongestions[].boardingCount

Number

NotNull

승차 인원

recommendations[].stationCongestions[].alightingCount

Number

NotNull

하차 인원

recommendations[].stationCongestions[].totalPassengers

Number

NotNull

총 승객 수

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 756

{
  "departureStationId" : "228",
  "arrivalStationId" : "150",
  "departureStationName" : "강남",
  "arrivalStationName" : "홍대입구",
  "travelDate" : "2026-03-21",
  "dayType" : "평일",
  "recommendations" : [ {
    "departureTime" : "09:00",
    "arrivalTime" : "09:45",
    "totalTime" : 45,
    "transferCount" : 1,
    "congestionScore" : 2500,
    "congestionLevel" : "LOW",
    "stationCongestions" : [ {
      "stationId" : "228",
      "stationName" : "강남",
      "lineName" : "2호선",
      "lineColor" : "#00A84D",
      "arrivalTime" : "09:00",
      "departureTime" : "09:02",
      "boardingCount" : 1200,
      "alightingCount" : 800,
      "totalPassengers" : 5000
    } ]
  } ],
  "message" : "추천 시간대입니다."
}

북마크 API

북마크 생성

POST /bookmarks

요청 필드

필드명 타입 필수여부 설명

name

String

필수

북마크 이름

departureStationId

String

필수

출발역 ID (숫자)

arrivalStationId

String

필수

도착역 ID (숫자)

startTime

String

필수

출발 시간 (HH:mm:ss)

endTime

String

필수

도착 시간 (HH:mm:ss)

요청 예시

POST /bookmarks HTTP/1.1
Content-Type: application/json
Content-Length: 156
Host: localhost:8080

{
  "name" : "강남 → 홍대입구",
  "departureStationId" : "228",
  "arrivalStationId" : "150",
  "startTime" : "09:00:00",
  "endTime" : "10:00:00"
}

응답 필드

필드명 타입 Null 여부 설명

id

Number

NotNull

북마크 ID

name

String

NotNull

북마크 이름

departureStationId

String

NotNull

출발역 ID

arrivalStationId

String

NotNull

도착역 ID

departureStationName

String

NotNull

출발역 이름

arrivalStationName

String

NotNull

도착역 이름

departureLineName

String

NotNull

출발역 노선 이름

departureLineColor

String

NotNull

출발역 노선 색상

arrivalLineName

String

NotNull

도착역 노선 이름

arrivalLineColor

String

NotNull

도착역 노선 색상

startTime

String

NotNull

출발 시간 (HH:mm)

endTime

String

NotNull

도착 시간 (HH:mm)

displayOrder

Number

NotNull

정렬 순서

createdAt

String

NotNull

생성 일시

updatedAt

String

NotNull

수정 일시

응답 예시

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 478

{
  "id" : 1,
  "name" : "강남 → 홍대입구",
  "departureStationId" : "228",
  "arrivalStationId" : "150",
  "departureStationName" : "강남",
  "arrivalStationName" : "홍대입구",
  "departureLineName" : "2호선",
  "departureLineColor" : "#00A84D",
  "arrivalLineName" : "2호선",
  "arrivalLineColor" : "#00A84D",
  "startTime" : "09:00",
  "endTime" : "10:00",
  "displayOrder" : 1,
  "createdAt" : "2026-03-21T09:00:00",
  "updatedAt" : "2026-03-21T09:00:00"
}

북마크 수정

PATCH /bookmarks/{id}

경로 파라미터

파라미터 필수여부 설명

id

필수

수정할 북마크 ID

요청 필드

필드명 타입 필수여부 설명

name

String

선택

변경할 북마크 이름

departureStationId

String

선택

변경할 출발역 ID

arrivalStationId

String

선택

변경할 도착역 ID

startTime

String

선택

변경할 출발 시간

endTime

String

선택

변경할 도착 시간

요청 예시

PATCH /bookmarks/1 HTTP/1.1
Content-Type: application/json
Content-Length: 150
Host: localhost:8080

{
  "name" : "강남 → 신촌",
  "departureStationId" : "228",
  "arrivalStationId" : "240",
  "startTime" : "09:00:00",
  "endTime" : "10:00:00"
}

응답 필드

필드명 타입 Null 여부 설명

id

Number

NotNull

북마크 ID

name

String

NotNull

북마크 이름

departureStationId

String

NotNull

출발역 ID

arrivalStationId

String

NotNull

도착역 ID

departureStationName

String

NotNull

출발역 이름

arrivalStationName

String

NotNull

도착역 이름

departureLineName

String

NotNull

출발역 노선 이름

departureLineColor

String

NotNull

출발역 노선 색상

arrivalLineName

String

NotNull

도착역 노선 이름

arrivalLineColor

String

NotNull

도착역 노선 색상

startTime

String

NotNull

출발 시간 (HH:mm)

endTime

String

NotNull

도착 시간 (HH:mm)

displayOrder

Number

NotNull

정렬 순서

createdAt

String

NotNull

생성 일시

updatedAt

String

NotNull

수정 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 466

{
  "id" : 1,
  "name" : "강남 → 신촌",
  "departureStationId" : "228",
  "arrivalStationId" : "240",
  "departureStationName" : "강남",
  "arrivalStationName" : "신촌",
  "departureLineName" : "2호선",
  "departureLineColor" : "#00A84D",
  "arrivalLineName" : "2호선",
  "arrivalLineColor" : "#00A84D",
  "startTime" : "09:00",
  "endTime" : "10:00",
  "displayOrder" : 1,
  "createdAt" : "2026-03-21T09:00:00",
  "updatedAt" : "2026-03-21T10:00:00"
}

북마크 순서 변경

PUT /bookmarks/reorder

요청 필드

필드명 타입 필수여부 설명

items

Array

필수

순서 변경 항목 목록

items[].bookmarkId

Number

필수

북마크 ID

items[].newDisplayOrder

Number

필수

변경할 순서 (0부터 시작)

요청 예시

PUT /bookmarks/reorder HTTP/1.1
Content-Type: application/json
Content-Length: 128
Host: localhost:8080

{
  "items" : [ {
    "bookmarkId" : 1,
    "newDisplayOrder" : 0
  }, {
    "bookmarkId" : 2,
    "newDisplayOrder" : 1
  } ]
}

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 34

"Bookmarks reordered successfully"

북마크 목록 조회

GET /bookmarks

응답 필드

필드명 타입 Null 여부 설명

[].id

Number

NotNull

북마크 ID

[].name

String

NotNull

북마크 이름

[].departureStationId

String

NotNull

출발역 ID

[].arrivalStationId

String

NotNull

도착역 ID

[].departureStationName

String

NotNull

출발역 이름

[].arrivalStationName

String

NotNull

도착역 이름

[].departureLineName

String

NotNull

출발역 노선 이름

[].departureLineColor

String

NotNull

출발역 노선 색상

[].arrivalLineName

String

NotNull

도착역 노선 이름

[].arrivalLineColor

String

NotNull

도착역 노선 색상

[].startTime

String

NotNull

출발 시간 (HH:mm)

[].endTime

String

NotNull

도착 시간 (HH:mm)

[].displayOrder

Number

NotNull

정렬 순서

[].createdAt

String

NotNull

생성 일시

[].updatedAt

String

NotNull

수정 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 482

[ {
  "id" : 1,
  "name" : "강남 → 홍대입구",
  "departureStationId" : "228",
  "arrivalStationId" : "150",
  "departureStationName" : "강남",
  "arrivalStationName" : "홍대입구",
  "departureLineName" : "2호선",
  "departureLineColor" : "#00A84D",
  "arrivalLineName" : "2호선",
  "arrivalLineColor" : "#00A84D",
  "startTime" : "09:00",
  "endTime" : "10:00",
  "displayOrder" : 1,
  "createdAt" : "2026-03-21T09:00:00",
  "updatedAt" : "2026-03-21T09:00:00"
} ]

북마크 단건 조회

GET /bookmarks/{id}

경로 파라미터

파라미터 필수여부 설명

id

필수

조회할 북마크 ID

응답 필드

필드명 타입 Null 여부 설명

id

Number

NotNull

북마크 ID

name

String

NotNull

북마크 이름

departureStationId

String

NotNull

출발역 ID

arrivalStationId

String

NotNull

도착역 ID

departureStationName

String

NotNull

출발역 이름

arrivalStationName

String

NotNull

도착역 이름

departureLineName

String

NotNull

출발역 노선 이름

departureLineColor

String

NotNull

출발역 노선 색상

arrivalLineName

String

NotNull

도착역 노선 이름

arrivalLineColor

String

NotNull

도착역 노선 색상

startTime

String

NotNull

출발 시간 (HH:mm)

endTime

String

NotNull

도착 시간 (HH:mm)

displayOrder

Number

NotNull

정렬 순서

createdAt

String

NotNull

생성 일시

updatedAt

String

NotNull

수정 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 478

{
  "id" : 1,
  "name" : "강남 → 홍대입구",
  "departureStationId" : "228",
  "arrivalStationId" : "150",
  "departureStationName" : "강남",
  "arrivalStationName" : "홍대입구",
  "departureLineName" : "2호선",
  "departureLineColor" : "#00A84D",
  "arrivalLineName" : "2호선",
  "arrivalLineColor" : "#00A84D",
  "startTime" : "09:00",
  "endTime" : "10:00",
  "displayOrder" : 1,
  "createdAt" : "2026-03-21T09:00:00",
  "updatedAt" : "2026-03-21T09:00:00"
}

전체 북마크 삭제

DELETE /bookmarks

요청 예시

DELETE /bookmarks HTTP/1.1
Host: localhost:8080

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 36

"All bookmarks deleted successfully"

북마크 단건 삭제

DELETE /bookmarks/{id}

경로 파라미터

파라미터 필수여부 설명

id

필수

삭제할 북마크 ID

요청 예시

DELETE /bookmarks/1 HTTP/1.1
Host: localhost:8080

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 31

"Bookmark deleted successfully"

인증 API

소셜 로그인

POST /auth/login

요청 필드

필드명 타입 필수여부 설명

providerType

String

필수

소셜 로그인 제공자 (KAKAO, GOOGLE)

nickname

String

선택

사용자 닉네임

authorizationCode

String

필수

소셜 인가 코드

redirectUri

String

선택

리다이렉트 URI

요청 예시

POST /auth/login HTTP/1.1
Content-Type: application/json
Content-Length: 153
Host: localhost:8080

{
  "providerType" : "KAKAO",
  "nickname" : "홍길동",
  "authorizationCode" : "auth-code-example",
  "redirectUri" : "https://example.com/callback"
}

응답 필드

필드명 타입 Null 여부 설명

accessToken

String

NotNull

액세스 토큰

refreshToken

String

NotNull

리프레시 토큰

tokenType

String

NotNull

토큰 타입 (Bearer)

expiresIn

Number

NotNull

액세스 토큰 만료 시간 (초)

user.id

Number

NotNull

사용자 ID

user.nickname

String

NotNull

사용자 닉네임

user.role

String

NotNull

사용자 권한

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 218

{
  "accessToken" : "access-token-example",
  "refreshToken" : "refresh-token-example",
  "tokenType" : "Bearer",
  "expiresIn" : 3600,
  "user" : {
    "id" : 1,
    "nickname" : "홍길동",
    "role" : "USER"
  }
}

토큰 갱신

POST /auth/refresh

요청 필드

필드명 타입 필수여부 설명

refreshToken

String

필수

갱신에 사용할 리프레시 토큰

요청 예시

POST /auth/refresh HTTP/1.1
Content-Type: application/json
Content-Length: 46
Host: localhost:8080

{
  "refreshToken" : "refresh-token-example"
}

응답 필드

필드명 타입 Null 여부 설명

accessToken

String

NotNull

새로 발급된 액세스 토큰

refreshToken

String

NotNull

새로 발급된 리프레시 토큰

tokenType

String

NotNull

토큰 타입 (Bearer)

expiresIn

Number

NotNull

액세스 토큰 만료 시간 (초)

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 144

{
  "accessToken" : "new-access-token-example",
  "refreshToken" : "new-refresh-token-example",
  "tokenType" : "Bearer",
  "expiresIn" : 3600
}

로그아웃

POST /auth/logout

요청 예시

POST /auth/logout HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 37

{
  "message" : "Logout successful"
}

사용자 API

현재 사용자 정보 조회

GET /user/me

요청 예시

GET /user/me HTTP/1.1
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

id

Number

NotNull

사용자 ID

nickname

String

NotNull

사용자 닉네임

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 42

{
  "id" : 1,
  "nickname" : "홍길동"
}

관리자 데이터 로드 API

지하철 마스터 데이터 로드

POST /admin/data-load/subway/master

요청 예시

POST /admin/data-load/subway/master HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

응답 필드

필드명 타입 Null 여부 설명

success

Boolean

NotNull

처리 성공 여부

dataCategory

String

NotNull

데이터 카테고리

totalCount

Number

NotNull

처리된 데이터 수

message

String

NotNull

처리 결과 메시지

loadedAt

String

NotNull

처리 완료 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 156

{
  "success" : true,
  "dataCategory" : "subwayMaster",
  "totalCount" : 300,
  "message" : "300 Loading completed",
  "loadedAt" : "2026-03-21T09:00:00"
}

지하철 통계 데이터 로드

POST /admin/data-load/subway/statistics

요청 파라미터

파라미터 필수여부 설명

yearMonth

필수

조회 연월 (yyyyMM 형식, 6자리)

요청 예시

POST /admin/data-load/subway/statistics?yearMonth=202603 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

success

Boolean

NotNull

처리 성공 여부

dataCategory

String

NotNull

데이터 카테고리

totalCount

Number

NotNull

처리된 데이터 수

message

String

NotNull

처리 결과 메시지

loadedAt

String

NotNull

처리 완료 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 162

{
  "success" : true,
  "dataCategory" : "subwayStatistics",
  "totalCount" : 1500,
  "message" : "1500 Loading completed",
  "loadedAt" : "2026-03-21T09:00:00"
}

전체 데이터 로드

POST /admin/data-load/all

요청 파라미터

파라미터 필수여부 설명

yearMonth

필수

조회 연월 (yyyyMM 형식, 6자리)

요청 예시

POST /admin/data-load/all?yearMonth=202603 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

subwayMaster.success

Boolean

NotNull

마스터 데이터 처리 성공 여부

subwayMaster.dataCategory

String

NotNull

마스터 데이터 카테고리

subwayMaster.totalCount

Number

NotNull

마스터 데이터 처리 수

subwayMaster.message

String

NotNull

마스터 데이터 처리 메시지

subwayMaster.loadedAt

String

NotNull

마스터 데이터 처리 완료 일시

subwayStatistics.success

Boolean

NotNull

통계 데이터 처리 성공 여부

subwayStatistics.dataCategory

String

NotNull

통계 데이터 카테고리

subwayStatistics.totalCount

Number

NotNull

통계 데이터 처리 수

subwayStatistics.message

String

NotNull

통계 데이터 처리 메시지

subwayStatistics.loadedAt

String

NotNull

통계 데이터 처리 완료 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 390

{
  "subwayMaster" : {
    "success" : true,
    "dataCategory" : "subwayMaster",
    "totalCount" : 300,
    "message" : "300 Loading completed",
    "loadedAt" : "2026-03-21T09:00:00"
  },
  "subwayStatistics" : {
    "success" : true,
    "dataCategory" : "subwayStatistics",
    "totalCount" : 1500,
    "message" : "1500 Loading completed",
    "loadedAt" : "2026-03-21T09:00:00"
  }
}

지하철 통계 데이터 삭제

DELETE /admin/data-load/subway/statistics

요청 파라미터

파라미터 필수여부 설명

yearMonth

필수

삭제할 연월 (yyyyMM 형식, 6자리)

요청 예시

DELETE /admin/data-load/subway/statistics?yearMonth=202603 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

success

Boolean

NotNull

처리 성공 여부

dataCategory

String

NotNull

데이터 카테고리

totalCount

Number

NotNull

삭제된 데이터 수

message

String

NotNull

처리 결과 메시지

loadedAt

String

NotNull

처리 완료 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 162

{
  "success" : true,
  "dataCategory" : "subwayStatistics",
  "totalCount" : 1500,
  "message" : "1500 Loading completed",
  "loadedAt" : "2026-03-21T09:00:00"
}

전체 열차 스케줄 로드

POST /admin/data-load/train-schedule/all

요청 예시

POST /admin/data-load/train-schedule/all HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

응답 필드

필드명 타입 Null 여부 설명

평일.success

Boolean

NotNull

평일 스케줄 처리 성공 여부

평일.dataCategory

String

NotNull

평일 스케줄 카테고리

평일.totalCount

Number

NotNull

평일 스케줄 처리 수

평일.message

String

NotNull

평일 스케줄 처리 메시지

평일.loadedAt

String

NotNull

평일 스케줄 처리 완료 일시

주말.success

Boolean

NotNull

주말 스케줄 처리 성공 여부

주말.dataCategory

String

NotNull

주말 스케줄 카테고리

주말.totalCount

Number

NotNull

주말 스케줄 처리 수

주말.message

String

NotNull

주말 스케줄 처리 메시지

주말.loadedAt

String

NotNull

주말 스케줄 처리 완료 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 370

{
  "평일" : {
    "success" : true,
    "dataCategory" : "trainSchedule",
    "totalCount" : 500,
    "message" : "500 Loading completed",
    "loadedAt" : "2026-03-21T09:00:00"
  },
  "주말" : {
    "success" : true,
    "dataCategory" : "trainSchedule",
    "totalCount" : 500,
    "message" : "500 Loading completed",
    "loadedAt" : "2026-03-21T09:00:00"
  }
}

전체 열차 스케줄 삭제

DELETE /admin/data-load/train-schedule/all

요청 예시

DELETE /admin/data-load/train-schedule/all HTTP/1.1
Host: localhost:8080

응답 필드

필드명 타입 Null 여부 설명

success

Boolean

NotNull

처리 성공 여부

dataCategory

String

NotNull

데이터 카테고리

totalCount

Number

NotNull

삭제된 데이터 수

message

String

NotNull

처리 결과 메시지

loadedAt

String

NotNull

처리 완료 일시

응답 예시

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 159

{
  "success" : true,
  "dataCategory" : "trainSchedule",
  "totalCount" : 1000,
  "message" : "1000 Loading completed",
  "loadedAt" : "2026-03-21T09:00:00"
}