{ "operationId": "postRouteTimeResult", "method": "GET, POST", "path": "/maps/v3.0/appkeys/{APPKEY}/route-time", "category": "route-directions", "tags": [ "탐색" ], "summary": "경로 예측 탐색", "description": "출발, 도착 예정시간을 기준으로 예상 도착시간 및 출발지와 목적지 (경유지 옵션) 좌표를 이용하여 탐색된 상세 정보와 경로 정보를 반환합니다", "deprecated": false, "parameters": [ { "name": "APPKEY", "in": "path", "description": "해당 API 사용 권한이 있는 API 키", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "경로 예측 탐색 조건", "content": { "application/json": { "schema": { "required": [ "day", "endX", "endY", "hour", "minutes", "month", "option", "startX", "startY", "type", "year" ], "type": "object", "properties": { "option": { "pattern": "^(stats|stats_freeroad|stats_highway)$", "type": "string", "description": "경로 탐색 옵션
*하나만 선택 가능", "default": "stats", "enum": [ "stats", "stats_freeroad", "stats_highway" ], "x-enum-descriptions": { "stats": "통계 예측 탐색", "stats_highway": "고속도로 우선 통계 예측 탐색", "stats_freeroad": "무료 도로 우선 통계 예측 탐색" } }, "type": { "pattern": "^(start|end)$", "type": "string", "description": "기준 시간", "example": "start", "enum": [ "start", "end" ], "x-enum-descriptions": { "start": "출발 시각 기준", "end": "도착 시각 기준" } }, "startX": { "type": "string", "description": "시작 지점(출발지)에 대한 X좌표(경도)", "example": "127.110762" }, "startY": { "type": "string", "description": "시작 지점(출발지)에 대한 Y좌표(위도)", "example": "37.402184" }, "endX": { "type": "string", "description": "끝 지점(도착지)에 대한 X좌표(경도)", "example": "127.105399" }, "endY": { "type": "string", "description": "끝 지점(도착지)에 대한 Y좌표(위도)", "example": "37.5124518" }, "year": { "minimum": 1, "type": "integer", "description": "경로 탐색의 기준이 되는 연도(YYYY)
*예: 2026", "format": "int32", "example": 2026 }, "month": { "maximum": 12, "minimum": 1, "type": "integer", "description": "경로 탐색의 기준이 되는 월
*예: 2", "format": "int32", "example": 1 }, "day": { "maximum": 31, "minimum": 1, "type": "integer", "description": "경로 탐색의 기준이 되는 일
*예: 26", "format": "int32", "example": 9 }, "hour": { "maximum": 23, "minimum": 0, "type": "integer", "description": "경로 탐색의 기준이 되는 시각(시)
*24시간 형식(0~23)으로 입력
*예: 17", "format": "int32", "example": 13 }, "minutes": { "maximum": 59, "minimum": 0, "type": "integer", "description": "경로 탐색의 기준이 되는 시각(분)
*예: 30", "format": "int32", "example": 30 }, "coordType": { "pattern": "^(tw|wgs84|TW|WGS84)$", "type": "string", "description": "좌표 체계
*'wgs84'는 국제 표준 좌표계, 'tw'는 팅크웨어 좌표계를 의미", "default": "wgs84", "enum": [ "wgs84", "tw" ] }, "via1X": { "type": "string", "description": "1 번째 경유지에 대한 X좌표(경도)" }, "via1Y": { "type": "string", "description": "1 번째 경유지에 대한 Y좌표(위도)" }, "via2X": { "type": "string", "description": "2 번째 경유지에 대한 X좌표(경도)" }, "via2Y": { "type": "string", "description": "2 번째 경유지에 대한 Y좌표(위도)" }, "via3X": { "type": "string", "description": "3 번째 경유지에 대한 X좌표(경도)" }, "via3Y": { "type": "string", "description": "3 번째 경유지에 대한 Y좌표(위도)" }, "via4X": { "type": "string", "description": "4 번째 경유지에 대한 X좌표(경도)" }, "via4Y": { "type": "string", "description": "4 번째 경유지에 대한 Y좌표(위도)" }, "via5X": { "type": "string", "description": "5 번째 경유지에 대한 X좌표(경도)" }, "via5Y": { "type": "string", "description": "5 번째 경유지에 대한 Y좌표(위도)" }, "carType": { "maximum": 6, "minimum": 1, "type": "integer", "description": "차량 종류", "format": "int32", "example": 1, "default": 1, "enum": [ 1, 2, 3, 4, 5, 6 ], "x-enum-descriptions": { "1": "소형차", "2": "중형차", "3": "대형차", "4": "대형화물차", "5": "특수화물차", "6": "경차" } }, "carHeight": { "type": "integer", "description": "차량의 높이(cm)", "format": "int32", "example": 150 }, "carWeight": { "type": "integer", "description": "차량의 총 중량(kg)", "format": "int32", "example": 4000 }, "groupByTrafficColor": { "type": "boolean", "description": "경로의 교통 상황 색상 그룹화 여부", "default": false, "enum": [ false, true ], "x-enum-descriptions": { "false": "교통 상황 색상 비그룹화", "true": "교통 상황 색상 그룹화" } }, "useAngle": { "type": "boolean", "description": "출발 지점의 주행 각도 설정 여부", "default": false, "enum": [ false, true ], "x-enum-descriptions": { "false": "주행 방향 비우선", "true": "주행 방향 우선" } }, "angle": { "maximum": 359, "minimum": 0, "type": "integer", "description": "주행 각도
*정북 방향을 0으로 하여 시계 방향으로 0~359도
*'useAngle'이 true일 때 적용", "format": "int32" }, "useStartDirection": { "type": "boolean", "description": "출발지 좌표 기준 주행 방향 지정 여부
*차량 주행방향을 알 수 없을 때 활용", "default": false, "enum": [ false, true ], "x-enum-descriptions": { "false": "출발지 좌표 기준 주행 방향 미지정", "true": "출발지 좌표 기준 주행 방향 지정" } }, "searchByAddress": { "type": "boolean", "description": "주소 기반 경로 탐색 여부", "default": false, "enum": [ false, true ], "x-enum-descriptions": { "false": "일반 경로 탐색", "true": "주소 기반 경로 탐색" } }, "usageType": { "maximum": 1, "minimum": 0, "type": "integer", "description": "사용 용도", "format": "int32", "default": 0, "enum": [ 0, 1 ], "x-enum-descriptions": { "0": "일반", "1": "택시" } }, "avoidWaterSourceArea": { "type": "boolean", "description": "상수원 보호 구역 회피 탐색 여부", "default": false, "enum": [ false, true ], "x-enum-descriptions": { "false": "일반 탐색", "true": "상수원 보호 구역 회피 탐색" } }, "avoidNarrowRoad": { "maximum": 16, "minimum": 0, "type": "integer", "description": "좁은 길(이면도로) 회피 차선 정보
*0~16
*값은 왕복 차선의 개수
*예: 값이 6일 경우, 왕복 6차선 도로에서 차종에 관계 없이 모두 회피", "format": "int32", "default": 0 }, "avoidUTurn": { "maximum": 16, "minimum": 0, "type": "integer", "description": "U턴 회피 차선 정보
*0~16
*값은 왕복 차선의 개수
*예: 값이 6 일 경우, 왕복 6차선 이하 도로에서 U턴 회피", "format": "int32", "default": 0 }, "useTaxifare": { "type": "string", "description": "예상 택시 요금 조회 여부", "default": "0", "enum": [ "0", "1", "2", "3" ], "x-enum-descriptions": { "0": "미사용", "1": "일반 택시", "2": "모범 택시", "3": "일반 및 모범 택시" } }, "beforeCount": { "type": "integer", "description": "기준 시간 이전 탐색 개수
*예: beforeCount=2
*interval=15인 경우 기준 시각 기준 15분 전, 30분 전 경로를 추가 탐색", "format": "int32", "example": 1, "default": 0 }, "afterCount": { "type": "integer", "description": "기준 시간 이후 탐색 개수
*예: afterCount=2
*interval=15인 경우 기준 시각 기준 15분 후, 30분 후 경로를 추가 탐색", "format": "int32", "example": 1, "default": 0 }, "interval": { "type": "integer", "description": "시간 간격
*기준 시각을 중심으로 설정된 간격마다 이전/이후 시각에 대해 예상 출/도착 시간 반환", "format": "int32", "example": 15, "default": 15 } }, "description": "경로 예측 시간 탐색을 위한 요청 파라미터 집합 출발지, 도착지, 시간, 차종 등 다양한 조건을 설정하여 예상 소요 시간을 예측합니다" }, "example": { "option": "stats", "type": "start", "startX": "127.110762", "startY": "37.402184", "endX": "127.111412", "endY": "37.39476", "year": 2026, "month": 1, "day": 20, "hour": 13, "minutes": 30, "coordType": "wgs84", "beforeCount": 1, "afterCount": 1, "interval": 15 } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": { "type": "object", "properties": { "isSuccessful": { "type": "boolean", "description": "API 요청 성공 여부", "example": true }, "resultCode": { "type": "integer", "description": "API 응답 결과 코드", "format": "int32", "example": 0 }, "resultMessage": { "type": "string", "description": "API 응답 결과 문구", "example": "Success" } }, "description": "API 응답 결과" }, "route": { "type": "object", "properties": { "data": { "type": "object", "properties": { "option": { "type": "string", "description": "경로 탐색 옵션
*하나만 선택 가능", "default": "stats", "enum": [ "stats", "stats_freeroad", "stats_highway" ], "x-enum-descriptions": { "stats": "통계 예측 탐색", "stats_highway": "고속도로 우선 통계 예측 탐색", "stats_freeroad": "무료 도로 우선 통계 예측 탐색" } }, "toll_fee": { "type": "integer", "description": "경로 상에서 발생하는 총 톨게이트 통행 요금", "format": "int32", "example": 3400 }, "taxiFare": { "type": "integer", "description": "예상 택시 요금 정보
*요청 시 'useTaxifare' 값이 1(일반) 또는 2(모범)일 때만 값이 반환", "format": "int32", "example": 45000 }, "totalTaxiFare": { "type": "string", "description": "예상 택시 요금 정보
*요금 정보가 문자열 형태로 반환
*예: \"6500\" or \"6500,11500\"", "example": "7000" }, "spend_time": { "type": "integer", "description": "경로 전체의 총 예상 소요 시간(초)", "format": "int32", "example": 3720 }, "distance": { "type": "integer", "description": "경로 전체의 총 거리(m)", "format": "int32", "example": 72183 }, "isHighWay": { "type": "boolean", "description": "해당 경로의 고속도로 포함 여부", "example": false }, "times": { "type": "array", "description": "각 시간대별 경로 요약 정보의 목록(배열)
둘 다 값이 0인 경우 빈 배열 반환", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "탐색된 시간대의 순번
'0'은 요청 시 설정한 기준 시간을 의미
index의 값이 클 수록 interval에 따른 기준 시간이 증가", "format": "int32", "example": 0 }, "spend_time": { "type": "integer", "description": "경로 전체의 총 예상 소요 시간(초)", "format": "int32", "example": 3720 }, "startTime": { "type": "object", "properties": { "year": { "type": "integer", "description": "연도(YYYY) 정보", "format": "int32", "example": 2019 }, "month": { "type": "integer", "description": "월(1-12) 정보", "format": "int32", "example": 11 }, "day": { "type": "integer", "description": "일(1-31) 정보", "format": "int32", "example": 26 }, "hour": { "type": "integer", "description": "시(0-23) 정보", "format": "int32", "example": 11 }, "minutes": { "type": "integer", "description": "분(0-59) 정보", "format": "int32", "example": 0 } }, "description": "해당 경로 탐색의 실제 출발 시간을 나타내는 객체" }, "endTime": { "type": "object", "properties": { "year": { "type": "integer", "description": "연도(YYYY) 정보", "format": "int32", "example": 2019 }, "month": { "type": "integer", "description": "월(1-12) 정보", "format": "int32", "example": 11 }, "day": { "type": "integer", "description": "일(1-31) 정보", "format": "int32", "example": 26 }, "hour": { "type": "integer", "description": "시(0-23) 정보", "format": "int32", "example": 11 }, "minutes": { "type": "integer", "description": "분(0-59) 정보", "format": "int32", "example": 0 } }, "description": "해당 경로 탐색의 예상 도착 시간을 나타내는 객체" } }, "description": "각 시간대별 경로 요약 정보의 목록(배열)
둘 다 값이 0인 경우 빈 배열 반환" } }, "paths": { "type": "array", "description": "경로를 구성하는 각 세부 구간에 대한 정보 목록(배열)", "items": { "type": "object", "properties": { "coords": { "type": "array", "description": "해당 구간을 구성하는 좌표 지점들의 목록(배열)", "items": { "type": "object", "properties": { "x": { "type": "number", "description": "해당 지점의 X좌표(경도)", "example": 127.110762 }, "y": { "type": "number", "description": "해당 지점의 Y좌표(위도)", "example": 37.402184 } }, "description": "검색 할 좌표를 담는 목록(배열)
*최소 3개 이상 입력" } }, "speed": { "type": "integer", "description": "해당 구간의 평균 속도(km/h)", "format": "int32", "example": 85 }, "distance": { "type": "integer", "description": "해당 구간의 거리(m)", "format": "int32", "example": 120 }, "spend_time": { "type": "integer", "description": "해당 구간의 예상 소요 시간(초)", "format": "int32", "example": 2800 }, "road_code": { "type": "integer", "description": "도로의 종류를 구분하는 코드", "format": "int32", "example": 1, "enum": [ 0, 1, 2, 3, 4, 5 ], "x-enum-descriptions": { "0": "페리항로", "1": "고속도로", "2": "도시 고속도로", "3": "국도", "4": "지방도", "5": "일반도로" } }, "traffic_color": { "type": "string", "description": "해당 구간의 교통 상황을 나타내는 색상 코드", "example": "#fb3a76" }, "point_type": { "type": "string", "description": "해당 구간의 속성", "example": "S", "enum": [ "S", "V", "E", "N" ], "x-enum-descriptions": { "S": "출발지", "E": "도착지", "V": "경유지", "N": "일반" } } }, "description": "경로를 구성하는 각 세부 구간에 대한 정보 목록(배열)" } } }, "description": "경로 예측 탐색 결과 데이터" } }, "description": "경로 예측 탐색 결과" } }, "description": "경로 예측 탐색 API의 전체 응답" } } } }, "400": { "description": "잘못된 요청", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": "[Circular Reference]" }, "description": "API 응답 결과의 상태" } } } }, "404": { "description": "API 없음", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": "[Circular Reference]" }, "description": "API 응답 결과의 상태" } } } }, "415": { "description": "허용되지 않는 메서드", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": "[Circular Reference]" }, "description": "API 응답 결과의 상태" } } } }, "500": { "description": "서버 내부 오류", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": "[Circular Reference]" }, "description": "API 응답 결과의 상태" } } } } }, "baseUrl": "https://imaps.inavi.com" }