MENU
      Directions 15 API

        Directions 15 API


        기사 요약

        VPC 환경에서 이용 가능합니다.

        입력한 정보(출발지, 경유지, 목적지 등)를 기반으로 자동차 경로 및 통행 정보(소요 시간, 거리, 예상 유류비, 통행 요금 정보, 분기점 안내)를 조회합니다.

        주의

        모든 경로는 실시간 교통 정보를 반영하므로 출발지, 목적지, 옵션이 동일하더라도 동일 경로를 보장하지 않습니다.

        요청

        요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

        메서드URI
        GET/driving

        요청 헤더

        Maps API에서 공통으로 사용하는 헤더에 대한 정보는 Maps 공통 헤더를 참조해 주십시오.

        요청 쿼리 파라미터

        요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        startStringRequired출발지(경도,위도)
        • <예시> start=127.12345,37.12345
        goalStringRequired목적지(경도,위도)
        • ':'로 구분하여 최대 10개의 목적지 입력 가능
        • 입력한 목적지 중 가장 적은 비용으로 도달할 수 있는 목적지에 대한 경로 조회
        • <예시> goal=123.45678,34.56789:124.56789,35.67890
        waypointsStringOptional경유지(경도,위도)
        • '| (Pipe char)'로 구분하여 최대 5개의 경유지 입력 가능
        • 동일 경유지의 좌표가 2개인 경우, ':'로 구분하여 입력
        • <예시> waypoints=127.12345,37.12345:127.23456,37.23456|128.12345,38.12345:128.23456,38.23456
        optionStringOptional경로 조회 옵션
        • ':'로 구분하여 최대 3개의 옵션 입력 가능
        • trafast | tracomfort | traoptimal (기본값) | traavoidtoll | traavoidcaronly
          • trafast: 실시간 빠른 길
          • tracomfort: 실시간 편한 길
          • traoptimal: 실시간 최적
          • traavoidtoll: 무료 우선
          • traavoidcaronly: 자동차 전용 도로 회피 우선
        cartypeIntegerOptional차량 타입
        • 1 (기본값) | 2 | 3 | 4 | 5 | 6
          • 1: 1종 소형차 2축 차량(윤폭 279.4 mm 이하 승용차, 소형 승합차, 소형 화물차)
          • 2: 2종 2축 차량(윤폭 279.4 mm 초과, 윤거 1,800 mm 이하 중형 승합차, 중형 화물차)
          • 3: 3종 대형차 2축 차량(윤폭 279.4 mm 초과, 윤거 1,800 mm 초과 대형 승합차, 2축 대형 화물차)
          • 4: 4종 3축 대형 화물차
          • 5: 5종 4축 이상 특수 화물차
          • 6: 1종 경형 자동차(배기량 1000 cc 미만으로 길이 3.6m, 너비 1.6 m, 높이 2.0 m 이하)
        • 일반적인 승용차는 모두 1 입력
        • 톨게이트 요금 계산에 활용되며, 차종에 따른 중량 또는 크기는 판단하지 않음
        fueltypeStringOptional연료 타입
        • gasoline (기본값) | highgradegasoline | diesel | lpg
          • gasoline: 휘발유
          • highgradegasoline: 고급 휘발유
          • diesel: 경유
          • lpg: LPG
        • 유류비 계산에 활용
        mileageDoubleOptional연비
        • 사용하는 차량의 연비를 직접 설정하고자 할 때 입력
        • 14 (기본값)
        langStringOptional응답 결과 언어
        • ko (기본값) | en | ja | zh
          • ko: 한국어
          • en: 영어
          • ja: 일본어
          • zh: 중국어 간체

        요청 예시

        요청 예시는 다음과 같습니다.

        curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-direction-15/v1/driving?start=127.1058342%2C37.359708&goal=129.075986%2C35.179470' \
        --header 'x-ncp-apigw-api-key-id: {API Key ID}' \
        --header 'x-ncp-apigw-api-key: {API Key}'
        Shell

        응답

        응답 형식을 설명합니다.

        응답 바디

        응답 바디에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        codeInteger-응답 코드
        messageString-응답 메시지
        currentDateTimeString-경로 조회 일시(yyyy-MM-ddTHH:mm:ss)
        routeObject-경로 조회 결과
        route.{option}Array-요청한 옵션에 따른 경로 정보
        • trafast | tracomfort | traoptimal | traavoidtoll | traavoidcaronly
          • trafast: 실시간 빠른 길
          • tracomfort: 실시간 편한 길
          • traoptimal: 실시간 최적
          • traavoidtoll: 무료 우선
          • traavoidcaronly: 자동차 전용 도로 회피 우선

        route.{option}

        route.{option}에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        summaryObject-경로 요약 정보
        summary.startObject-출발지 정보
        summary.start.locationArray-출발지 좌표(경도,위도)
        summary.goalObject-목적지 정보
        summary.goal.locationArray-목적지 좌표(경도,위도)
        summary.goal.dirInteger-경로상에서 location을 바라보는 방향
        • 경로상 진행 방향을 중심으로, 실제 경유지/도착지로 지정한 지점의 방향을 나타냄
        • 0 | 1 | 2
          • 0: 전방
          • 1: 왼쪽
          • 2: 오른쪽
        summary.distanceInteger-전체 경로 거리(m)
        summary.durationInteger-전체 경로 소요 시간(밀리초)
        summary.departureTimeString-예상 도착 일시(yyyy-MM-ddTHH:mm:ss)
        summary.bboxArray-전체 경로 경계 영역(Left Bottom Point, Right Top Point)
        summary.tollFareInteger-통행(톨게이트) 요금
        summary.taxiFareInteger-택시 요금
        • 택시 요금에 영향을 미치는 요소(지역, 할증(심야, 시계외, 복합), 콜비)를 감안하여 계산
        summary.fuelPriceInteger-유류비
        • 경로 조회 시점의 전국 평균 유류비와 연비를 감안하여 계산
        pathArray-경로를 구성하는 좌표
        • 좌표에는 0번부터 시작되는 pointIndex가 존재
        • 경로를 구성하는 모든 좌표 표시
        sectionArray-주요 도로 정보
        • 전체 경로 중 주행 길이가 긴 일부 경로의 정보를 도로 이름을 기준으로 표시
        guideArray-분기점 안내 정보

        section

        section에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        pointIndexInteger-경로를 구성하는 좌표의 인덱스
        pointCountInteger-형상점 수
        distanceInteger-거리(m)
        nameString-도로 이름
        congestion-혼잡도 분류 코드
        • 0 | 1 | 2 | 3
          • 0: 값없음
          • 1: 원활
          • 2: 서행
          • 3: 혼잡
        • 혼잡도에 대한 기준은 혼잡도 기준 참조
        speedInteger-평균 속도(km/h)

        혼잡도 기준


        혼잡도 기준은 다음과 같습니다.

        참고

        도로별 실시간 통행 속도를 기준으로 하며, 속도 단위는 km/h입니다.

        코드일반 도로국도도시고속고속도로
        원활30 이상40 이상60 이상70 이상
        서행15~3020~4030~6040~70
        혼잡15 미만20 미만30 미만40 미만

        guide

        guide에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        pointIndexInteger-경로를 구성하는 좌표의 인덱스
        typeInteger-분기점 안내 타입
        instructionsString-경로 안내 문구
        distanceInteger-이전 분기점의 경로 구성 좌표 인덱스로부터 해당 분기점의 경로 구성 좌표 인덱스까지의 거리(m)
        durationInteger-이전 분기점의 경로 구성 좌표 인덱스로부터 해당 분기점의 경로 구성 좌표 인덱스까지의 소요 시간(밀리초)

        분기점 안내 코드


        분기점 안내 코드에 대한 설명은 다음과 같습니다.

        코드설명
        1직진 방향
        2좌회전
        3우회전
        4왼쪽 방향
        5오른쪽 방향
        6유턴
        8비보호 좌회전
        11왼쪽 8시 방향
        12왼쪽 9시 방향
        13왼쪽 11시 방향
        14오른쪽 1시 방향
        15오른쪽 3시 방향
        16오른쪽 4시 방향
        21로터리에서 직진 방향
        22로터리에서 유턴
        23로터리에서 왼쪽 7시 방향
        24로터리에서 왼쪽 8시 방향
        25로터리에서 왼쪽 9시 방향
        26로터리에서 왼쪽 10시 방향
        27로터리에서 왼쪽 11시 방향
        28로터리에서 12시 방향
        29로터리에서 오른쪽 1시 방향
        30로터리에서 오른쪽 2시 방향
        31로터리에서 오른쪽 3시 방향
        32로터리에서 오른쪽 4시 방향
        33로터리에서 오른쪽 5시 방향
        34로터리에서 6시 방향
        41왼쪽 도로로 진입
        42오른쪽 도로로 진입
        47휴게소로 진입
        48페리항로 진입
        49페리항로 진출
        50전방에 고속도로 진입
        51전방에 고속도로 진출
        52전방에 도시 고속 도로 진입
        53전방에 도시 고속 도로 진출
        54전방에 분기 도로 진입
        55전방에 고가 차로 진입
        56전방에 지하 차도 진입
        57왼쪽에 고속 도로 진입
        58왼쪽에 고속 도로 진출
        59왼쪽에 도시 고속 도로 진입
        60왼쪽에 도시 고속 도로 진출
        62왼쪽에 고가 차도 진입
        63왼쪽에 고가 차도 옆길
        64왼쪽에 지하 차도 진입
        65왼쪽에 지하 차도 옆길
        66오른쪽에 고속 도로 진입
        67오른쪽에 고속 도로 진출
        68오른쪽에 도시 고속 도로 진입
        69오른쪽에 도시 고속 도로 진출
        71오른쪽에 고가 차도 진입
        72오른쪽에 고가 차도 옆길
        73오른쪽에 지하 차도 진입
        74오른쪽에 지하 차도 옆길
        75전방에 자동차 전용 도로 진입
        76왼쪽에 자동차 전용 도로 진입
        77오른쪽에 자동차 전용 도로 진입
        78전방에 자동차 전용 도로 진출
        79왼쪽에 자동차 전용 도로 진출
        80오른쪽에 자동차 천용 도로 진출
        81왼쪽에 본선으로 합류
        82오른쪽에 본선으로 합류
        87경유지
        88도착지
        91회전 교차로에서 직진 방향
        92회전 교차로에서 유턴
        93회전 교차로에서 왼쪽 7시 방향
        94회전 교차로에서 왼쪽 8시 방향
        95회전 교차로에서 왼쪽 9시 방향
        96회전 교차로에서 왼쪽 10시 방향
        97회전 교차로에서 왼쪽 11시 방향
        98회전 교차로에서 12시 방향
        99회전 교차로에서 오른쪽 1시 방향
        100회전 교차로에서 오른쪽 2시 방향
        101회전 교차로에서 오른쪽 3시 방향
        102회전 교차로에서 오른쪽 4시 방향
        103회전 교차로에서 오른쪽 5시 방향
        104회전 교차로에서 6시 방향
        121톨게이트
        122하이패스 전용 톨게이트
        123원톨링 톨게이트

        응답 상태 코드

        응답 상태 코드에 대한 설명은 다음과 같습니다.

        HTTP 상태 코드코드메시지설명
        2000-요청 처리 성공. 길 찾기 성공
        2001-요청 처리 실패. 출발지와 도착지가 동일함
        2002-요청 처리 실패. 출발지 또는 도착지가 도로 주변이 아님
        2003-요청 처리 실패. 자동차 길 찾기 결과 제공 불가
        2004-요청 처리 실패. 경유지가 도로 주변이 아님
        2005-요청 처리 실패. 경유지를 포함한 직선거리 합이 1500 km 이상인 경로가 요청됨
        참고

        Maps API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Maps 공통 응답 상태 코드를 참조해 주십시오.

        응답 예시

        응답 예시는 다음과 같습니다.

        {
            "code": 0,
            "message": "길찾기를 성공하였습니다.",
            "currentDateTime": "2024-08-27T17:17:21",
            "route": {
                "traoptimal": [
                    {
                        "summary": {
                            "start": {
                                "location": [
                                    127.1058342,
                                    37.3597080
                                ]
                            },
                            "goal": {
                                "location": [
                                    129.0759854,
                                    35.1794698
                                ],
                                "dir": 2
                            },
                            "distance": 378984,
                            "duration": 15213293,
                            "departureTime": "2024-08-27T17:17:20",
                            "bbox": [
                                [
                                    127.0999824,
                                    35.1793190
                                ],
                                [
                                    129.0817364,
                                    37.3940298
                                ]
                            ],
                            "tollFare": 19300,
                            "taxiFare": 348820,
                            "fuelPrice": 45283
                        },
                        "path": [
                            [
                                127.1059979,
                                37.3597094
                            ],
                            // (생략)
                            [
                                129.0762855,
                                35.1793190
                            ]
                        ],
                        "section": [
                            {
                                "pointIndex": 826,
                                "pointCount": 1430,
                                "distance": 151091,
                                "name": "중부내륙고속도로",
                                "congestion": 1,
                                "speed": 99
                            },
                            {
                                "pointIndex": 2255,
                                "pointCount": 564,
                                "distance": 61004,
                                "name": "경부고속도로",
                                "congestion": 1,
                                "speed": 104
                            },
                            {
                                "pointIndex": 2818,
                                "pointCount": 827,
                                "distance": 82790,
                                "name": "중앙고속도로(부산-대구)",
                                "congestion": 1,
                                "speed": 102
                            }
                        ],
                        "guide": [
                            {
                                "pointIndex": 50,
                                "type": 3,
                                "instructions": "머내공원사거리에서 '서분당(고기)IC' 방면으로 우회전",
                                "distance": 1075,
                                "duration": 284218
                            },
                            // (생략)
                            {
                                "pointIndex": 4054,
                                "type": 88,
                                "instructions": "목적지",
                                "distance": 904,
                                "duration": 107763
                            }
                        ]
                    }
                ]
            }
        }
        JSON

        이 문서가 도움이 되었습니까?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.