Kakao Developers

페이지 이동경로

문서>
카카오내비>
REST API

카카오내비

REST API

이 문서는 REST API를 사용하여 경로 안내 정보를 요청하는 방법을 안내합니다.

각 API를 통해 제공 받은 경로 정보는 웹 서비스나 애플리케이션에서 다양한 목적에 맞게 활용할 수 있습니다.

이 문서에 포함된 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.

자동차 길찾기

단일 출발지에서 단일 목적지까지의 경로 정보를 제공합니다. 최대 5개의 경유지를 추가할 수 있습니다.

REST API 키를 헤더에 담아 GET으로 요청합니다. 경유지나 경로 탐색과 관련한 설정과 운행 차량 정보를 지정할 수 있습니다.

성공 시 응답 바디에 JSON 객체로 설정한 목적지로 가는 경로 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

URL

GET /v1/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK {REST_API_KEY}

Parameter

Name	Type	Description	Required
origin	`String`	출발지 다음 중 하나의 형식으로 요청: `{X좌표},{Y좌표},name={출발지명}` `{X좌표},{Y좌표}` (예: `"127.111202,37.394912,name=판교역"` 또는 `"127.111202,37.394912"`)	O
destination	`String`	목적지 다음 중 하나의 형식으로 요청: `{X좌표},{Y좌표},name={목적지명}` `{X좌표},{Y좌표}` (예: `"127.111202,37.394912,name=판교역"` 또는 `"127.111202,37.394912"`)	O
waypoints	`String`	경유지, 최대 5개까지 허용 경유지 수만큼 `{X좌표},{Y좌표},name={경유지명}` 또는 `{X좌표},{Y좌표}`를 `\|`(또는 인코딩된 문자인 `%7C`)로 연결하여 입력 (예: `"127.111202,37.394912,name=판교역 \| 127.112275,37.392815"`)	X
priority	`String`	경로탐색 우선순위 옵션 다음 중 하나: `RECOMMEND`: 추천 경로 `TIME`: 최단 시간 `DISTANCE`: 최단 경로 (기본값: `RECOMMEND`)	X
avoid	`String`	경로탐색 제한 옵션 다음 값 사용 가능: `roadevent`: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보) `ferries`: 페리 항로 `toll`: 유료도로 `motorway`: 자동차 전용도로 `schoolzone`: 어린이보호구역 (기본값: `null`) 여러 개의 제한 옵션을 사용하려면 `\|`(또는 인코딩된 문자인 `%7C`)로 연결 (예: `avoid=roadevent\|ferries`)	X
alternatives	`Boolean`	대안 경로 제공 여부 `true`: 대안 경로 제공 `false`: 대안 경로 미제공 (기본값: `false`)	X
road_details	`Boolean`	상세 도로 정보 제공 여부 `true`: 상세 도로 정보 제공 `false`: 상세 도로 정보 미제공 (기본값: `false`)	X
car_type	`Int`	차종 (기본값: `1`)	X
car_fuel	`String`	차량 유종 정보 다음 중 하나: `GASOLINE`: 휘발유 `DIESEL`: 경유 `LPG`: LPG (기본값: `GASOLINE`)	X
car_hipass	`Boolean`	하이패스 장착 여부 `true`: 하이패스 장착 `false`: 하이패스 미장착 (기본값: `false`)	X
summary	`Boolean`	요약 정보 제공 여부 `true`: 요약 정보 제공 `false`: 요약 정보 미제공 (기본값: `false`)	X

Response

Name	Type	Description
trans_id	`String`	경로 요청 ID
routes	`Route[]`	경로 정보 `alternatives`가 `true`인 경우 한 개 이상의 경로 제공 가능

Route: 자동차 길찾기

Name	Type	Description
result_code	`Int`	경로 탐색 결과 코드
result_msg	`String`	경로 탐색 결과 메시지
summary	`Summary`	경로 요약 정보
sections	`Section[]`	구간별 경로 정보 경유지가 존재할 경우 {경유지 수 + 1} 만큼의 섹션(경로 구간) 생성 (예: 경유지 수가 2개인 경우 총 3개의 섹션 정보가 생성, section1: 출발지 → 경유지 1 section2: 경유지1 → 경유지 2 section3: 경유지2 → 목적지)

Summary: 자동차 길찾기

Name	Type	Description
origin	`Origin`	출발지 정보
destination	`Destination`	목적지 정보
waypoints	`Waypoint[]`	경유지 정보
priority	`String`	경로탐색 우선순위 옵션
bound	`Bound`	모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box)
fare	`Fare`	요금 정보
distance	`Int`	전체 검색결과 거리(미터)
duration	`Int`	목적지까지 소요시간(초)

Section: 자동차 길찾기

Name	Type	Description
distance	`Int`	섹션 거리(미터)
duration	`Int`	전체 검색결과 이동시간(초)
bound	`Bound`	모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box) `summary`가 `false`인 경우에만 제공
roads	`Road[]`	도로 정보 `summary`가 `false`인 경우에만 제공
guides	`Guide[]`	안내 정보 `summary`가 `false`인 경우에만 제공

Origin: 자동차 길찾기

Name	Type	Description
name	`String`	출발지 이름
x	`Double`	X 좌표
y	`Double`	Y 좌표

Destination: 자동차 길찾기

Name	Type	Description
name	`String`	목적지 이름
x	`Double`	X 좌표
y	`Double`	Y 좌표

Waypoint: 자동차 길찾기

Name	Type	Description
name	`String`	경유지 이름
x	`Double`	X 좌표
y	`Double`	Y 좌표

Bound: 자동차 길찾기

Name	Type	Description
min_x	`Double`	바운딩 박스 왼쪽 하단의 X 좌표
min_y	`Double`	바운딩 박스 왼쪽 하단의 Y 좌표
max_x	`Double`	바운딩 박스 오른쪽 상단의 X 좌표
max_y	`Double`	바운딩 박스 오른쪽 상단의 Y 좌표

Fare: 자동차 길찾기

Name	Type	Description
taxi	`Int`	택시 요금(원)
toll	`Int`	통행 요금(원)

Road: 자동차 길찾기

Name	Type	Description
name	`String`	도로명
distance	`Int`	도로길이(미터)
duration	`Int`	예상 이동시간(초) 현재 예상 이동시간 및 실제 이동시간은 동일한 값으로 설정
traffic_speed	`Double`	현재 교통정보 속도(km/h)
traffic_state	`Int`	현재 교통정보 상태
vertexes	`Double[]`	X,Y 좌표로 구성된 1차원 배열 (예: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] )

Guide: 자동차 길찾기

Name	Type	Description
name	`String`	명칭
x	`Double`	X 좌표
y	`Double`	Y 좌표
distance	`Int`	이전 가이드 지점부터 현재 가이드 지점까지 거리(미터)
duration	`Int`	이전 가이드 지점부터 현재 가이드 지점까지 시간(초)
type	`Int`	안내 타입
guidance	`String`	안내 문구
road_index	`Int`	현재 가이드에 대한 링크 인덱스

Sample

Request

curl -v -X GET "https://apis-navi.kakaomobility.com/v1/directions?origin=127.11015314141542,37.39472714688412&destination=127.10824367964793,37.401937080111644&waypoints=&priority=RECOMMEND&car_fuel=GASOLINE&car_hipass=false&alternatives=false&road_details=false" \
    -H "Authorization: KakaoAK {REST_API_KEY}"

Response

{
    "trans_id": "f368e6fad6f648a4b3e1c1680b0a6ff2",
    "routes": [
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "summary": {
                "origin": {
                    "name": "",
                    "x": 127.11015051307636,
                    "y": 37.394725518530834
                },
                "destination": {
                    "name": "",
                    "x": 127.10823557165544,
                    "y": 37.401928707331656
                },
                "waypoints": [],
                "priority": "RECOMMEND",
                "bound": {
                    "min_x": 127.10833536148644,
                    "min_y": 37.39445954360996,
                    "max_x": 127.1098222529551,
                    "max_y": 37.40242724407785
                },
                "fare": {
                    "taxi": 3800,
                    "toll": 0
                },
                "distance": 1033,
                "duration": 262
            },
            "sections": [
                {
                    "distance": 1033,
                    "duration": 262,
                    "bound": {
                        "min_x": 127.10824109988312,
                        "min_y": 37.394469584427156,
                        "max_x": 127.10991634747967,
                        "max_y": 37.40242613861426
                    },
                    "roads": [
                        {
                            "name": "",
                            "distance": 22,
                            "duration": 5,
                            "traffic_speed": 16.0,
                            "traffic_state": 0,
                            "vertexes": [
                                127.10991634747967,
                                37.39447145478345,
                                127.10966790676201,
                                37.394469584427156
                            ]
                        },
                        {
                            "name": "판교역로",
                            "distance": 883,
                            "duration": 213,
                            "traffic_speed": 19.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.10966790676201,
                                37.394469584427156,
                                127.10967141980313,
                                37.39512739646385,
                                127.10967141980313,
                                37.39512739646385,
                                127.10968100356395,
                                37.396226781360426,
                                127.10968100356395,
                                37.396226781360426,
                                127.10967417816033,
                                37.39775855885587,
                                127.10967417816033,
                                37.39775855885587,
                                127.10968323318781,
                                37.39794785293074,
                                127.10968323318781,
                                37.39794785293074,
                                127.10967534594126,
                                37.39861458950405,
                                127.10967534594126,
                                37.39861458950405,
                                127.10967214334856,
                                37.399840028043634,
                                127.10967214334856,
                                37.399840028043634,
                                127.1096931266438,
                                37.40093048716485,
                                127.1096931266438,
                                37.40093048716485,
                                127.10967543155922,
                                37.40242613861426
                            ]
                        },
                        {
                            "name": "판교역로241번길",
                            "distance": 128,
                            "duration": 44,
                            "traffic_speed": 25.0,
                            "traffic_state": 3,
                            "vertexes": [
                                127.10967543155922,
                                37.40242613861426,
                                127.10860261294675,
                                37.40240904474889,
                                127.10860261294675,
                                37.40240904474889,
                                127.10824109988312,
                                37.402415329497174
                            ]
                        }
                    ],
                    "guides": [
                        {
                            "name": "출발지",
                            "x": 127.10991634747967,
                            "y": 37.39447145478345,
                            "distance": 0,
                            "duration": 0,
                            "type": 100,
                            "guidance": "출발지",
                            "road_index": 0
                        },
                        {
                            "name": "",
                            "x": 127.10966790676201,
                            "y": 37.394469584427156,
                            "distance": 22,
                            "duration": 5,
                            "type": 2,
                            "guidance": "우회전",
                            "road_index": 1
                        },
                        {
                            "name": "",
                            "x": 127.10967543155922,
                            "y": 37.40242613861426,
                            "distance": 883,
                            "duration": 213,
                            "type": 1,
                            "guidance": "좌회전",
                            "road_index": 2
                        },
                        {
                            "name": "목적지",
                            "x": 127.10824109988312,
                            "y": 37.402415329497174,
                            "distance": 128,
                            "duration": 44,
                            "type": 101,
                            "guidance": "목적지",
                            "road_index": -1
                        }
                    ]
                }
            ]
        }
    ]
}

다중 경유지 길찾기

단일 출발지에서 여러 개의 경유지를 거쳐 단일 목적지까지의 경로 정보를 제공합니다. 최대 5개의 경유지를 추가할 수 있는 자동차 길찾기와 달리, 다중 경유지 길찾기 요청 시에는 최대 30개의 경유지를 설정할 수 있습니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다.

성공 시 응답 바디에 JSON 객체로 지정한 경유지를 거친 경로 정보를 받습니다. 응답 구성은 자동차 길찾기 응답과 동일합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

URL

POST /v1/waypoints/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK {REST_API_KEY}
Content-Type: application/json

Parameter

Name	Type	Description	Required
origin	`Origin`	출발지	O
destination	`Destination`	목적지	O
waypoints	`Waypoint[]`	경유지, 최대 30개까지 허용	X
priority	`String`	경로탐색 우선순위 옵션 다음 중 하나: `RECOMMEND`: 추천 경로 `TIME`: 최단 시간 `DISTANCE`: 최단 경로 (기본값: `RECOMMEND`)	X
avoid	`String[]`	경로탐색 제한 옵션을 배열로 사용 다음 값 사용 가능: `roadevent`: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보) `ferries`: 페리 항로 `toll`: 유료도로 `motorway`: 자동차 전용도로 `schoolzone`: 어린이보호구역 (예: `["roadevent", "motorway"]`) (기본값: `null`)	X
alternatives	`Boolean`	대안 경로 제공 여부 `true`: 대안 경로 제공 `false`: 대안 경로 미제공 (기본값: `false`)	X
road_details	`Boolean`	상세 도로 정보 제공 여부 `true`: 상세 도로 정보 제공 `false`: 상세 도로 정보 미제공 (기본값: `false`)	X
car_type	`Int`	차종 (기본값: `1`)	X
car_fuel	`String`	차량 유종 정보 다음 중 하나: `GASOLINE`: 휘발유 `DIESEL`: 경유 `LPG`: LPG (기본값: `GASOLINE`)	X
car_hipass	`Boolean`	하이패스 장착 여부 `true`: 하이패스 장착 `false`: 하이패스 미장착 (기본값: `false`)	X
summary	`Boolean`	요약 정보 제공 여부 `true`: 요약 정보 제공 `false`: 요약 정보 미제공 (기본값: `false`)	X

Origin: 다중 경유지 길찾기

Name	Type	Description	Required
name	`String`	출발지 이름	X
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Destination: 다중 경유지 길찾기

Name	Type	Description	Required
name	`String`	목적지 이름	X
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Waypoint: 다중 경유지 길찾기

Name	Type	Description	Required
name	`String`	경유지 이름	X
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Response

응답 구성은 자동차 길찾기와 동일합니다.

Sample

Request

curl -v -X POST "https://apis-navi.kakaomobility.com/v1/waypoints/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK {REST_API_KEY}" \
-d '{
    "origin": {
        "x": "127.11024293202674",
        "y": " 37.394348634049784"
    },
    "destination": {
        "x": "127.10860518470294",
        "y": "37.401999820065534"
    },
    "waypoints": [
        {
            "name": "name0",
            "x": 127.11341936045922,
            "y": 37.39639094915999
        }
    ],
    "priority": "RECOMMEND",
    "car_fuel": "GASOLINE",
    "car_hipass": false,
    "alternatives": false,
    "road_details": false
}'

Response

{
    "trans_id": "eba67ee00e494638984205a83ba3892a",
    "routes": [
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "summary": {
                "origin": {
                    "name": "",
                    "x": 127.11023403583478,
                    "y": 37.39434769502827
                },
                "destination": {
                    "name": "",
                    "x": 127.10859622855493,
                    "y": 37.40199450213265
                },
                "waypoints": [
                    {
                        "name": "name0",
                        "x": 127.11341740484119,
                        "y": 37.39639001677204
                    }
                ],
                "priority": "RECOMMEND",
                "bound": {
                    "min_x": 127.10869672963145,
                    "min_y": 37.39446226802707,
                    "max_x": 127.11400101911747,
                    "max_y": 37.402458630852735
                },
                "fare": {
                    "taxi": 4300,
                    "toll": 0
                },
                "distance": 1772,
                "duration": 549
            },
            "sections": [
                {
                    "distance": 605,
                    "duration": 164,
                    "bound": {
                        "min_x": 127.11341931516797,
                        "min_y": 37.394469584427156,
                        "max_x": 127.11406301821938,
                        "max_y": 37.39623266200683
                    },
                    "roads": [
                        {
                            "name": "",
                            "distance": 22,
                            "duration": 5,
                            "traffic_speed": 16.0,
                            "traffic_state": 0,
                            "vertexes": [
                                127.10991634747967,
                                37.39447145478345,
                                127.10966790676201,
                                37.394469584427156
                            ]
                        },
                        {
                            "name": "판교역로",
                            "distance": 195,
                            "duration": 54,
                            "traffic_speed": 13.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.10966790676201,
                                37.394469584427156,
                                127.10967141980313,
                                37.39512739646385,
                                127.10967141980313,
                                37.39512739646385,
                                127.10968100356395,
                                37.396226781360426
                            ]
                        },
                        {
                            "name": "대왕판교로606번길",
                            "distance": 331,
                            "duration": 93,
                            "traffic_speed": 17.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.10968100356395,
                                37.396226781360426,
                                127.11030222640413,
                                37.39622244643168,
                                127.11030222640413,
                                37.39622244643168,
                                127.11047162177373,
                                37.396223720873245,
                                127.11047162177373,
                                37.396223720873245,
                                127.11126224002652,
                                37.39622065509858,
                                127.11126224002652,
                                37.39622065509858,
                                127.11205275202975,
                                37.396226593999046,
                                127.11205275202975,
                                37.396226593999046,
                                127.11225602658233,
                                37.39622812029087,
                                127.11225602658233,
                                37.39622812029087,
                                127.11274162696445,
                                37.39623176501827,
                                127.11274162696445,
                                37.39623176501827,
                                127.11309181718316,
                                37.39622538141045,
                                127.11309181718316,
                                37.39622538141045,
                                127.11341931516797,
                                37.39622783738649
                            ]
                        },
                        {
                            "name": "대왕판교로606번길",
                            "distance": 57,
                            "duration": 12,
                            "traffic_speed": 17.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.11341931516797,
                                37.39622783738649,
                                127.11406301821938,
                                37.39623266200683
                            ]
                        }
                    ],
                    "guides": [
                        {
                            "name": "출발지",
                            "x": 127.10991634747967,
                            "y": 37.39447145478345,
                            "distance": 0,
                            "duration": 0,
                            "type": 100,
                            "guidance": "출발지",
                            "road_index": 0
                        },
                        {
                            "name": "",
                            "x": 127.10966790676201,
                            "y": 37.394469584427156,
                            "distance": 22,
                            "duration": 5,
                            "type": 2,
                            "guidance": "우회전",
                            "road_index": 1
                        },
                        {
                            "name": "동안사거리",
                            "x": 127.10968100356395,
                            "y": 37.396226781360426,
                            "distance": 195,
                            "duration": 54,
                            "type": 2,
                            "guidance": "분당구청 삼평동주민센터 방면으로 우회전",
                            "road_index": 2
                        },
                        {
                            "name": "경유지",
                            "x": 127.11341931516797,
                            "y": 37.39622783738649,
                            "distance": 331,
                            "duration": 93,
                            "type": 1000,
                            "guidance": "경유지",
                            "road_index": -1
                        }
                    ]
                },
                {
                    "distance": 1224,
                    "duration": 397,
                    "bound": {
                        "min_x": 127.10860261294675,
                        "min_y": 37.39622783738649,
                        "max_x": 127.11406301821938,
                        "max_y": 37.40242613861426
                    },
                    "roads": [
                        {
                            "name": "대왕판교로606번길",
                            "distance": 57,
                            "duration": 12,
                            "traffic_speed": 17.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.11341931516797,
                                37.39622783738649,
                                127.11406301821938,
                                37.39623266200683
                            ]
                        },
                        {
                            "name": "",
                            "distance": 233,
                            "duration": 57,
                            "traffic_speed": 42.0,
                            "traffic_state": 0,
                            "vertexes": [
                                127.11406301821938,
                                37.39623266200683,
                                127.11403422576758,
                                37.39771922184463,
                                127.11403422576758,
                                37.39771922184463,
                                127.11404960021814,
                                37.398332068681995
                            ]
                        },
                        {
                            "name": "동판교로177번길",
                            "distance": 86,
                            "duration": 45,
                            "traffic_speed": 21.0,
                            "traffic_state": 3,
                            "vertexes": [
                                127.11404960021814,
                                37.398332068681995,
                                127.1130784782746,
                                37.3983157776669
                            ]
                        },
                        {
                            "name": "분당내곡로",
                            "distance": 160,
                            "duration": 27,
                            "traffic_speed": 33.0,
                            "traffic_state": 3,
                            "vertexes": [
                                127.1130784782746,
                                37.3983157776669,
                                127.11313041857109,
                                37.39965877010523,
                                127.11313041857109,
                                37.39965877010523,
                                127.11312925062586,
                                37.399757879664605
                            ]
                        },
                        {
                            "name": "대왕판교로644번길",
                            "distance": 124,
                            "duration": 76,
                            "traffic_speed": 15.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.11312925062586,
                                37.399757879664605,
                                127.11274420726458,
                                37.39984509856906,
                                127.11274420726458,
                                37.39984509856906,
                                127.11173886656147,
                                37.39985557194009
                            ]
                        },
                        {
                            "name": "",
                            "distance": 564,
                            "duration": 180,
                            "traffic_speed": 16.0,
                            "traffic_state": 2,
                            "vertexes": [
                                127.11173886656147,
                                37.39985557194009,
                                127.11175987981302,
                                37.40094603107842,
                                127.11175987981302,
                                37.40094603107842,
                                127.11174254485269,
                                37.40241465350646,
                                127.11170855662199,
                                37.402423408918274,
                                127.10967543155922,
                                37.40242613861426,
                                127.10967543155922,
                                37.40242613861426,
                                127.10860261294675,
                                37.40240904474889,
                                127.10860261294675,
                                37.40240904474889,
                                127.10860261294675,
                                37.40240904474889
                            ]
                        }
                    ],
                    "guides": [
                        {
                            "name": "경유지",
                            "x": 127.11341931516797,
                            "y": 37.39622783738649,
                            "distance": 0,
                            "duration": 0,
                            "type": 0,
                            "guidance": "동판교로 삼평동주민센터 방면으로 직진",
                            "road_index": 0
                        },
                        {
                            "name": "",
                            "x": 127.11406301821938,
                            "y": 37.39623266200683,
                            "distance": 57,
                            "duration": 12,
                            "type": 1,
                            "guidance": "삼평동주민센터 방면으로 좌회전",
                            "road_index": 1
                        },
                        {
                            "name": "",
                            "x": 127.11404960021814,
                            "y": 37.398332068681995,
                            "distance": 233,
                            "duration": 57,
                            "type": 1,
                            "guidance": "판교테크노밸리 양재 내곡 방면으로 좌회전",
                            "road_index": 2
                        },
                        {
                            "name": "",
                            "x": 127.1130784782746,
                            "y": 37.3983157776669,
                            "distance": 86,
                            "duration": 45,
                            "type": 2,
                            "guidance": "동판교IC 내곡,서울 방면으로 우회전",
                            "road_index": 3
                        },
                        {
                            "name": "삼평사거리",
                            "x": 127.11312925062586,
                            "y": 37.399757879664605,
                            "distance": 160,
                            "duration": 27,
                            "type": 1,
                            "guidance": "대왕판교로 경기창조경제혁신센터 방면으로 좌회전",
                            "road_index": 4
                        },
                        {
                            "name": "",
                            "x": 127.11173886656147,
                            "y": 37.39985557194009,
                            "distance": 124,
                            "duration": 76,
                            "type": 2,
                            "guidance": "우회전",
                            "road_index": 5
                        },
                        {
                            "name": "목적지",
                            "x": 127.10860261294675,
                            "y": 37.40240904474889,
                            "distance": 564,
                            "duration": 180,
                            "type": 101,
                            "guidance": "목적지",
                            "road_index": -1
                        }
                    ]
                }
            ]
        }
    ]
}

다중 출발지 길찾기

한 개 이상의 다중 출발지에서 단일 목적지까지의 경로 요약 정보를 제공합니다. 경로의 요약 정보만을 제공하기 때문에 상세 경로 안내를 받으려면 자동차 길찾기를 추가적으로 요청하여야 합니다.

출발지는 최대 30개까지 설정할 수 있습니다. 30개를 초과하는 출발지를 설정하려면 partnership@kakaomobility.com을 통해 제휴를 신청합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다.

성공 시 응답 바디에 JSON 객체로 경로 요약 정보를 받습니다. 경로 요약 정보는 여러 개의 출발지에서 하나의 목적지로 가는 경로 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

URL

POST /v1/origins/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK {REST_API_KEY}
Content-Type: application/json

Parameter

Name	Type	Description	Required
origins	`Origin[]`	출발지, 최대 30개까지 허용	O
destination	`Destination`	목적지	O
radius	`Int`	길찾기 반경(미터) (최대: 10000)	O
priority	`String`	경로탐색 우선순위 옵션 다음 중 하나: `TIME`: 최단 시간 `DISTANCE`: 최단 경로 (기본값: `TIME`)	X
avoid	`String[]`	경로탐색 제한 옵션을 배열로 사용 다음 값 사용 가능: `roadevent`: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보) `ferries`: 페리 항로 `toll`: 유료도로 `motorway`: 자동차 전용도로 `schoolzone`: 어린이보호구역 (예: `["roadevent", "motorway"]`) (기본값: `null`)	X

Origin: 다중 출발지 길찾기

Name	Type	Description	Required
key	`String`	각 출발지를 구분하기 위한 임의의 문자열 지정	O
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Destination: 다중 출발지 길찾기

Name	Type	Description	Required
name	`String`	목적지 이름	X
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Response

Name	Type	Description
trans_id	`String`	경로 요청 ID
routes	`Route[]`	경로 정보, 경로 수 만큼 생성

Route: 다중 출발지 길찾기

Name	Type	Description
result_code	`Int`	경로 탐색 결과 코드
result_msg	`String`	경로 탐색 결과 메시지
key	`String`	`origins`의 `key` 값으로 지정한 각 출발지의 키 값
summary	`Summary`	경로 요약 정보

Summary: 다중 출발지 길찾기

Name	Type	Description
distance	`Int`	전체 검색결과 거리(미터)
duration	`Int`	목적지까지 소요시간(초)

Sample

Request

curl -v -X POST "https://apis-navi.kakaomobility.com/v1/origins/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK {REST_API_KEY}" \
-d '{
  "origins": [
    {
      "x": "127.1331694942593",
      "y": "37.4463137562622",
      "key": "0"
    },
    {
      "x": "127.13243772760565",
      "y": "37.44148514309502",
      "key": "1"
    }
  ],
  "destination": {
    "x": "127.14816492905383",
    "y": "37.4401690139602"
  },
  "radius": 5000
}'

Response

{
    "trans_id": "a2653095f26445dba15d736c5714d86a",
    "routes": [
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "key": "0",
            "summary": {
                "distance": 2305,
                "duration": 615
            }
        },
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "key": "1",
            "summary": {
                "distance": 1878,
                "duration": 408
            }
        }
    ]
}

다중 목적지 길찾기

단일 출발지에서 한 개 이상의 다중 목적지까지의 경로 요약 정보를 제공합니다. 경로의 요약 정보만을 제공하기 때문에 상세 경로 안내를 받으려면 자동차 길찾기를 추가적으로 요청하여야 합니다.

목적지는 최대 30개까지 설정할 수 있습니다. 30개를 초과하는 목적지를 설정하려면 partnership@kakaomobility.com을 통해 제휴를 신청합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다.

성공 시 응답 바디에 JSON 객체로 경로 요약 정보를 받습니다. 경로 요약 정보는 하나의 출발지에서 여러 목적지로 가는 경로 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

URL

POST /v1/destinations/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK {REST_API_KEY}
Content-Type: application/json

Parameter

Name	Type	Description	Required
origin	`Origin`	출발지	O
destinations	`Destination[]`	목적지, 최대 30개까지 허용	O
radius	`Int`	길찾기 반경(미터) (최대: 10000)	O
priority	`String`	경로탐색 우선순위 옵션 다음 중 하나: `TIME`: 최단 시간 `DISTANCE`: 최단 경로 (기본값: `TIME`)	X
avoid	`String[]`	경로탐색 제한 옵션을 배열로 사용 다음 값 사용 가능: `roadevent`: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보) `ferries`: 페리 항로 `toll`: 유료도로 `motorway`: 자동차 전용도로 `schoolzone`: 어린이보호구역 (예: `["roadevent", "motorway"]`) (기본값: `null`)	X

Origin: 다중 목적지 길찾기

Name	Type	Description	Required
name	`String`	출발지 이름	X
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Destination: 다중 목적지 길찾기

Name	Type	Description	Required
key	`String`	각 목적지를 구분하기 위한 임의의 문자열 지정 O
x	`Double`	X 좌표	O
y	`Double`	Y 좌표	O

Response

Name	Type	Description
trans_id	`String`	경로 요청 ID
routes	`Route[]`	경로 정보, 경로 수 만큼 생성

Route: 다중 목적지 길찾기

Name	Type	Description
result_code	`Int`	경로 탐색 결과 코드
result_msg	`String`	경로 탐색 결과 메시지
key	`String`	`destinations`의 `key` 값으로 지정한 각 목적지의 키 값
summary	`Summary`	경로 요약 정보

Summary: 다중 목적지 길찾기

Name	Type	Description
distance	`Int`	전체 검색결과 거리(미터)
duration	`Int`	목적지까지 소요시간(초)

Sample

Request

curl -v -X POST "https://apis-navi.kakaomobility.com/v1/destinations/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK {REST_API_KEY}" \
-d '{
  "origin": {
    "x": "127.13144306487084",
    "y": " 37.44134209110179"
  },
  "destinations": [
    {
      "x": "127.14112393388389",
      "y": "37.44558371517034",
      "key": "0"
    },
    {
      "x": "127.14192737519186",
      "y": "37.4401766683372",
      "key": "1"
    }
  ],
  "radius": 5000
}'

Response

{
    "trans_id": "b2520cb429004460a4d5f389d108db38",
    "routes": [
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "key": "0",
            "summary": {
                "distance": 1307,
                "duration": 307
            }
        },
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "key": "1",
            "summary": {
                "distance": 1323,
                "duration": 320
            }
        }
    ]
}

미래운행정보 길찾기

미래의 특정 시간을 지정하여 해당 시간을 기준으로 단일 출발지에서 단일 목적지까지의 경로 정보를 제공합니다. 반드시 현재 시각 이후로 출발 시간을 지정해야 합니다.

REST API 키를 헤더에 담아 GET으로 요청합니다.

성공 시 응답 바디에 JSON 객체로 경로 정보를 받습니다. 경로 정보는 지정한 출발 시간에 하나의 출발지에서 하나의 목적지로 가는 예상 경로 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

URL

GET /v1/future/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK {REST_API_KEY}

Parameter

Name	Type	Description	Required
departure_time	`String`	출발시간, YYYYMMDDHHMM 형식으로 현재시간 이후 시간 설정 (예: 202107171010)	O
origin	`String`	출발지 다음 중 하나의 형식으로 요청: `{X좌표},{Y좌표},name={출발지명}` `{X좌표},{Y좌표}` (예: `"127.111202,37.394912,name=판교역"` 또는 `"127.111202,37.394912"`)	O
destination	`String`	목적지 다음 중 하나의 형식으로 요청: `{X좌표},{Y좌표},name={목적지명}` `{X좌표},{Y좌표}` (예: `"127.111202,37.394912,name=판교역"` 또는 `"127.111202,37.394912"`)	O
waypoints	`String`	경유지, 최대 5개까지 허용 경유지 수만큼 `{X좌표},{Y좌표},name={경유지명}` 또는 `{X좌표},{Y좌표}`를 `\|`(또는 인코딩된 문자인 `%7C`)로 연결하여 입력 (예: `"127.111202,37.394912,name=판교역 \| 127.112275,37.392815"`)	X
priority	`String`	경로탐색 우선순위 옵션 다음 중 하나: `RECOMMEND`: 추천 경로 `TIME`: 최단 시간 `DISTANCE`: 최단 경로 (기본값: `RECOMMEND`)	X
avoid	`String`	경로탐색 제한 옵션 다음 값 사용 가능: `roadevent`: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보) `ferries`: 페리 항로 `toll`: 유료도로 `motorway`: 자동차 전용도로 `schoolzone`: 어린이보호구역 (기본값: `null`) 여러 개의 제한 옵션을 사용하려면 `\|`(또는 인코딩된 문자인 `%7C`)로 연결 (예: `avoid=roadevent\|ferries`)	X
alternatives	`Boolean`	대안 경로 제공 여부 `true`: 대안 경로 제공 `false`: 대안 경로 미제공 (기본값: `false`)	X
road_details	`Boolean`	상세 도로 정보 제공 여부 `true`: 상세 도로 정보 제공 `false`: 상세 도로 정보 미제공 (기본값: `false`)	X
car_type	`Int`	차종 (기본값: `1`)	X
car_fuel	`String`	차량 유종 정보 다음 중 하나: `GASOLINE`: 휘발유 `DIESEL`: 경유 `LPG`: LPG (기본값: `GASOLINE`)	X
car_hipass	`Boolean`	하이패스 장착 여부 `true`: 하이패스 장착 `false`: 하이패스 미장착 (기본값: `false`)	X
summary	`Boolean`	요약 정보 제공 여부 `true`: 요약 정보 제공 `false`: 요약 정보 미제공 (기본값: `false`)	X

Response

응답 구성은 자동차 길찾기와 동일합니다.

Sample

Request

curl -v -X GET "https://apis-navi.kakaomobility.com/v1/future/directions?origin=127.11015314141542,37.39472714688412&destination=127.10824367964793,37.401937080111644&departure_time=202109170000" \
    -H "Authorization: KakaoAK {REST_API_KEY}"

Response

{
    "trans_id": "e173a5282b084871bfbfac8771743748",
    "routes": [
        {
            "result_code": 0,
            "result_msg": "길찾기 성공",
            "summary": {
                "origin": {
                    "name": "",
                    "x": 127.11015051307636,
                    "y": 37.394725518530834
                },
                "destination": {
                    "name": "",
                    "x": 127.10823557165544,
                    "y": 37.401928707331656
                },
                "waypoints": [],
                "priority": "RECOMMEND",
                "bound": {
                    "min_x": 127.10833536148644,
                    "min_y": 37.39445954360996,
                    "max_x": 127.1098222529551,
                    "max_y": 37.40242724407785
                },
                "fare": {
                    "taxi": 3800,
                    "toll": 0
                },
                "distance": 1033,
                "duration": 255
            },
            "sections": [
                {
                    "distance": 1033,
                    "duration": 255,
                    "bound": {
                        "min_x": 127.10824109988312,
                        "min_y": 37.394469584427156,
                        "max_x": 127.10991634747967,
                        "max_y": 37.40242613861426
                    },
                    "roads": [
                        {
                            "name": "",
                            "distance": 22,
                            "duration": 5,
                            "traffic_speed": 16.0,
                            "traffic_state": 0,
                            "vertexes": [
                                127.10991634747967,
                                37.39447145478345,
                                127.10966790676201,
                                37.394469584427156
                            ]
                        },
                        {
                            "name": "판교역로",
                            "distance": 883,
                            "duration": 206,
                            "traffic_speed": 20.0,
                            "traffic_state": 3,
                            "vertexes": [
                                127.10966790676201,
                                37.394469584427156,
                                127.10967141980313,
                                37.39512739646385,
                                127.10967141980313,
                                37.39512739646385,
                                127.10968100356395,
                                37.396226781360426,
                                127.10968100356395,
                                37.396226781360426,
                                127.10967417816033,
                                37.39775855885587,
                                127.10967417816033,
                                37.39775855885587,
                                127.10968323318781,
                                37.39794785293074,
                                127.10968323318781,
                                37.39794785293074,
                                127.10967534594126,
                                37.39861458950405,
                                127.10967534594126,
                                37.39861458950405,
                                127.10967214334856,
                                37.399840028043634,
                                127.10967214334856,
                                37.399840028043634,
                                127.1096931266438,
                                37.40093048716485,
                                127.1096931266438,
                                37.40093048716485,
                                127.10967543155922,
                                37.40242613861426
                            ]
                        },
                        {
                            "name": "판교역로241번길",
                            "distance": 128,
                            "duration": 44,
                            "traffic_speed": 25.0,
                            "traffic_state": 3,
                            "vertexes": [
                                127.10967543155922,
                                37.40242613861426,
                                127.10860261294675,
                                37.40240904474889,
                                127.10860261294675,
                                37.40240904474889,
                                127.10824109988312,
                                37.402415329497174
                            ]
                        }
                    ],
                    "guides": [
                        {
                            "name": "출발지",
                            "x": 127.10991634747967,
                            "y": 37.39447145478345,
                            "distance": 0,
                            "duration": 0,
                            "type": 100,
                            "guidance": "출발지",
                            "road_index": 0
                        },
                        {
                            "name": "",
                            "x": 127.10966790676201,
                            "y": 37.394469584427156,
                            "distance": 22,
                            "duration": 5,
                            "type": 2,
                            "guidance": "우회전",
                            "road_index": 1
                        },
                        {
                            "name": "",
                            "x": 127.10967543155922,
                            "y": 37.40242613861426,
                            "distance": 883,
                            "duration": 206,
                            "type": 1,
                            "guidance": "좌회전",
                            "road_index": 2
                        },
                        {
                            "name": "목적지",
                            "x": 127.10824109988312,
                            "y": 37.402415329497174,
                            "distance": 128,
                            "duration": 44,
                            "type": 101,
                            "guidance": "목적지",
                            "road_index": -1
                        }
                    ]
                }
            ]
        }
    ]
}

레퍼런스

길찾기 API에서 사용하는 공통 클래스 정보를 안내합니다.

result_code: 경로 탐색 결과 코드

Code	Description
0	길찾기 성공
1	길찾기 결과를 찾을 수 없음
101	경유지 지점 주변의 도로를 탐색할 수 없음
102	시작 지점 주변의 도로를 탐색할 수 없음
103	도착 지점 주변의 도로를 탐색할 수 없음
104	출발지와 도착지가 같은 지점임
105	시작 지점 주변의 도로에 교통 장애가 있음
106	도착 지점 주변의 도로에 교통 장애가 있음
201	다중 출발지: 출발지가 탐색영역에 포함되지 않음
202	다중 출발지: 출발지 최대 개수 초과 도로 선택 실패
203	다중 출발지: 목적지 도로 선택 실패
204	다중 출발지: 경로탐색 처리시간 제한
205	다중 출발지: 출발지 주변의 유고 정보로 인한 통행 불가
206	다중 출발지: 목적지 주변의 유고 정보로 인한 통행 불가
207	다중 출발지: 출발지가 설정한 길찾기 반경 범위를 벗어남
301	다중 목적지: 출발지 도로 선택 실패
302	다중 목적지: 목적지 도로 선택 실패
303	다중 목적지: 목적지 최대 개수 초과로 인해 경로 탐색 실패
304	다중 목적지:목적지가 설정한 길찾기 반경 범위를 벗어남

traffic_state: 현재 교통정보 상태

Code	Description
0	교통 상태 정보 없음
1	교통 정체
2	교통 지체
3	교통 서행
4	교통 원활
6	교통사고(통행불가)

car_type: 차종

Code	Description
1	소형 (예: 승용차, 16인승 이하 승합차, 2.5ton 미만 화물차) 분류기준: 2축 차량, 윤폭 279.4mm 이하
2	중형 (예: 승합차 17-32인승, 2.5~5.5ton 화물차) 분류기준: 2축 차량, 윤폭 279.4mm 초과, 윤거 1,800mm 이하
3	대형 (예: 승합차 33인승 이상, 5.5~10ton 화물차) 분류기준: 2축 차량, 윤폭 279.4mm 초과, 윤거 1,800mm 초과
4	대형화물 (예: 10t~20ton 화물차) 분류기준: 3축 차량
5	특수화물 (예: 20t 이상 화물차) 분류기준: 4축 이상 차량
6	경차 분류기준: 배기량이 1,000cc 미만으로 길이 3.6m, 너비 1.6m, 높이 2.0m 이하인 차량
7	이륜차

type: 안내 타입

Code	Description
0	직진
1	좌회전
2	우회전
3	유턴
5	왼쪽 방향
6	오른쪽 방향
7	고속도로 출구
8	왼쪽에 고속도로 출구
9	오른쪽에 고속도로 출구
10	고속도로 입구
11	왼쪽에 고속도로 입구
12	오른쪽에 고속도로 입구
14	고가도로 진입
15	지하차도 진입
16	고가도로 옆길
17	지하차도 옆길
18	오른쪽 1시 방향
19	오른쪽 2시 방향
20	오른쪽 3시 방향
21	오른쪽 4시 방향
22	오른쪽 5시 방향
23	6시 방향
24	왼쪽 7시 방향
25	왼쪽 8시 방향
26	왼쪽 9시 방향
27	왼쪽 10시 방향
28	왼쪽 11시 방향
29	12시 방향
30	로터리에서 오른쪽 1시 방향
31	로터리에서 오른쪽 2시 방향
32	로터리에서 오른쪽 3시 방향
33	로터리에서 오른쪽 4시 방향
34	로터리에서 오른쪽 5시 방향
35	로터리에서 6시 방향
36	로터리에서 왼쪽 7시 방향
37	로터리에서 왼쪽 8시 방향
38	로터리에서 왼쪽 9시 방향
39	로터리에서 왼쪽 10시 방향
40	로터리에서 왼쪽 11시 방향
41	로터리에서 12시 방향
42	도시고속도로 출구
43	왼쪽에 도시고속도로 출구
44	오른쪽에 도시고속도로 출구
45	도시고속도로 입구
46	왼쪽에 도시고속도로 입구
47	오른쪽에 도시고속도로 입구
48	왼쪽 고속도로 진입
49	오른쪽 고속도로 진입
61	페리항로 진입
62	페리항로 진출
70	회전교차로에서 오른쪽 1시 방향
71	회전교차로에서 오른쪽 2시 방향
72	회전교차로에서 오른쪽 3시 방향
73	회전교차로에서 오른쪽 4시 방향
74	회전교차로에서 오른쪽 5시 방향
75	회전교차로에서 6시 방향
76	회전교차로에서 왼쪽 7시 방향
77	회전교차로에서 왼쪽 8시 방향
78	회전교차로에서 왼쪽 9시 방향
79	회전교차로에서 왼쪽 10시 방향
80	회전교차로에서 왼쪽 11시 방향
81	회전교차로에서 12시 방향
82	왼쪽 직진
83	오른쪽 직진
84	톨게이트 진입
85	원톨링 진입
86	분기 후 합류 구간 진입
100	출발지
101	목적지
1000	경유지
300	톨게이트
301	휴게소

menu

카카오내비

REST API

자동차 길찾기

URL

Parameter

Route: 자동차 길찾기

Summary: 자동차 길찾기

Section: 자동차 길찾기

Origin: 자동차 길찾기

Destination: 자동차 길찾기

Waypoint: 자동차 길찾기

Bound: 자동차 길찾기

Fare: 자동차 길찾기

Road: 자동차 길찾기

Guide: 자동차 길찾기

Request

Response

다중 경유지 길찾기

URL

Parameter

Origin: 다중 경유지 길찾기

Destination: 다중 경유지 길찾기

Waypoint: 다중 경유지 길찾기

Request

Response

다중 출발지 길찾기

URL

Parameter

Origin: 다중 출발지 길찾기

Destination: 다중 출발지 길찾기

Route: 다중 출발지 길찾기

Summary: 다중 출발지 길찾기

Request

Response

다중 목적지 길찾기

URL

Parameter

Origin: 다중 목적지 길찾기

Destination: 다중 목적지 길찾기

Route: 다중 목적지 길찾기

Summary: 다중 목적지 길찾기

Request

Response

미래운행정보 길찾기

URL

Parameter

Request

Response

레퍼런스

result_code: 경로 탐색 결과 코드

traffic_state: 현재 교통정보 상태

car_type: 차종

type: 안내 타입