🌐 한국어

Multi-Origin Multi-Destination (Matrix)

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

A REST API key is required to use this API. Please refer to Getting Started for instructions on how to register an app and obtain a REST API key.

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 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 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	Departure point. Up to 200 origins are allowed.	O
key	String	Random string to identify each origin	O
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
destinations	Object[]	Arrival point. Up to 200 destinations are allowed.	O
key	String	Random string to identify each destination	O
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
radius	Int	Radius to find routes in meters (Maximum: 20000)	O
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)	X
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"])	X
roadevent	Int	Road Blockage Information Option Due to Incidents (e.g., traffic 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)	X

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 direction request	O
routes	Object[]	Route Information, created for each route	O
result_code	Int	Result code	O
result_msg	String	Result message	O
origin_key	String	The value of key specified for origins	O
destination_key	String	The value of key specified for destinations	O
summary	Object	Route summary information	O
distance	Int	Distance between sections in meters	O
duration	Int	Total required time in seconds	O