MENU
      driving

        driving


        기사 요약

        개요

        길찾기 API는 지도 앱 메인 화면에서 주요 지역까지의 소요 시간과 거리, 예상 유류비, 통행 요금 정보를 제공합니다.
        그리고 경로상 분기점에서 안내가 필요한 경우 해당 지점에서의 guide code를 제공합니다.

        요청

        curl "https://naveropenapi.apigw.gov-ntruss.com/map-direction/v1/driving?start={출발지}&goal={목적지}&option={탐색옵션}" \
        	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
        	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
        Shell

        요청 파라미터

        길찾기 API의 쿼리 스트링 파라미터에 공통으로 해당되는 내용입니다.

        • 별도의 정보가 없으면 거리의 단위는 meter, 시간의 단위는 milisecond(1/1000초)를 사용합니다.
        • 문자열 인코딩은 UTF-8을 사용합니다.
        파라미터타입필수 여부설명
        startrequest position formatY출발지
        goalmultiple request position formatY- 목적지
        하나 이상의 목적지 정보를 전달할 수 있으며, 복수 개의 목적지를 입력할 때는 :로 연결
        입력한 목적지 정보 중 가장 적은 비용으로 도달할 수 있는 목적지로 경로가 생성됨
        목적지의 최대 개수는 10개이며, 최초의 최적 목적지 좌표를 기준으로 직선거리 3km 이내의 좌표만 유효하게 판정
        waypointsmultiple request position format listN- 경유지
        최대 5개를 입력할 수 있으며 서로 다른 경유지의 구분자로 |(pipe char)를 사용
        optionoption codeN- 탐색 옵션
        옵션은 최대 3개까지 동시에 요청할 수 있으며, 여러 옵션은 ‘:'로 연결
        기본값은 traoptimal
        cartypecartype codeN- 톨게이트 요금 계산용 차종 정보
        기본값은 1이며 차종을 바탕으로 차량의 중량 또는 크기를 판단하지는 않음
        3, 4, 5종은 option에서 traavoidtoll이 적용되지 않았더라도 하이패스 전용 톨게이트를 회피해서 탐색함
        일반적인 승용차는 모두 1종
        fueltypefueltype codeN유류비 계산용 유종 (기본값은 gasoline)
        mileagedoubleN- 설정된 유류에 해당하는 연비
        사용하는 차량의 연비를 사용자가 직접 입력하고자 할 때 사용하는 파라미터
        기본값은 14
        langlang string codeN언어 종류 (기본값은 ko)

        Request Position Format

        • 필수 항목(경도, 위도)과 옵션 항목(이름, 지점 ID)을 , 문자로 연결한 문자열입니다.
        • 옵션 항목은 항목에 맞는 prefix가 필요합니다.
        • 옵션 항목값은 ,, : 또는 | 문자를 포함할 수 없습니다.
        • 숫자가 아닌 문자는 URL 인코딩이 필요합니다.
        • 옵션 항목 간의 순서는 상관 없습니다.

        다음은 request position format의 사용 예입니다.

        • 기본 예: 127.12345,37.12345
        • 이름 옵션 항목을 추가한 예: 127.12345,37.12345,name=출발지이름

        Multiple Request Position Format

        request position format 여러 개를 : 문자로 연결한 문자열입니다.

        • waypoints의 각 항목은 독립적인 경유지이므로 name을 사용한 여러 개의 request position format을 사용할 수 있습니다.
          • waypoints 예 1: 127.12345,37.12345:128.12345,38.12345
          • waypoints 예 2: 127.12345,37.12345:128.12345,38.12345,name=장소이름1
          • waypoints 예 3: 127.12345,37.12345,name=장소이름1:128.12345,38.12345,name=장소이름2

        Multiple Request Position Format list

        multiple request position format 여러 개를 | 문자로 연결한 리스트 문자열입니다. 경유지 파라미터인 waypoints가 이 형식을 사용합니다.

        • 경유지가 두 개이고 각 경유지에 좌표가 두 개씩 있는 경우의 예: 127.12345,37.12345:127.23456,37.23456|128.12345,38.12345:128.23456,38.23456

        Cartype Code

        톨게이트 요금 계산용 차종 정보를 나타내는 코드입니다.

        코드설명
        11종(소형차) 2축 차량. 윤폭 279.4mm 이하 승용차, 소형승합차, 소형화물차
        22종(중형차) 2축 차량. 윤폭 279.4mm 초과, 윤거 1,800mm 이하 중형승합차, 중형화물차
        33종(대형차) 2축 차량. 윤폭 279.4mm 초과, 윤거 1,800mm 초과 대형승합차, 2축 대형화물차
        44종(대형화물차) 3축 대형화물차
        55종(특수화물차) 4축 이상 특수화물차
        61종(경형자동차) 배기량 1000cc 미만으로 길이 3.6m, 너비 1.6m, 높이 2.0m 이하

        Fueltype Code

        유류비 계산용 유종을 나타내는 코드입니다.

        스트링 코드설명
        gasoline휘발유. 유류비 계산 시 사용
        highgradegasoline고급 휘발유. 유류비 계산 시 사용
        diesel경유. 유류비 계산 시 사용
        lpgLPG. 유류비 계산 시 사용

        Option Code

        탐색 옵션을 나타내는 코드입니다.(모든 경로는 교통정보를 반영하므로 출발지, 목적지, 옵션이 같더라도 같은 경로가 보장되지 않습니다.)

        스트링 코드탐색 종류
        trafast실시간 빠른길
        tracomfort실시간 편한길
        traoptimal실시간 최적
        traavoidtoll무료 우선
        traavoidcaronly자동차 전용도로 회피 우선

        Language Code

        지원되는 언어 종류를 나타내는 코드입니다.

        스트링 코드설명
        ko한국어
        en영어
        ja일본어
        zh중국어 간체

        요청 헤더

        헤더 명설명
        X-NCP-APIGW-API-KEY-ID앱 등록 시 발급받은 Client ID X-NCP-APIGW-API-KEY-ID:{Client ID}
        X-NCP-APIGW-API-KEY앱 등록 시 발급 받은 Client Secret X-NCP-APIGW-API-KEY:{Client Secret}

        요청 바디

        • 해당 API 는 요청 바디를 필요로 하지 않습니다.

        응답

        응답 바디

        하위 구조체는 Object로 표현하며, route 내 각 항목의 속성은 일반적인 key-value 쌍("key": "value")으로 표현합니다.

        속성타입필수 여부설명
        coderesult codeY응답 결과 코드
        messgestringY응답 결과 문자열
        currentDateTimestringY탐색 시점 시간 정보. ISO datetime format 사용
        routekey: option code
        value: route unit ent array
        Y응답결과

        Route Unit Ent

        경로 안내를 위한 속성들의 대분류를 나타냅니다.

        속성타입필수 여부설명
        summarysummaryY요약 정보
        pathlng-lat position format arrayY- 경로를 구성하는 모든 좌표열
        해당 좌표들에는 0번부터 시작되는 index가 있으며, 이 index는 경로 정보를 표현하기 위한 pointIndex라는 명칭으로 활용됨
        sectionsection unitN해당 경로를 구성하는 주요 도로에 관한 정보열(모든 경로를 포함하는 정보는 아님)
        guideguide unit for ent arrayN안내 정보열

        Summary

        탐색된 경로의 요약 정보를 나타냅니다.

        속성타입필수 여부설명
        startresponse position formatY출발지
        goalresponse position formatY목적지
        waypointsresponse position format arrayN경유지(경유하는 순서대로 array에 기록)
        distanceintY전체 경로 거리(meters)
        durationintY전체 경로 소요 시간(milisecond(1/1000초))
        bboxlenth 2인 lng-lat position arrayY전체 경로 경계 영역. left bottom point와 right top point 두 개의 point array로 제공
        tollFareintY통행 요금(톨게이트)
        taxiFareintY택시 요금(지자체별, 심야, 시경계, 복합, 콜비 감안)
        fuelPriceintY해당 시점의 전국 평균 유류비와 연비를 감안한 유류비

        Section Unit

        탐색된 경로 중 주요 도로의 정보를 나타냅니다. 도로명을 기준으로 주행 길이가 긴 경로의 정보입니다.

        속성타입필수 여부설명
        pointIndexintY경로를 구성하는 좌표의 인덱스
        pointCountintY형상점 수
        distanceintY거리(meters)
        namestringY도로명
        congestioncongestion codeN구간 혼잡도
        speedintN평균 속도

        Guide Unit for Ent

        회전 안내가 필요한 지점과 회전 안내까지의 거리 정보를 제공합니다.

        속성타입필수 여부설명
        pointIndexintY경로를 구성하는 좌표의 인덱스
        typeguide codeY안내 종류
        instructionsstringN안내 문구
        distanceintY이전 guide unit의 경로 구성 좌표 인덱스로부터 해당 guide unit의 경로 구성 좌표 인덱스까지의 거리(meters)
        durationintY이전 guide unit의 경로 구성 좌표 인덱스로부터 해당 guide unit의 경로 구성 좌표 인덱스까지의 소요 시간(milisecond(1/1000초))

        Result Code

        ResultCode가 0이 아니면 탐색 실패입니다.

        HttpStatusCodeResultCodeResultMessage설명
        2000-길찾기 성공
        2001-출발지와 도착지가 동일
        2002-출발지 또는 도착지가 도로 주변이 아닌 경우
        2003-자동차 길찾기 결과 제공 불가
        2004-경유지가 도로 주변이 아닌 경우
        2005-요청 경로가 매우 긴 경우(경유지를 포함한 직선거리의 합이 1500km이상인 경우)

        lng-lat Position Format

        경도, 위도로 된 좌표 정보를 나타냅니다. Length 2인 1차원 배열로, 경도, 위도 순서로 제공합니다(lng, lat).

        예: [127.001122, 37.001122]

        Response Position Format

        출발지, 도착지, 경유지의 좌표 정보를 제공합니다.

        속성타입필수 여부설명
        locationlng-lat positionY지점
        dirview direction codeN경로상에서 location 좌표를 바라보는 방향. 경유지와 목적지에 대해서만 존재 가능

        View Direction Code

        경로상의 도착지/경유지에서 실제 도착지/경유지로 지정한 지점의 방향을 나타냅니다. 경로상 진행 방향 중심으로 방향을 지정합니다.

        코드설명
        0전방
        1왼쪽
        2오른쪽

        Guide Code

        경로상 회전이 발생하거나 추가 안내가 필요한 지점에서 어떻게 진행할지 안내합니다.

        코드설명
        1직진 방향
        2좌회전
        3우회전
        4왼쪽 방향
        5오른쪽 방향
        6U턴
        8비보호 좌회전
        11왼쪽 8시 방향
        12왼쪽 9시 방향
        13왼쪽 11시 방향
        14오른쪽 1시 방향
        15오른쪽 3시 방향
        16오른쪽 4시 방향
        21로터리에서 직진 방향
        22로터리에서 U턴
        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전방에 고속도로 진출
        54전방에 분기도로 진입
        55전방에 고가차로 진입
        56전방에 지하차도 진입
        57왼쪽에 고속도로 진입
        58왼쪽에 고속도로 진출
        62왼쪽에 고가차도 진입
        63왼쪽에 고가차도 옆길
        64왼쪽에 지하차도 진입
        65왼쪽에 지하차도 옆길
        66오른쪽에 고속도로 진입
        67오른쪽에 고속도로 진출
        71오른쪽에 고가차로 진입
        72오른쪽에 고가차도 옆길
        73오른쪽에 지하차도 진입
        74오른쪽에 지하차도 옆길
        81왼쪽에 본선으로 합류
        82오른쪽에 본선으로 합류
        87경유지
        88도착지
        91회전교차로에서 직진 방향
        92회전교차로에서 U턴
        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원톨링 톨게이트

        Congestion code

        도로의 종별 및 실제 통행 속도 정보를 이용해 추정한 혼잡도 분류 코드입니다.

        코드설명
        0값 없음
        1원활
        2서행
        3혼잡

        다음은 혼잡도를 기준으로 도로 종별 통행 속도를 나타낸 표입니다.

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

        예시

        요청 예시

        curl "https://naveropenapi.apigw.gov-ntruss.com/map-direction/v1/driving?start=127.1058342,37.359708&goal=129.075986,35.179470&option=trafast" \
        	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
        	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
        Shell

        응답 예시

        {
            "code": 0,
            "message": "길찾기를 성공하였습니다.",
            "currentDateTime": "2018-12-21T14:45:34",
            "route": {
                "trafast": [
                    {
                        "summary": {
                            "start": {
                                "location": [
                                    127.1058342,
                                    37.3597078
                                ]
                            },
                            "goal": {
                                "location": [
                                    129.0759853,
                                    35.1794697
                                ],
                                "dir": 2
                            },
                            "distance": 382403,
                            "duration": 15372873,
                            "bbox": [
                                [
                                    127.0833901,
                                    35.1793188
                                ],
                                [
                                    129.0817364,
                                    37.3599059
                                ]
                            ],
                            "tollFare": 24500,
                            "taxiFare": 319900,
                            "fuelPrice": 46027
                        },
                        "path": [
                            [
                                127.1059968,
                                37.3597093
                            ],
        
                            ....
        
                            [
                                129.0764276,
                                35.1795108
                            ],
                            [
                                129.0762855,
                                35.1793188
                            ]
                        ],
                        "section": [
                            {
                                "pointIndex": 654,
                                "pointCount": 358,
                                "distance": 22495,
                                "name": "죽양대로",
                                "congestion": 1,
                                "speed": 60
                            },
                            {
                                "pointIndex": 3059,
                                "pointCount": 565,
                                "distance": 59030,
                                "name": "낙동대로",
                                "congestion": 1,
                                "speed": 89
                            },
                            {
                                "pointIndex": 4708,
                                "pointCount": 433,
                                "distance": 23385,
                                "name": "새마을로",
                                "congestion": 1,
                                "speed": 66
                            }
                        ],
                        "guide": [
                            {
                                "pointIndex": 1,
                                "type": 3,
                                "instructions": "정자일로1사거리에서 '성남대로' 방면으로 우회전",
                                "distance": 21,
                                "duration": 4725
                            },
                            {
                                "pointIndex": 8,
                                "type": 3,
                                "instructions": "불정교사거리에서 '수원·용인, 미금역' 방면으로 우회전",
                                "distance": 186,
                                "duration": 42914
                            },
        
         					....
        
                            {
                                "pointIndex": 6824,
                                "type": 14,
                                "instructions": "연산교차로에서 '서면교차로, 시청·경찰청' 방면으로 오른쪽 1시 방향",
                                "distance": 910,
                                "duration": 125240
                            },
                            {
                                "pointIndex": 6842,
                                "type": 88,
                                "instructions": "목적지",
                                "distance": 895,
                                "duration": 111333
                            }
                        ]
                    }
                ]
            }
        }
        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.