페이지 이동경로
  • 문서>
  • 카카오내비>
  • 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[] 경로 정보
alternativestrue인 경우 한 개 이상의 경로 제공 가능
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)
summaryfalse인 경우에만 제공
roads Road[] 도로 정보
summaryfalse인 경우에만 제공
guides Guide[] 안내 정보
summaryfalse인 경우에만 제공
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-Typeapplication/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-Typeapplication/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 originskey 값으로 지정한 각 출발지의 키 값
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-Typeapplication/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 destinationskey 값으로 지정한 각 목적지의 키 값
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 휴게소