Directions 5 API

English

Directions 5 API

Article summary

Did you find this summary helpful?

Thank you for your feedback

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:

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/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

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 See Branch point guidance code
`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-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
                    }
                ]
            }
        ]
    }
}

Was this article helpful?

What's Next

Directions 15 API

Table of contents

Request
Response