Matrix Directions

This API provides route summary information from one or more origins to one or more destinations. You can set up to 200 origins and 200 destinations each.

DANGER

You need a REST API key to use this API. To register an app and get a REST API key, see Getting Started.

Request

This section describes the request method and the required request headers. If the request fails, see Troubleshooting for detailed error information.

Request Method

Method	URL
POST	https://apis-navi.kakaomobility.com/affiliate/v1/matrix/directions

Request Headers

Parameter	Description
Authorization	KakaoAK ${REST_API_KEY} {REST_API_KEY}: The REST API key issued from Kakao Developers
Content-Type	application/json

Sample request

curl -v -X POST "http://sandbox-navi-api.kakao.com/affiliate/v1/matrix/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \  // The REST API key issued from Kakao Developers
-d '{
  "priority": "TIME",
  "avoid": null,
  "radius": 10000,
  "origins": [
  {
      "key": "0",
      "x": 127.10944211462966,
      "y": 37.32663448680758
  },
  {
      "key": "1",
      "x": 127.05971101787819,
      "y": 37.31883381417869
  },
  {
      "key": "2",
      "x": 127.06908737313162,
      "y": 37.31420428563164
  }
  ],
  "destinations": [
  {
      "key": "0",
      "x": 127.11082432539847,
      "y": 37.32615829528716
  },
  {
      "key": "1",
      "x": 127.0597521023936,
      "y": 37.319158530933635
  }
  ]
}'

The request parameters are as follows:

Parameters

Name	Type	Description	Required
origins	Object	Origin. Up to 200 origins are allowed.	Required
key	String	An arbitrary string to identify each origin	Required
x	Double	X coordinate (longitude)	Required
y	Double	Y coordinate (latitude)	Required
destinations	Object[]	Destination. Up to 200 destinations are allowed.	Required
key	String	An arbitrary string to identify each destination	Required
x	Double	X coordinate (longitude)	Required
y	Double	Y coordinate (latitude)	Required
radius	Int	Radius to find routes in meters (Maximum: 10000)	Required
priority	String	Set priority options for navigation. Use one of the following: TIME: The fastest route DISTANCE: The shortest route NO_TRAFFIC_INFO: The fastest route without considering real-time traffic information (Default: TIME)	Optional
avoid	String[]	Set restriction options for navigation. Use one or more of the following in the array: ferries: Exclude sea route toll: Exclude toll road motorway: Exclude motorway schoolzone: Exclude school zone uturn: Exclude U-turns (Default: null) Use multiple restriction options by connecting them like this: (Example: ["ferries", "motorway"])	Optional
roadevent	Int	Option to reflect road closure information caused by traffic incidents (traffic obstructions such as accidents, events, disasters, or road construction) 0: Reflect full road closures 1: Do not reflect full road closures near the origin and destination. 2: Do not reflect any full road closures. (Default: 0)	Optional

Response

Upon successful response, the success status is delivered via HTTP status code, and the request body is delivered in JSON format.

Sample response

{
  "trans_id": "ae98ef77f0824abe90d651c622742f4a",
  "routes": [
      {
          "result_code": 0,
          "result_msg": "Success",
          "origin_key": "0",
          "destination_key": "0",
          "summary": {
              "distance": 3053,
              "duration": 885
          }
      },
      {
          "result_code": 0,
          "result_msg": "Success",
          "origin_key": "0",
          "destination_key": "1",
          "summary": {
              "distance": 6540,
              "duration": 1437
          }
      },
      {
          "result_code": 0,
          "result_msg": "Success",
          "origin_key": "1",
          "destination_key": "0",
          "summary": {
              "distance": 8484,
              "duration": 2217
          }
      },
      {
          "result_code": 0,
          "result_msg": "Success",
          "origin_key": "1",
          "destination_key": "1",
          "summary": {
              "distance": 105,
              "duration": 22
          }
      },
      {
          "result_code": 0,
          "result_msg": "Success",
          "origin_key": "2",
          "destination_key": "0",
          "summary": {
              "distance": 9015,
              "duration": 2028
          }
      },
      {
          "result_code": 0,
          "result_msg": "Success",
          "origin_key": "2",
          "destination_key": "1",
          "summary": {
              "distance": 1382,
              "duration": 358
          }
      }
  ]
}

The response object information is as follows:

Response object

Name	Type	Description	Required
trans_id	String	Unique identifier of a route request	Required
routes	Object[]	Route information; one entry is created for each route	Required
result_code	Int	Route search result code	Required
result_msg	String	Route search result message	Required
origin_key	String	The value of key specified for each origin in origins	Required
destination_key	String	The value of key specified for each destination in destinations	Required
summary	Object	Route summary information	Required
distance	Int	Total distance of the search result in meters	Required
duration	Int	Time required to reach the destination in seconds	Required