Directions 15

Prev Next

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.

Request

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

Method URI
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.

Field Type Required Description
start String Required Origin (longitude, latitude)
  • <e.g.> start=127.12345,37.12345
goal String Required Destination (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
waypoints String Optional Waypoints (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
option String Optional Route 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
cartype Integer Optional Vehicle 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
fueltype String Optional Fuel type
  • gasoline (default) | highgradegasoline | diesel | lpg
    • gasoline: gasoline
    • highgradegasoline: high grade gasoline
    • diesel: diesel
    • lpg: LPG
  • Use to calculate fuel costs
mileage Double Optional Fuel efficiency
  • Enter when you want to set your own fuel efficiency for the vehicle you use
  • 14 (default)
lang String Optional Response 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-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}'

Response

The following describes the response format.

Response body

The following describes the response body.

Field Type Required Description
code Integer - Response code
message String - Response message
currentDateTime String - Route query date and time (yyyy-MM-ddTHH:mm:ss)
route Object - 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}.

Field Type Required Description
summary Object - Route summary information
summary.start Object - Origin information
summary.start.location Array - Origin coordinates (longitude, latitude)
summary.goal Object - Destination information
summary.goal.location Array - Destination coordinates (longitude, latitude)
summary.goal.dir Integer - 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.distance Integer - Total route distance (m)
summary.duration Integer - Total route duration (millisecond)
summary.departureTime String - Estimated arrival date and time (yyyy-MM-ddTHH:mm:ss)
summary.bbox Array - Entire route bounding area (Left Bottom Point, Right Top Point)
summary.tollFare Integer - Toll charges
summary.taxiFare Integer - Taxi charges
  • Calculations take into account factors that affect taxi fares: region, surcharges (late night, out-of-city, complex), and call charges
summary.fuelPrice Integer - Fuel costs
  • Calculations are based on national average gas prices and fuel efficiency at the time of route query
path Array - Coordinates that make up the route
  • Coordinates have a pointIndex starting at 0
  • Display all coordinates that make up the route
section Array - Major road information
  • Display information for a portion of the route with a long drive length based on street name
guide Array - Branch point guidance information

section

The following describes section.

Field Type Required Description
pointIndex Integer - Index of the coordinates that make up the route
pointCount Integer - Number of geometry points
distance Integer - Distance (m)
name String - 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
speed Integer - 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.

Code General road National road Urban expressway Expressway
Seamless 30 or higher 40 or higher 60 or higher 70 or higher
Slow 15~30 20~40 30~60 40~70
Congested Less than 15 Less than 20 Less than 30 Less than 40

guide

The following describes guide.

Field Type Required Description
pointIndex Integer - Index of the coordinates that make up the route
type Integer - Branch point guidance type
instructions String - Route instruction text
distance Integer - Distance (m) from the route construction coordinate index of the previous branch point to the route construction coordinate index of the current branch point
duration Integer - 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.

Code Description
1 Straight ahead
2 Turn left
3 Turn right
4 Left side
5 Right side
6 U-turn
8 Unprotected left turn
11 8 o'clock left
12 9 o'clock left
13 11 o'clock left
14 1 o'clock right
15 3 o'clock right
16 4 o'clock right
21 Straight ahead at the traffic circle
22 U-turn at the traffic circle
23 7 o'clock left at the traffic circle
24 8 o'clock left at the traffic circle
25 9 o'clock left at the traffic circle
26 10 o'clock left at the traffic circle
27 11 o'clock left at the traffic circle
28 12 o'clock at the traffic circle
29 1 o'clock right at the traffic circle
30 2 o'clock right at the traffic circle
31 3 o'clock right at the traffic circle
32 4 o'clock right at the traffic circle
33 5 o'clock right at the traffic circle
34 6 o'clock at the traffic circle
41 Enter the road on the left
42 Enter the road on the right
47 Enter the rest stop
48 Enter the ferry waterway
49 Exit the ferry waterway
50 Enter the expressway ahead
51 Exit the expressway ahead
52 Enter the urban expressway ahead
53 Exit the urban expressway ahead
54 Enter the branch road ahead
55 Enter the overpass ahead
56 Enter the underpass ahead
57 Enter the expressway on left
58 Exit the expressway on left
59 Enter the urban expressway on left
60 Exit the urban expressway on left
62 Enter the overpass on left
63 Enter the side street next to overpass on left
64 Enter the underpass on left
65 Enter the side street next to underpass on left
66 Enter the expressway on right
67 Exit the expressway on right
68 Enter the urban expressway on right
69 Exit the urban expressway on right
71 Enter the overpass on right
72 Enter the side street next to overpass on right
73 Enter the underpass on right
74 Enter the side street next to underpass on right
75 Enter the automobile-only road ahead
76 Enter the automobile-only road on left
77 Enter the automobile-only road on right
78 Exit the automobile-only road ahead
79 Exit the automobile-only road on left
80 Exit the automobile-only road on right
81 Merge onto main road on left
82 Merge onto main road on right
87 Waypoint
88 Destination
91 Straight ahead at the roundabout
92 U-turn at the roundabout
93 7 o'clock left at the roundabout
94 8 o'clock left at the roundabout
95 9 o'clock left at the roundabout
96 10 o'clock left at the roundabout
97 11 o'clock left at the roundabout
98 12 o'clock at the roundabout
99 1 o'clock right at the roundabout
100 2 o'clock right at the roundabout
101 3 o'clock right at the roundabout
102 4 o'clock right at the roundabout
103 5 o'clock right at the roundabout
104 6 o'clock at the roundabout
121 Tollgate
122 Hi-pass-only tollgate
123 One-tolling tollgate

Response status codes

The following describes the response status codes.

HTTP status code Code Message Description
200 0 - Request processing successful. Route finding success
200 1 - Request processing failed. Origin and destination are the same
200 2 - Request processing failed. Origin or destination isn't near a road
200 3 - Request processing failed. Unable to provide car directions results
200 4 - Request processing failed. Waypoint isn't near a road
200 5 - 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-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
                    ],
                    // (Omitted)
                    [
                        129.0762855,
                        35.1793190
                    ]
                ],
                "section": [
                    {
                        "pointIndex": 826,
                        "pointCount": 1430,
                        "distance": 151091,
                        "name": "Jungbu Naeryuk Expressway",
                        "congestion": 1,
                        "speed": 99
                    },
                    {
                        "pointIndex": 2255,
                        "pointCount": 564,
                        "distance": 61004,
                        "name": "Gyeongbu Expressway",
                        "congestion": 1,
                        "speed": 104
                    },
                    {
                        "pointIndex": 2818,
                        "pointCount": 827,
                        "distance": 82790,
                        "name": "Jungang Expressway (Busan - Daegu)",
                        "congestion": 1,
                        "speed": 102
                    }
                ],
                "guide": [
                    {
                        "pointIndex": 50,
                        "type": 3,
                        "instructions": "Turn right at Meonae Park intersection towards "Seobundang (Gogi) IC"",
                        "distance": 1075,
                        "duration": 284218
                    },
                    // (Omitted)
                    {
                        "pointIndex": 4054,
                        "type": 88,
                        "instructions": "Destination",
                        "distance": 904,
                        "duration": 107763
                    }
                ]
            }
        ]
    }
}