driving

Overview

The route search API provides information on the time duration and distance between key locations on the main screen of the map app, along with estimates for fuel costs and toll fares.
If guidance is needed at a junction on the route, it provides a guide code at the location.

Requests

curl "https://naveropenapi.apigw.ntruss.com/map-direction/v1/driving?start={Origin}&goal={Destination}&option={Navigation Options}" \
	-H "X-NCP-APIGW-API-KEY-ID: {Client ID value issued at application registration}" \
	-H "X-NCP-APIGW-API-KEY: {Client secret value issued at application registration}" -v

Request parameters

The following apply universally to the query string parameters of the route search API.

• If specific information is not available, use meters for the distance unit and milliseconds (1/1000 second) for the time unit.
• Use UTF-8 for the string encoding.

Request Position Format

• Strings that connect required items (longitude, latitude) and optional items (name) with , character.
• The optional items require an appropriate prefix for each item.
• The optional item values cannot contain characters ,, : or |.
• URL encoding is required for non-numeric characters.
• The order between option items does not matter.

The following are examples using the request position format:

• Basic example: 127.12345,37.12345
• Example with added name option items: 127.12345,37.12345,name=출발지이름

Multiple Request Position Format

Strings that connect multiple request position format with : character.

• Each item of waypoints is an independent waypoint, so multiple request position format with name can be used.
  • waypoints Example 1: 127.12345,37.12345:128.12345,38.12345
  • waypoints Example 2: 127.12345,37.12345:128.12345,38.12345,name=장소이름1
  • waypoints Example 3: 127.12345,37.12345,name=장소이름1:128.12345,38.12345,name=장소이름2

Multiple Request Position Format list

List strings that connect multiple request position format with | character. The waypoints parameter waypoints uses this format.

• An example where there are two waypoints, and each waypoint has two coordinates: 127.12345,37.12345:127.23456,37.23456|128.12345,38.12345:128.23456,38.23456

Cartype Code

Represents vehicle type information for calculating toll fares.

Fueltype Code

Represents the fuel type used for calculating fuel cost.

Option Code

Represents navigation options. (Since all routes reflect traffic information, even if the origin, destination, and options are the same, the same route is not guaranteed.)

Language Code

Refers to the supported language types.

Request Headers

Request Bodies

• This API does not require request bodies.

Responses

Response Bodies

The substructure is represented as an object, and the properties of each item in the route are expressed as general key-value pairs ("key": "value").

Route Unit Ent

Represents the major category of properties for route guidance.

Summary

Represents the summary of information on the searched routes.

Section Unit

Represents the information on the major roads among searched routes. Information on the route with a long driving distance based on the road name.

Guide Unit for Ent

Provides the information on the location requiring turn guidance and the distance to the turn guidance.

Result Code

If the ResultCode is not 0, the navigation fails.

lng-lat Position Format

Represents the coordinate information in longitude and latitude. A one-dimensional array with a length of 2. This is provided in the order of longitude and latitude (lng, lat).

E.g., [127.001122, 37.001122]

Response Position Format

Provides the coordinate information in origin, destination, and waypoints.

View Direction Code

Represents the direction of the locations specified as the actual destination/waypoints from the destination/waypoints on the route. Specifies the direction based on the moving direction on the route.

Guide Code

Guidance on how to proceed at locations where a turn occurs on the route or additional guidances are needed.

Congestion code

Represents a classification code for congestion estimated using the information on road type and actual travel speed.

The following is the table representing travel speed for each road type based on congestion:

Examples

Request Examples

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 value issued at application registration}" \
	-H "X-NCP-APIGW-API-KEY: {Client secret value issued at application registration}" -v

Response Examples

{
    "code": 0,
    "message": "The route search was successful.",
    "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": "Jukyang-daero",
                        "congestion": 1,
                        "speed": 60
                    },
                    {
                        "pointIndex": 3059,
                        "pointCount": 565,
                        "distance": 59030,
                        "name": "Nakdong-daero",
                        "congestion": 1,
                        "speed": 89
                    },
                    {
                        "pointIndex": 4708,
                        "pointCount": 433,
                        "distance": 23385,
                        "name": "Saemaeul-ro",
                        "congestion": 1,
                        "speed": 66
                    }
                ],
                "guide": [
                    {
                        "pointIndex": 1,
                        "type": 3,
                        "instructions": "Turn right from Jeongjail-ro 1 intersection towards Seongnam-daero",
                        "distance": 21,
                        "duration": 4725
                    },
                    {
                        "pointIndex": 8,
                        "type": 3,
                        "instructions": "Turn right from Buljeonggyo Intersection towards Suwon·Yongin, Migeum Subway Station",
                        "distance": 186,
                        "duration": 42914
                    },

 					....

                    {
                        "pointIndex": 6824,
                        "type": 14,
                        "instructions": "From Yeonsan Intersection, turn right 1 o’clock toward Seomyeon Intersection, City Hall/National Police Agency",
                        "distance": 910,
                        "duration": 125240
                    },
                    {
                        "pointIndex": 6842,
                        "type": 88,
                        "instructions": "Destination",
                        "distance": 895,
                        "duration": 111333
                    }
                ]
            }
        ]
    }
}