카카오모빌리티 디벨로퍼스 문서 길찾기 API 자동차 길찾기

Request 링크 복사

요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.

호출 방식 링크 복사

표 1 호출 방식
Method URL
GET https://apis-navi.kakaomobility.com/v1/directions

요청 헤더(Header) 링크 복사

표 2 요청 헤더
Parameter Description
Authorization KakaoAK ${REST_API_KEY}

{REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키
Content-Type application/json

요청 코드 예제 링크 복사 

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}" // 카카오디벨로퍼스에서 발급 받은 API 키 값

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}" // 카카오디벨로퍼스에서 발급 받은 API 키 값
코드가 숨겨졌습니다.

요청에 대한 파라미터는 다음과 같습니다.

표 3 요청 파라미터
Name Type Description Required
origin String 출발지

다음 중 하나의 형식으로 요청:
${X좌표},${Y좌표},name=${출발지명} 또는
${X좌표},${Y좌표}
(예: "127.111202,37.394912,name=판교역" 또는 
"127.111202,37.394912")		 필수
destination String 목적지

다음 중 하나의 형식으로 요청:
${X좌표},${Y좌표},name=${목적지명} 또는
${X좌표},${Y좌표}
(예: "127.111202,37.394912,name=판교역" 또는 
"127.111202,37.394912")		 필수
waypoints String 경유지, 최대 5개까지 허용

경유지 수만큼 ${X좌표},${Y좌표},name=${경유지명} 또는 ${X좌표},${Y좌표}를 |(또는 인코딩 된 문자인 %7C)로 연결하여 입력
(예: "127.111202,37.394912,name=판교역 | 127.112275,37.392815")		 선택
priority String 경로 탐색 우선순위 옵션

다음 중 하나:
RECOMMEND: 추천 경로
TIME: 최단 시간
DISTANCE: 최단 경로
(기본값: RECOMMEND)		 선택
avoid String 경로 탐색 제한 옵션

다음 값 사용 가능:
ferries: 페리 항로
toll: 유료 도로
motorway: 자동차 전용 도로
schoolzone: 어린이 보호 구역
uturn: 유턴
(기본값: null)

여러 개의 제한 옵션을 사용하려면 |(또는 인코딩 된 문자인 %7C)로 연결
(예: avoid=motorway|ferries)		 선택
roadevent Int 유고(교통사고, 행사, 재난, 도로 공사 등의 교통 장애)로 인한 도로 통제 정보 반영 옵션

0: 도로 전면 통제 정보 반영
1: 출발지 및 목적지 주변의 도로 전면 통제 정보 반영 안 함
2: 모든 도로 전면 통제 정보 반영 안 함
(기본값: 0)		 선택
alternatives Boolean 대안 경로 제공 여부

true: 대안 경로 제공
false: 대안 경로 미제공
(기본값: false)		 선택
road_details Boolean 상세 도로 정보 제공 여부

true: 상세 도로 정보 제공
false: 상세 도로 정보 미제공
(기본값: false)		 선택
car_type Int 차종

(기본값: 1)		 선택
car_fuel String 차량 유종 정보

다음 중 하나:
GASOLINE: 휘발유
DIESEL: 경유
LPG: LPG
(기본값: GASOLINE)		 선택
car_hipass Boolean 하이패스 장착 여부

true: 하이패스 장착
false: 하이패스 미장착
(기본값: false)		 선택
summary Boolean 요약 정보 제공 여부

true: 요약 정보 제공
false: 요약 정보 미제공
(기본값: false)		 선택

Response 링크 복사

응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON포맷으로 전달합니다.

응답 코드 예제 링크 복사 

{
  "trans_id": "c9d60cbabdd44deeafb1e78feb8c8b86",
  "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": 349
      },
      "sections": [
        {
          "distance": 1033,
          "duration": 349,
          "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,
              "traffic_state": 0,
              "vertexes": [
                127.10991634747967,
                37.39447145478345,
                127.10966790676201,
                37.394469584427156
              ]
            },
            {
              "name": "판교역로",
              "distance": 883,
              "duration": 279,
              "traffic_speed": 9,
              "traffic_state": 1,
              "vertexes": [
                127.10966790676201,
                37.394469584427156,
                127.10967141980313,
                37.39512739646385,
                127.10968100356395,
                37.396226781360426,
                127.10967417816033,
                37.39775855885587,
                127.10968323318781,
                37.39794785293074,
                127.10967534594126,
                37.39861458950405,
                127.10967214334856,
                37.399840028043634,
                127.1096931266438,
                37.40093048716485,
                127.10967543155922,
                37.40242613861426
              ]
            },
            {
              "name": "판교역로241번길",
              "distance": 128,
              "duration": 65,
              "traffic_speed": 15,
              "traffic_state": 2,
              "vertexes": [
                127.10967543155922,
                37.40242613861426,
                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": 279,
              "type": 1,
              "guidance": "좌회전",
              "road_index": 2
            },
            {
              "name": "목적지",
              "x": 127.10824109988312,
              "y": 37.402415329497174,
              "distance": 128,
              "duration": 65,
              "type": 101,
              "guidance": "목적지",
              "road_index": -1
            }
          ]
        }
      ]
    }
  ]
}

{
  "trans_id": "c9d60cbabdd44deeafb1e78feb8c8b86",
  "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": 349
      },
      "sections": [
        {
          "distance": 1033,
          "duration": 349,
          "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,
              "traffic_state": 0,
              "vertexes": [
                127.10991634747967,
                37.39447145478345,
                127.10966790676201,
                37.394469584427156
              ]
            },
            {
              "name": "판교역로",
              "distance": 883,
              "duration": 279,
              "traffic_speed": 9,
              "traffic_state": 1,
              "vertexes": [
                127.10966790676201,
                37.394469584427156,
                127.10967141980313,
                37.39512739646385,
                127.10968100356395,
                37.396226781360426,
                127.10967417816033,
                37.39775855885587,
                127.10968323318781,
                37.39794785293074,
                127.10967534594126,
                37.39861458950405,
                127.10967214334856,
                37.399840028043634,
                127.1096931266438,
                37.40093048716485,
                127.10967543155922,
                37.40242613861426
              ]
            },
            {
              "name": "판교역로241번길",
              "distance": 128,
              "duration": 65,
              "traffic_speed": 15,
              "traffic_state": 2,
              "vertexes": [
                127.10967543155922,
                37.40242613861426,
                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": 279,
              "type": 1,
              "guidance": "좌회전",
              "road_index": 2
            },
            {
              "name": "목적지",
              "x": 127.10824109988312,
              "y": 37.402415329497174,
              "distance": 128,
              "duration": 65,
              "type": 101,
              "guidance": "목적지",
              "road_index": -1
            }
          ]
        }
      ]
    }
  ]
}
코드가 숨겨졌습니다.

요청 응답에 대한 객체 정보는 다음과 같습니다.

표 4 응답 객체
Name Type Description Required
trans_id String 경로 요청 ID 필수
routes Object[] 경로 정보

alternatives가 true인 경우 한 개 이상의 경로 제공 가능		 필수
result_code Int 경로 탐색 결과 코드 필수
result_msg String 경로 탐색 결과 메시지 필수
summary Object 경로 요약 정보 필수
origin Object 출발지 정보 필수
name String 출발지 이름 필수
x Double X 좌표(경도) 필수
y Double Y 좌표(위도) 필수
destination Object 목적지 정보 필수
name String 목적지 이름 필수
x Double X 좌표(경도) 필수
y Double Y 좌표(위도) 필수
waypoints Object[] 경유지 정보 필수
name String 경유지 이름 필수
x Double X 좌표(경도) 필수
y Double Y 좌표(위도) 필수
priority String 경로 탐색 우선순위 옵션 필수
bound Object 모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box) 선택
min_x Double 바운딩 박스 왼쪽 하단의 X 좌표 필수
min_y Double 바운딩 박스 왼쪽 하단의 Y 좌표 필수
max_x Double 바운딩 박스 오른쪽 상단의 X 좌표 필수
max_y Double 바운딩 박스 오른쪽 상단의 Y 좌표 필수
fare Object 요금 정보 필수
taxi Int 택시 요금(원) 필수
toll Int 통행 요금(원) 필수
distance Int 전체 검색 결과 거리(미터) 필수
duration Int 목적지까지 소요 시간(초) 필수
sections Object[] 구간별 경로 정보

경유지가 존재할 경우 {경유지 수 + 1} 만큼의 섹션(경로 구간) 생성
(예: 경유지 수가 2개인 경우 총 3개의 섹션 정보가 생성,
section1: 출발지 → 경유지 1
section2: 경유지 1 → 경유지 2
section3: 경유지 2 → 목적지)		 필수
distance Int 섹션 거리(미터) 필수
duration Int 전체 검색 결과 이동 시간(초) 필수
bound Object 모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box)

summary가 false인 경우에만 제공		 선택
min_x Double 바운딩 박스 왼쪽 하단의 X 좌표 필수
min_y Double 바운딩 박스 왼쪽 하단의 Y 좌표 필수
max_x Double 바운딩 박스 오른쪽 상단의 X 좌표 필수
max_y Double 바운딩 박스 오른쪽 상단의 Y 좌표 필수
roads Object[] 도로 정보

summary가 false인 경우에만 제공		 선택
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] )		 필수
guides Object[] 안내 정보

summary가 false인 경우에만 제공		 선택
name String 명칭 필수
x Double X 좌표(경도) 필수
y Double Y 좌표(위도) 필수
distance Int 이전 가이드 지점부터 현재 가이드 지점까지 거리(미터) 필수
duration Int 이전 가이드 지점부터 현재 가이드 지점까지 시간(초) 필수
type Int 안내 타입 필수
guidance String 안내 문구 필수
road_index Int 현재 가이드에 대한 링크 인덱스 필수