Directions 5

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.

Note

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

Request

This section describes the request format. The method and URI are as follows:

Method URI
GET /driving

Request headers

For information about the headers common to all Maps APIs, see Common Maps headers.

Request query parameters

You can use the following query parameters with your request:

Field Type Required Description
start String Required Origin (longitude, latitude)
  • Example: 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.
  • Example: 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 ":".
  • Example: 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 request example is as follows:

curl --location --request GET 'https://maps.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}'

Response

This section describes the response format.

Response body

The response body includes the following data:

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 information about the HTTP status codes common to all Maps APIs, see Common Maps response status codes.

Response example

The response example is as follows:

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