MENU
      Directions 5 API

        Directions 5 API


        Article summary

        Available in VPC

        Get driving directions and traffic information (duration, distance, estimated gas cost, toll information, and branch points) based on the entered information (origin, waypoints, destination, etc.).

        Caution

        All routes reflect real-time traffic information, so even if you have the same origin, destination, and options, we don't guarantee the same route.

        Note

        The Directions 5 API allows you to enter up to five waypoints. To enter more waypoints, see Directions 15 API.

        Request

        The following describes the request format for the endpoint. The request format is as follows:

        MethodURI
        GET/driving

        Request headers

        For headers common to all Maps APIs, see Common Maps headers.

        Request query parameters

        The following describes the request query parameters.

        FieldTypeRequiredDescription
        startStringRequiredOrigin (longitude, latitude)
        • <e.g.> start=127.12345,37.12345
        goalStringRequiredDestination (longitude, latitude)
        • Up to 10 destinations can be entered, separated by ":"
        • Among destinations entered, get the route to the destination that can be reached for the least cost
        • <e.g.> goal=123.45678,34.56789:124.56789,35.67890
        waypointsStringOptionalWaypoints (longitude, latitude)
        • Up to 5 waypoints can be entered, separated by "| (pipe char)"
        • If there are two coordinates for the same waypoint, enter them separated by ":"
        • <e.g.> waypoints=127.12345,37.12345:127.23456,37.23456\|128.12345,38.12345:128.23456,38.23456
        optionStringOptionalRoute query options
        • Up to 3 options can be entered, separated by ":"
        • trafast | tracomfort | traoptimal (default) | traavoidtoll | traavoidcaronly
          • trafast: real-time fast routes
          • tracomfort: real-time comfortable routes
          • traoptimal: real-time optimal
          • traavoidtoll: prioritize free
          • traavoidcaronly: prioritize avoiding roads dedicated to cars
        cartypeIntegerOptionalVehicle type
        • 1 (default) | 2 | 3 | 4 | 5 | 6
          • 1: class 1 small two-axle vehicles (passenger cars, small vans, small cargo vehicles with a tire width of 279.4 mm or less)
          • 2: class 2 two-axle vehicles (tire width greater than 279.4 mm, track length less than or equal to 1800 mm, medium-sized vans, medium-sized cargo vehicles)
          • 3: class 3 large two-axle vehicles (tire width greater than 279. 4 mm, track length over 1800 mm, large passenger vans, 2 axle large cargo vehicles)
          • 4: class 4 3-axle large cargo vehicles
          • 5: class 5 4-axle or more special cargo vehicles
          • 6: class 1 light vehicles (displacement less than 1000 cc, less than 3.6 m in length, 1.6 m in width, and 2.0 m in height)
        • Enter 1 for all general passenger cars
        • It is used to calculate toll, and doesn't determine the weight or size based on the type of vehicle
        fueltypeStringOptionalFuel type
        • gasoline (default) | highgradegasoline | diesel | lpg
          • gasoline: gasoline
          • highgradegasoline: high grade gasoline
          • diesel: diesel
          • lpg: LPG
        • Use to calculate fuel costs
        mileageDoubleOptionalFuel efficiency
        • Enter when you want to set your own fuel efficiency for the vehicle you use
        • 14 (default)
        langStringOptionalResponse result language
        • ko (default) | en | ja | zh
          • ko: Korean
          • en: English
          • ja: Japanese
          • zh: Chinese (Simplified)

        Request example

        The following is a sample request.

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

        Response

        The following describes the response format.

        Response body

        The following describes the response body.

        FieldTypeRequiredDescription
        codeInteger-Response code
        messageString-Response message
        currentDateTimeString-Route query date and time (yyyy-MM-ddTHH:mm:ss)
        routeObject-Route query result
        route.{option}Array-Route information based on requested options
        • trafast | tracomfort | traoptimal | traavoidtoll | traavoidcaronly
          • trafast: real-time fast routes
          • tracomfort: real-time comfortable routes
          • traoptimal: real-time optimal
          • traavoidtoll: prioritize free
          • traavoidcaronly: prioritize avoiding roads dedicated to cars

        route.{option}

        The following describes route.{option}.

        FieldTypeRequiredDescription
        summaryObject-Route summary information
        summary.startObject-Origin information
        summary.start.locationArray-Origin coordinates (longitude, latitude)
        summary.goalObject-Destination information
        summary.goal.locationArray-Destination coordinates (longitude, latitude)
        summary.goal.dirInteger-Direction facing location on the route
        • It represents the direction of the actual waypoint/destination, centered on the direction of travel along the route
        • 0 | 1 | 2
          • 0: front
          • 1: left
          • 2: right
        summary.distanceInteger-Total route distance (m)
        summary.durationInteger-Total route duration (millisecond)
        summary.departureTimeString-Estimated arrival date and time (yyyy-MM-ddTHH:mm:ss)
        summary.bboxArray-Entire route bounding area (Left Bottom Point, Right Top Point)
        summary.tollFareInteger-Toll charges
        summary.taxiFareInteger-Taxi charges
        • Calculations take into account factors that affect taxi fares: region, surcharges (late night, out-of-city, complex), and call charges
        summary.fuelPriceInteger-Fuel costs
        • Calculations are based on national average gas prices and fuel efficiency at the time of route query
        pathArray-Coordinates that make up the route
        • Coordinates have a pointIndex starting at 0
        • Display all coordinates that make up the route
        sectionArray-Major road information
        • Display information for a portion of the route with a long drive length based on street name
        guideArray-Branch point guidance information

        section

        The following describes section.

        FieldTypeRequiredDescription
        pointIndexInteger-Index of the coordinates that make up the route
        pointCountInteger-Number of geometry points
        distanceInteger-Distance (m)
        nameString-Street name
        congestion-Congestion classification code
        • 0 | 1 | 2 | 3
          • 0: no value
          • 1: seamless
          • 2: slow
          • 3: congested
        • For criteria of congestion, see Congestion criteria
        speedInteger-Average speed (km/h)

        Congestion criteria


        The congestion criteria are as follows.

        Note

        It is based on real-time traffic speeds by road, with speed units in km/h.

        CodeGeneral roadNational roadUrban expresswayExpressway
        Seamless30 or higher40 or higher60 or higher70 or higher
        Slow15~3020~4030~6040~70
        CongestedLess than 15Less than 20Less than 30Less than 40

        guide

        The following describes guide.

        FieldTypeRequiredDescription
        pointIndexInteger-Index of the coordinates that make up the route
        typeInteger-Branch point guidance type
        instructionsString-Route instruction text
        distanceInteger-Distance (m) from the route construction coordinate index of the previous branch point to the route construction coordinate index of the current branch point
        durationInteger-Duration (millisecond) from the route construction coordinate index of the previous branch point to the route construction coordinate index of the current branch point

        Branch point guidance code


        The following describes the branch point guidance codes.

        CodeDescription
        1Straight ahead
        2Turn left
        3Turn right
        4Left side
        5Right side
        6U-turn
        8Unprotected left turn
        118 o'clock left
        129 o'clock left
        1311 o'clock left
        141 o'clock right
        153 o'clock right
        164 o'clock right
        21Straight ahead at the traffic circle
        22U-turn at the traffic circle
        237 o'clock left at the traffic circle
        248 o'clock left at the traffic circle
        259 o'clock left at the traffic circle
        2610 o'clock left at the traffic circle
        2711 o'clock left at the traffic circle
        2812 o'clock at the traffic circle
        291 o'clock right at the traffic circle
        302 o'clock right at the traffic circle
        313 o'clock right at the traffic circle
        324 o'clock right at the traffic circle
        335 o'clock right at the traffic circle
        346 o'clock at the traffic circle
        41Enter the road on the left
        42Enter the road on the right
        47Enter the rest stop
        48Enter the ferry waterway
        49Exit the ferry waterway
        50Enter the expressway ahead
        51Exit the expressway ahead
        52Enter the urban expressway ahead
        53Exit the urban expressway ahead
        54Enter the branch road ahead
        55Enter the overpass ahead
        56Enter the underpass ahead
        57Enter the expressway on left
        58Exit the expressway on left
        59Enter the urban expressway on left
        60Exit the urban expressway on left
        62Enter the overpass on left
        63Enter the side street next to overpass on left
        64Enter the underpass on left
        65Enter the side street next to underpass on left
        66Enter the expressway on right
        67Exit the expressway on right
        68Enter the urban expressway on right
        69Exit the urban expressway on right
        71Enter the overpass on right
        72Enter the side street next to overpass on right
        73Enter the underpass on right
        74Enter the side street next to underpass on right
        75Enter the automobile-only road ahead
        76Enter the automobile-only road on left
        77Enter the automobile-only road on right
        78Exit the automobile-only road ahead
        79Exit the automobile-only road on left
        80Exit the automobile-only road on right
        81Merge onto main road on left
        82Merge onto main road on right
        87Waypoint
        88Destination
        91Straight ahead at the roundabout
        92U-turn at the roundabout
        937 o'clock left at the roundabout
        948 o'clock left at the roundabout
        959 o'clock left at the roundabout
        9610 o'clock left at the roundabout
        9711 o'clock left at the roundabout
        9812 o'clock at the roundabout
        991 o'clock right at the roundabout
        1002 o'clock right at the roundabout
        1013 o'clock right at the roundabout
        1024 o'clock right at the roundabout
        1035 o'clock right at the roundabout
        1046 o'clock at the roundabout
        121Tollgate
        122Hi-pass-only tollgate
        123One-tolling tollgate

        Response status codes

        The following describes the response status codes.

        HTTP status codeCodeMessageDescription
        2000-Request processing successful. Route finding success
        2001-Request processing failed. Origin and destination are the same
        2002-Request processing failed. Origin or destination isn't near a road
        2003-Request processing failed. Unable to provide car directions results
        2004-Request processing failed. Waypoint isn't near a road
        2005-Request processing failed. A route is requested with a total straight-line distance of 1500 km or more, including waypoints
        Note

        For response status codes common to all Maps APIs, see Common Maps response status codes.

        Response example

        The following is a sample example.

        {
            "code": 0,
            "message": "Route finding succeeded.",
            "currentDateTime": "2024-09-03T14:39:25",
            "route": {
                "traoptimal": [
                    {
                        "summary": {
                            "start": {
                                "location": [
                                    127.1058342,
                                    37.3597080
                                ]
                            },
                            "goal": {
                                "location": [
                                    129.0759854,
                                    35.1794698
                                ],
                                "dir": 2
                            },
                            "distance": 380044,
                            "duration": 15856847,
                            "departureTime": "2024-09-03T14:39:24",
                            "bbox": [
                                [
                                    127.0833901,
                                    35.1793190
                                ],
                                [
                                    129.1969372,
                                    37.3597094
                                ]
                            ],
                            "tollFare": 21000,
                            "taxiFare": 352360,
                            "fuelPrice": 45056
                        },
                        "path": [
                            [
                                127.1059979,
                                37.3597094
                            ],
                            // (Omitted)
                            [
                                129.0762855,
                                35.1793190
                            ]
                        ],
                        "section": [
                            {
                                "pointIndex": 315,
                                "pointCount": 1018,
                                "distance": 95575,
                                "name": "Gyeongbu Expressway",
                                "congestion": 1,
                                "speed": 83
                            },
                            {
                                "pointIndex": 2157,
                                "pointCount": 812,
                                "distance": 92508,
                                "name": "Sangju–Yeongcheon Expressway",
                                "congestion": 1,
                                "speed": 108
                            },
                            {
                                "pointIndex": 2968,
                                "pointCount": 833,
                                "distance": 89391,
                                "name": "Gyeongbu Expressway",
                                "congestion": 1,
                                "speed": 106
                            }
                        ],
                        "guide": [
                            {
                                "pointIndex": 50,
                                "type": 3,
                                "instructions": "Turn right at Meonae Park intersection towards "Seobundang (Gogi) IC"",
                                "distance": 1075,
                                "duration": 262406
                            },
                            // (Omitted)
                            {
                                "pointIndex": 4065,
                                "type": 88,
                                "instructions": "Destination",
                                "distance": 904,
                                "duration": 147960
                            }
                        ]
                    }
                ]
            }
        }
        JSON

        Was this article helpful?

        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.