다크 모드
대중교통 통합 길찾기
출발지에서 도착지까지 도보·지하철·버스를 결합한 최적 경로 정보를 제공합니다. 노선 정보, 정차역, 환승 안내, 하차문 정보 등 사용자가 경로를 이용하는 데 필요한 상세 정보를 함께 반환합니다.
DANGER
해당 API를 사용하기 위해서는 REST API 키 값이 반드시 필요합니다. 시작하기에서 앱 등록과 REST API 키 값 확인 방법을 참고하세요.
Request
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식
| Method | URL |
|---|---|
GET | https://apis-navi.kakaomobility.com/affiliate/publictransit/v1/multimodal/directions |
요청 헤더(Header)
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키 |
| Content-Type | application/json |
요청 코드 예제
bash
curl -X 'GET' \
'https://apis-navi.kakaomobility.com/affiliate/publictransit/v1/multimodal/directions?start=127.111181,37.394717&goal=127.027819,37.498185&date=-1&hhmmss=-1&day_type=Weekday&route_type=All' \
-H 'accept: application/json' \
-H "Authorization: KakaoAK ${REST_API_KEY}" // 카카오디벨로퍼스에서 발급 받은 API 키 값요청에 대한 파라미터는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
start | String | 출발지 좌표(WGS84) 경도, 위도 순서로 ${lng},${lat} 형식으로 요청 (예: 127.111181,37.394717) | 필수 |
goal | String | 도착지 좌표(WGS84) 경도, 위도 순서로 ${lng},${lat} 형식으로 요청 (예: 127.027819,37.498185) | 필수 |
date | Integer | 날짜 YYYYMMDD 형식 (예: 20250531)(기본값: -1, 미지정 시 현재 날짜 기준) | 선택 |
hhmmss | Integer | 출발 시간 시/분/초를 이어 붙인 정수 형식 (예: 153000 = 15:30:00)(기본값: -1, 미지정 시 현재 시간 기준) | 선택 |
day_type | String | 요일 다음 중 하나: • Weekday: 평일• Saturday: 토요일• Holiday: 공휴일(기본값: Weekday) | 선택 |
route_type | String | 이용할 노선 Type 조합 다음 중 하나: • All: 전체• Subway: 지하철• Bus: 버스(기본값: All) | 선택 |
Response
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 응답 본문은 JSON 포맷으로 전달합니다.
응답 코드 예제
json
{
"trans_id": "019fee6c0b52790d8e0622a0633d4616",
"result_code": 0,
"result_message": "성공",
"journeys": [
{
"summary": {
"score": 1144,
"distance": 14371,
"total_time": 1089,
"moving_time": 1089,
"waiting_time": 0,
"walking_time": 278,
"transfer_count": 0,
"moving_stop_count": 4,
"transport_type": [
"Subway"
]
},
"sections": [
{
"departure_stop": {
"stop_name": "출발지",
"x": 123.74176686017732,
"y": 32.522050568904874,
"arrival_time": -1,
"departure_time": 37703,
"boardable": true
},
"arrival_stop": {
"stop_id": "SS0528",
"stop_name": "판교",
"x": 127.11118924971723,
"y": 37.39476903466787,
"arrival_time": 37831,
"departure_time": -1,
"boardable": true
},
"route": {
"route_short_name": "Walk",
"route_full_name": "Walk"
},
"path": [
127.11116740884869,
37.39470579515886,
127.11117177090183,
37.39433638666676,
127.11099108700814,
37.39433502838185,
127.1109930024199,
37.3941728490443,
127.11123025590503,
37.39416562176231,
127.11123025590503,
37.39416562176231
],
"distance": 96,
"time": 128,
"waiting_time": 0,
"first_trip": false,
"last_trip": false,
"walking_transfer_section": false
},
{
"departure_stop": {
"stop_id": "SS0528",
"stop_name": "판교",
"x": 127.11118924971723,
"y": 37.39476903466787,
"arrival_time": 37796,
"departure_time": 37831,
"boardable": true
},
"arrival_stop": {
"stop_id": "SS0524",
"stop_name": "강남",
"x": 127.02818282789538,
"y": 37.49677408896288,
"arrival_time": 38642,
"departure_time": 38677,
"boardable": true
},
"passing_stops": [
{
"stop_id": "SS0527",
"stop_name": "청계산입구",
"x": 127.05466778928293,
"y": 37.44837676589618,
"arrival_time": -1,
"departure_time": -1,
"boardable": true
},
{
"stop_id": "SS0526",
"stop_name": "양재시민의숲",
"x": 127.03846500348334,
"y": 37.47013284411478,
"arrival_time": -1,
"departure_time": -1,
"boardable": true
},
{
"stop_id": "SS0525",
"stop_name": "양재",
"x": 127.03515087026057,
"y": 37.48345952178811,
"arrival_time": -1,
"departure_time": -1,
"boardable": true
}
],
"route": {
"route_id": "SBD01",
"route_short_name": "신분당",
"route_full_name": "수도권 신분당선",
"vehicle_type_name": "GENERAL",
"branch_id": "SHINBUNDANG",
"branch_direction": "UP",
"train_type": "GENERAL",
"last_stop_id_of_trip": "SS0534",
"last_stop_name_of_trip": "신사"
},
"path": [
127.11118924971723,
37.39476903466787,
127.11120142439634,
37.39660732146608,
127.11120496545158,
37.398220273876824,
127.11103871230895,
37.402733411804164,
127.11098768179471,
37.40322861938216,
127.11092407891427,
37.40383186134391,
127.11060891283441,
37.40469452284903,
127.11028532148646,
37.40531382980909,
127.11001095244829,
37.405591097990985,
127.10888512120738,
37.40623139174164,
127.1061466587737,
37.407598374688206,
127.1028964958957,
37.40924074460957,
127.10142265885608,
37.41063522673524,
127.09967767828458,
37.41202762536604,
127.09842730565474,
37.41267588007562,
127.09662050814738,
37.413563160538374,
127.08562091854125,
37.419795109072396,
127.07408283932051,
37.42831952660031,
127.06699203730055,
37.43430092706447,
127.06163736473371,
37.43961988614554,
127.05882128249235,
37.443409003874784,
127.0562495808895,
37.44661431005451,
127.05466778928293,
37.44837676589618,
127.05134246539868,
37.45216162151642,
127.04356349556487,
37.460379687659426,
127.0415233691119,
37.46257976975773,
127.03955555123449,
37.464419978461436,
127.03884495810996,
37.46606314217026,
127.03882015888499,
37.467117181430055,
127.0385263749596,
37.468871859212996,
127.03844539633917,
37.46989840892825,
127.03851759366886,
37.471322671285954,
127.03858333582836,
37.47236843565812,
127.03866384582449,
37.47314400207878,
127.0386566911291,
37.47370260084017,
127.0386562295291,
37.47373863946807,
127.03865137764697,
37.47500008327963,
127.03866683182152,
37.475558865817966,
127.03866648560202,
37.47558589478043,
127.03867408667122,
37.47764037150194,
127.03867166296128,
37.47782957416983,
127.03866889297933,
37.478045805782635,
127.03866843131279,
37.478081844383965,
127.03865608744682,
37.47816283925346,
127.03865493325867,
37.478252935754256,
127.03862955286756,
37.4784689833797,
127.03860521115737,
37.478603944146364,
127.03859298255335,
37.478675929350814,
127.03854510680385,
37.478882783305764,
127.03852122654466,
37.47898170544763,
127.03849723077832,
37.47908963723046,
127.03843804919346,
37.47929639911899,
127.03841451500801,
37.479368292285635,
127.03836756195642,
37.47950306895304,
127.03828576897449,
37.47970964671112,
127.03822739462353,
37.479853340932664,
127.03820409101107,
37.47990721475285,
127.03809980179946,
37.48010459864674,
127.0378098883925,
37.48066990490002,
127.03778681528276,
37.480705759334896,
127.03771748027724,
37.48082233225297,
127.03769440707525,
37.480858186667625,
127.0376367239726,
37.48094782268226,
127.03755608295715,
37.48106430340717,
127.03747555726143,
37.48117177442888,
127.03745259940946,
37.481198619148785,
127.03738361017,
37.481288162921615,
127.03729177838677,
37.48139554169499,
127.03718864072734,
37.48150282826133,
127.03710846088242,
37.48158327008843,
127.03708550277156,
37.48161011473155,
127.03626131424774,
37.482396325936556,
127.03604372713585,
37.48261080481651,
127.03524247596245,
37.48337016406037,
127.03515087026057,
37.48345952178811,
127.03444109256985,
37.48413852717639,
127.03405065677026,
37.48460388566319,
127.03402769663018,
37.48463072967029,
127.03400462046939,
37.48466658330041,
127.03398166029336,
37.48469342729777,
127.03395858409081,
37.48472928091794,
127.03393562387883,
37.48475612490557,
127.03392385373077,
37.484792070966186,
127.03390077746948,
37.484827924573636,
127.0337843515385,
37.48508827917539,
127.03372642836315,
37.4851959323591,
127.03358704066817,
37.48548313066824,
127.03336630256422,
37.485940864137234,
127.03309905904817,
37.48649733285104,
127.03292470197462,
37.48686533924082,
127.03269206826491,
37.4873680267812,
127.03266910677665,
37.48739487049315,
127.03241350789986,
37.487924401094865,
127.03213494332606,
37.48848077464184,
127.03189052728348,
37.489019406155926,
127.03163480084956,
37.48955794438808,
127.03137930335487,
37.490078462741515,
127.03067037267843,
37.491559391331904,
127.02996141345375,
37.4930403149068,
127.02918259777407,
37.494673839137725,
127.02818282789538,
37.49677408896288
],
"alighting": {
"door_direction": "LEFT",
"fast_alighting_door_list": "6-4,3-2"
},
"distance": 14172,
"time": 811,
"waiting_time": 0,
"first_trip": false,
"last_trip": false,
"walking_transfer_section": false
},
{
"departure_stop": {
"stop_id": "SS0524",
"stop_name": "강남",
"x": 127.02818282789538,
"y": 37.49677408896288,
"arrival_time": -1,
"departure_time": 38642,
"boardable": true
},
"arrival_stop": {
"stop_name": "목적지",
"x": 123.74176686017732,
"y": 32.522050568904874,
"arrival_time": 38792,
"departure_time": -1,
"boardable": true
},
"route": {
"route_short_name": "Walk",
"route_full_name": "Walk"
},
"path": [
127.02786116383426,
37.49803291977578,
127.02839065877372,
37.498190455363655,
127.02829797581137,
37.49836089351186,
127.02859081989868,
37.49845340750207,
127.02856773676302,
37.49848925989071,
127.0285564286201,
37.49848916689907
],
"distance": 103,
"time": 150,
"waiting_time": 0,
"first_trip": false,
"last_trip": false,
"walking_transfer_section": false
}
]
},
{
"summary": {
"score": 2007,
"distance": 16836,
"total_time": 1826,
"moving_time": 1826,
"waiting_time": 0,
"walking_time": 905,
"transfer_count": 0,
"moving_stop_count": 8,
"transport_type": [
"Bus"
]
},
"sections": [
{
"departure_stop": {
"stop_name": "출발지",
"x": 123.74176686017732,
"y": 32.522050568904874,
"arrival_time": -1,
"departure_time": 87435,
"boardable": true
},
"arrival_stop": {
"stop_id": "KS323703",
"stop_name": "판교역.낙생육교.현대백화점",
"x": 127.11111015559987,
"y": 37.391903016956675,
"arrival_time": 87798,
"departure_time": -1,
"boardable": true
},
"route": {
"route_short_name": "Walk",
"route_full_name": "Walk"
},
"path": [
127.11116730245614,
37.39471480512179,
127.11117177090183,
37.39433638666676,
127.11117772869953,
37.39383182868806,
127.11119295763818,
37.39349854488041,
127.11114778716608,
37.3934982053496,
127.11114938301404,
37.39336305587693,
127.11114970218237,
37.393336025982016,
127.11107065402831,
37.39333543176507,
127.11107427156098,
37.39302909295372,
127.1110753355308,
37.39293899330021,
127.11107576111735,
37.39290295343844,
127.11107810183006,
37.392704734194545,
127.11107969775742,
37.392569584706166,
127.11106957563376,
37.39247039018952,
127.11107000121592,
37.39243435032492,
127.11107074598286,
37.392371280561306,
127.11107180993157,
37.3922811808978,
127.11107308666381,
37.39217306129972,
127.1110762784645,
37.39190276229568,
127.11109886322137,
37.391902932070764
],
"distance": 326,
"time": 363,
"waiting_time": 0,
"first_trip": false,
"last_trip": false,
"walking_transfer_section": false
},
{
"departure_stop": {
"stop_id": "KS323703",
"stop_name": "판교역.낙생육교.현대백화점",
"x": 127.11111015559987,
"y": 37.391903016956675,
"arrival_time": 87798,
"departure_time": 87798,
"boardable": true
},
"arrival_stop": {
"stop_id": "KS332988",
"stop_name": "신논현역.유화빌딩",
"x": 127.02556344158106,
"y": 37.50166326057349,
"arrival_time": 88719,
"departure_time": 88719,
"boardable": true
},
"passing_stops": [
{
"stop_id": "KS333699",
"stop_name": "판교TG(미정차)",
"x": 127.10315666018009,
"y": 37.395942857821375,
"arrival_time": -1,
"departure_time": -1,
"boardable": false
},
{
"stop_id": "KS318288",
"stop_name": "금토JC(미정차)",
"x": 127.08531433082632,
"y": 37.41527837084757,
"arrival_time": -1,
"departure_time": -1,
"boardable": false
},
{
"stop_id": "KS320642",
"stop_name": "서울진입(미정차)",
"x": 127.06657958333804,
"y": 37.43384713699376,
"arrival_time": -1,
"departure_time": -1,
"boardable": false
},
{
"stop_id": "KS336691",
"stop_name": "청계산입구역(미정차)",
"x": 127.05419327409582,
"y": 37.44836395880759,
"arrival_time": -1,
"departure_time": -1,
"boardable": false
},
{
"stop_id": "KS327155",
"stop_name": "양재IC(미정차)",
"x": 127.04044050949763,
"y": 37.46328282018592,
"arrival_time": -1,
"departure_time": -1,
"boardable": false
},
{
"stop_id": "KS326376",
"stop_name": "서초IC(미정차)",
"x": 127.02632436919144,
"y": 37.4831258037927,
"arrival_time": -1,
"departure_time": -1,
"boardable": false
},
{
"stop_id": "KS319915",
"stop_name": "KCC사옥",
"x": 127.02027526893939,
"y": 37.503025164060396,
"arrival_time": -1,
"departure_time": -1,
"boardable": true
}
],
"route": {
"route_id": "KB304122",
"route_short_name": "1101N",
"route_full_name": "1101N",
"vehicle_type_name": "DIRECT",
"last_stop_id_of_trip": "KS331081",
"last_stop_name_of_trip": "단국대.치과병원"
},
"alternative_routes": [
{
"route_id": "KB304699",
"route_short_name": "1101",
"route_full_name": "1101",
"vehicle_type_name": "DIRECT"
}
/// 내용 생략
{
"departure_stop": {
"stop_id": "SS0445",
"stop_name": "신논현",
"x": 127.02548864689048,
"y": 37.50480732294818,
"arrival_time": -1,
"departure_time": 42070,
"boardable": true
},
"arrival_stop": {
"stop_name": "목적지",
"x": 123.74176686017732,
"y": 32.522050568904874,
"arrival_time": 42747,
"departure_time": -1,
"boardable": true
},
"route": {
"route_short_name": "Walk",
"route_full_name": "Walk"
},
"path": [
127.02786116383426,
37.49803291977578,
127.02771474298407,
37.497986661980434,
127.02761343771817,
37.49794978592996,
127.02740393315295,
37.49840759935346,
127.02732232210717,
37.49859614897418,
127.02752505101647,
37.49866089191224,
127.0274669911619,
37.49877755109666,
127.02753460657807,
37.49879612883737,
127.0274301452786,
37.49900251151141,
127.02713972515906,
37.499594816390726,
127.02697673243563,
37.499953895897576,
127.02675544194577,
37.50044765307321,
127.02646442578869,
37.5010850039087,
127.02634841569038,
37.50130931142545,
127.02616279806358,
37.501668203177346,
127.0257555239647,
37.502547878278264,
127.02568568115237,
37.50270048147215,
127.02539511525742,
37.50330179087496
],
"distance": 675,
"time": 677,
"waiting_time": 0,
"first_trip": false,
"last_trip": false,
"walking_transfer_section": false
}
]
}
]
}요청 응답에 대한 객체 정보는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
trans_id | String | 트랜잭션 ID | 필수 |
result_code | Int | 경로 탐색 결과 코드 | 필수 |
result_message | String | 결과 메시지 | 필수 |
journeys | Object[] | 경로 목록 탐색 실패 시 미제공 | 조건부 필수 |
summary | Object | 요약 정보 | 필수 |
score | Int | 경로 점수 (추천 경로를 위한 스코어) | 필수 |
distance | Int | 전체 이동 거리 (단위: m) | 필수 |
total_time | Int | 전체 소요 시간 [이동 + 대기] (단위: 초) | 필수 |
moving_time | Int | 실제 이동에 소요된 시간 [대기 시간 제외] (단위: 초) 출발지 → 첫 정류장(역) 도보 + 노선 이동 + 환승 도보 + 마지막 정류장(역) → 목적지 도보의 합산 | 필수 |
waiting_time | Int | 전체 대기 시간 [첫 번째 탑승 대기 제외] (단위: 초) | 필수 |
walking_time | Int | 전체 도보 시간. 출발지·목적지·환승 구간을 포함한 도보 시간의 합산 (단위: 초) | 필수 |
transfer_count | Int | 환승 횟수 | 필수 |
moving_stop_count | Int | 이동한 정류장(역) 개수 | 필수 |
transport_type | String[] | 이용 교통수단 목록 (Walk, Subway, Bus) | 필수 |
sections | Object[] | 구간 정보 | 필수 |
departure_stop | Object | 출발 정류장(역) | 필수 |
stop_id | String | 정류장(역) ID | 필수 |
stop_name | String | 정류장명 | 필수 |
x | Double | 정류장 좌표 x | 필수 |
y | Double | 정류장 좌표 y | 필수 |
arrival_time | Int | 도착 시각 자정(00:00:00)을 기준으로 흐른 초(seconds from midnight) 단위의 정수 (예: 47460 = 13:11:00, 47,460 ÷ 3600 = 13시간, 나머지 660초 ÷ 60 = 11분) | 필수 |
departure_time | Int | 출발 시각 자정(00:00:00) 기준 누적 초 (예: 47490 = 47460 + 30, 30초 정차 후 출발) | 필수 |
boardable | Boolean | 승하차 가능 여부(기본값: true)• true: 해당 차량이 이 정류장(역)에 정차하여 승하차 가능• false: 통과하여 승하차 불가 (예: 급행 무정차 통과역)ex) 급행 열차의 무정차 통과역의 경우 false | 필수 |
arrival_stop | Object | 도착 정류장(역) 객체 구조는 departure_stop과 동일 | 필수 |
passing_stops | Object[] | 출발 정류장(역)과 도착 정류장(역) 사이의 모든 중간 정류장(역) 목록 객체 구조는 departure_stop과 동일 | 선택 |
route | Object | 노선 정보 | 필수 |
route_id | String | 노선 ID | 필수 |
route_short_name | String | 노선 약칭 (예: 1호선, 740) ※ 도보 Section의 경우 Walk 값으로 응답 | 필수 |
route_full_name | String | 노선명 (예: 수도권 1호선, 740) ※ 도보 Section의 경우 Walk 값으로 응답 | 필수 |
vehicle_type_name | String | 차량 종류 지하철: • GENERAL: 일반 열차• EXPRESS: 급행 열차• LIMITED_EXPRESS: 특급 열차• DIRECT: 직행 열차버스: • EMPTY: 미정의• BLUE: 간선• GREEN: 지선• RED: 광역• YELLOW: 순환• AIRPORT:공항• GENERAL: 일반• SEAT: 좌석• EXPRESS: 급행• MAUL: 마을• DIRECT: 직행• OUTER: 외곽• INTERCITY: 시외• RURAL: 농어촌도보: • Walk | 필수 |
branch_id | String | 지하철 노선 분기 ID. 같은 노선이라도 종착역·운행 방향·급행 여부 등에 따라 별도 ID로 구분됨 (예: METROPOLITAN_01_FROM_INCHEON, 인천 방향 1호선) ※ 지하철 Section인 경우 제공 | 조건부 필수 |
branch_direction | String | 지하철 노선 분기 방향 • UP: 상행• DOWN: 하행※ 지하철 Section인 경우 제공 | 조건부 필수 |
train_type | String | 열차 종류 지하철: • GENERAL: 일반 열차• EXPRESS: 급행 열차• LIMITED_EXPRESS: 특급 열차• DIRECT: 직행 열차 | 조건부 필수 |
last_stop_id_of_trip | String | Trip의 종착역(행선지) ID | 조건부 필수 |
last_stop_name_of_trip | String | Trip의 종착역(행선지) 명칭 | 조건부 필수 |
alternative_routes | Object[] | 대체 노선 목록. 각 섹션에서 "탑승정류장 → 통과정류장 → 하차정류장" 순서가 모두 동일한 다른 노선 객체 구조는 route와 동일 | 선택 |
path | Double[] | 구간 경로 좌표 배열 Vertex 목록 형식: [x1, y1, x2, y2, ...] (x, y 쌍이 연속됨) | 선택 |
alighting | Object | 하차 정보 ※ 지하철 Section인 경우 제공 | 조건부 필수 |
door_direction | String | 하차문 방향 • LEFT: 왼쪽• RIGHT: 오른쪽• BOTH: 양쪽• UNKNOWN: 알 수 없음 | 필수 |
fast_alighting_door_list | String | 빠른 하차문 목록 형식: {호차-문번호},{호차-문번호},... (쉼표 구분) (예: 3-2,3-3 — 3호차 2번 문, 3호차 3번 문) | 필수 |
transfer | Object | 환승 정보 ※ 다음 Section이 존재하고, 해당 Section이 지하철인 경우 제공 | 조건부 필수 |
transfer_type | String | 환승 유형 • NONE: 환승 없음 (마지막 섹션 등)• NORMAL: 일반 환승• CURRENT: 제자리 환승• OPPOSITE: 맞은편 환승• UNKNOWN: 환승에 대한 정확한 정보 없음※ 지하철 Section인 경우 제공 | 필수 |
fast_transfer_door_list | String | 빠른 환승문 목록 환승 유형에 따른 값 제공: • NORMAL: 일반 문 번호 (예: 1-1, 5-4) 또는 모든 문• CURRENT, OPPOSITE: 모든 문• NONE, UNKNOWN: 미제공 | 선택 |
platform_number | String | 환승 승강장 번호 | 선택 |
transfer_time | Int | 환승 시간 (단위: 초) | 필수 |
distance | Int | 이동 거리 (단위: m) ※ 환승을 제외한 순수 노선 이동 거리 | 필수 |
time | Int | 이동 시간 (단위: 초) ※ 환승을 제외한 순수 노선 이동 시간 | 필수 |
waiting_time | Int | 노선 탑승 대기시간 (단위: 초) 현재 Section 출발 시간 - 이전 Section 도착 시간 | 필수 |
first_trip | Boolean | 첫차 여부 (기본값: false)• true: 해당 노선 운행 시작일의 첫차인 경우• false: 그 외 일반 운행 차량인 경우 | 필수 |
last_trip | Boolean | 막차 여부 (기본값: false)• true: 해당 노선 운행 종료일의 막차인 경우• false: 그 외 일반 운행 차량인 경우 | 필수 |
walking_transfer_section | Boolean | 이종 교통수단 간 환승을 위한 도보 Section 여부 (기본값: false)(지하철 ↔ 버스 등 노선 종류 간 환승. 지하철 ↔ 지하철 환승은 제외) • true: 이종 간 환승 도보 Section• false: 그 외예: • 섹션 #0 - 출발지 → 첫 정류장 구간: false• 섹션 #1 - 지하철 or 버스 구간: false• 섹션 #2 - 도보 환승: true• 섹션 #3 - 지하철 or 버스 구간: false• 섹션 #4 - 최종 하차지 → 목적지: false | 필수 |