driving
    • PDF

    driving

    • PDF

    Article Summary

    개요

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

    요청

    curl "https://naveropenapi.apigw.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
    

    요청 파라미터

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

    • 별도의 정보가 없으면 거리의 단위는 meter, 시간의 단위는 millisecond(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

    • 필수 항목(경도, 위도)과 옵션 항목(이름)을 , 문자로 연결한 문자열입니다.
    • 옵션 항목은 항목에 맞는 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전체 경로 소요 시간(millisecond(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평균 속도(km/h)

    Guide Unit for Ent

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

    속성타입필수 여부설명
    pointIndexintY경로를 구성하는 좌표의 인덱스
    typeguide codeY안내 종류
    instructionsstringN안내 문구
    distanceintY이전 guide unit의 경로 구성 좌표 인덱스로부터 해당 guide unit의 경로 구성 좌표 인덱스까지의 거리(meters)
    durationintY이전 guide unit의 경로 구성 좌표 인덱스로부터 해당 guide unit의 경로 구성 좌표 인덱스까지의 소요 시간(millisecond(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 좌표를 바라보는 방향. 경유지와 목적지에 대해서만 존재 가능
    distanceintN출발지 또는 직전 경유지부터 해당 지점까지의 거리(meters). 경유지가 있는 경우, 경유지와 목적지에만 존재함
    durationintN출발지 또는 직전 경유지부터 해당 지점까지의 소요 시간(millisecond(1/1000초)). 경유지가 있는 경우, 경유지와 목적지에만 존재함
    pointIndexintN경로 상에서 해당 지점에 해당하는 좌표의 인덱스. 경유지가 있는 경우, 경유지와 목적지에만 존재함

    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전방에 고속도로 진출
    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회전교차로에서 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.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
    

    응답 예시

    {
        "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
                        }
                    ]
                }
            ]
        }
    }
    

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

    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.