-
[Navigation] #4 route API 분석 (옵션별 결과 비교)Navigation 2026. 3. 22. 00:09
이번 글에서는 Route API 옵션과 OSRM이 제공하는 주요 서비스 API들을 확인해보겠다.
1. OSRM Route API 파라미터 살펴보기
OSRM Route API는 다양한 파라미터를 통해 응답 결과의 형태와 상세 수준을 조정할 수 있다.
파라미터를 활용하여 반환되는 경로 정보의 구조, 상세 정보, geometry 형식 등을 필요에 맞게 제어할 수 있다.
예를 들어, 응답 크기 최적화, 디버깅, 지도 렌더링, 네비게이션 기능 구현 등의 목적에 따라 여러 파라미터를 조합하여 사용할 수 있다.
파라미터 설정없이 기본 요청 결과는 아래와 같다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?overview=simplified[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }이제 Route 서비스에서 자주 사용되는 주요 파라미터들을 살펴보겠다.
1) overview
overview는 경로 전체의 geometry 반환 수준을 설정하는 파라미터이다.
즉, 경로를 얼마나 상세하게 좌표로 표현할지를 결정한다.
값 설명 사용 사례 예시 simplified 단순화된 경로 geometry 반환 (기본값) 지도에 경로를 표시할 때 일반적으로 사용 ?overview=simplified false 경로 geometry 반환 거리/시간만 필요한 경우, 응답 크기 최소화 ?overview=false full 전체 경로를 상세 좌표로 반환 정확한 경로 분석, 상세 지도 렌더링 ?overview=full overview= simplified
overview=simplified 는 기본값으로 단순화된 geometry가 반환된다.
실제 경로를 유지하면서도 좌표 개수를 줄여 응답 크기를 최적화한다.
지도 위에 경로를 표시할 때 (일반적인 웹/앱), 성능과 정확도의 균형이 필요한 경우 사용된다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?overview=simplified[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }overview=false
overview=false 옵션을 사용하면 geometry 필드가 제거되어 응답 JSON 크기를 크게 줄일 수 있다.
경로 좌표 대신 distance, duration 등 요약 정보만 반환된다.
단순히 거리(distance)나 시간(duration)만 필요한 경우, 서버 간 API 호출 등에서 네트워크 비용을 줄이고 싶을 때 사용된다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?overview=false[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }overview=full
overview=full 옵션을 사용하면 경로를 구성하는 모든 좌표가 반환된다.
경로의 모든 좌표가 geometry 필드에 포함되기 때문에 응답 데이터의 크기가 증가하지만, 정확한 경로 정보를 얻을 수 있다.
경로를 정밀하게 분석해야 하는 경우에 활용된다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?overview=full[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@lA?l@?Xq@?aC@U?mD@QECCUe@?G@O?CBy@NyFB[@WDqA@q@NqEH{DDkA?SBk@Fm@\\gDd@sE^sCLoATyB@gBBoAr@@pBF`ADJATAp@Ad@AZAT?F?B?xA?`CCZGl@UVKb@OJCZOLGl@Y\\YxA}@\\SZM\\KXElBOfAKRCD?ZAf@G\\ETERERK^Q`@a@b@i@`@cALm@PaA@E\\aAb@iAZg@j@m@b@a@h@Wh@Sz@KbAKdCSl@I\\E`@Iv@M|Bw@v@UtA{@jlA{o@PMZYx@{@JKX[f@q@Xg@d@oAf@wAXk@RYVWh@]`@QTEr@M~B]|AYrAYbBe@t@Wv@Yj@K`Ak@|@]jAeA~BaB|@m@`Ao@z@q@fCaB`Am@pBsAt@k@j@e@nA{@^[r@]\\SROfC}AbAs@`As@fJmIvHaH~AyAvIeIrHyGlBiBd@c@v@k@fB}@l@UbAUbB]fJkBj@AXCpCg@vFcABA^GZGb@KnA]h@OfBU`Dk@`@InCs@lAWbBo@pDuA^MRIf@Up@[bE}AzB}@rAg@p@W~@UdA_@xB{@NG`Bu@hCkAzEaBf@Ud@YtCkAn@UnAY`A[rBo@pAg@pBw@t@W|@]pCiAf@QXMdBm@n@UZMdAa@VIHEJECO", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }2) steps
steps는 경로의 단계별(turn-by-turn) 네비게이션 정보를 포함할지 여부를 설정하는 파라미터이다.
값 설명 사용 사례 예시 false 단계별 경로 안내 정보 반환하지 않음 (기본값) 단순 경로 표시 ?steps=false true 좌회전, 우회전, 직진 등의 네비게이션 단계 반환 내비게이션 서비스 구현 ?steps=true steps=false
steps=false는 기본값으로 단계별 경로 안내 정보를 포함하지 않고, 전체 경로 요약 정보만 반환한다.
단순히 경로를 지도에 표시하거나 distance, duration만 필요한 경우에 적합하다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?steps=false[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }steps=true
좌회전, 우회전, 직진 등의 상세한 네비게이션 단계 정보를 함께 반환한다.
실제 내비게이션 서비스처럼 사용자에게 경로 안내를 제공할 때 활용된다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?steps=true[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [ { "intersections": [ { "out": 0, "entry": [true], "bearings": [269], "location": [126.977993, 37.567005] } ], "driving_side": "right", "geometry": "yhhdFmk_fW@lA?l@?X", "maneuver": { "bearing_after": 269, "bearing_before": 0, "location": [126.977993, 37.567005], "modifier": "left", "type": "depart" }, "name": "세종대로20길", "mode": "driving", "weight": 6.4, "duration": 6.4, "distance": 66.4 }, { "intersections": [ { "out": 0, "in": 1, "entry": [true, false, false], "bearings": [0, 90, 180], "location": [126.977241, 37.567003] }, { "out": 0, "in": 2, "entry": [true, true, false], "bearings": [0, 75, 180], "location": [126.977231, 37.568014] } ], "driving_side": "right", "maneuver": { "bearing_after": 358, "bearing_before": 268, "location": [126.977241, 37.567003], "modifier": "right", "type": "continue" }, "geometry": "whhdFwf_fWq@?aC@U?mD@", "ref": "31", "name": "세종대로", "mode": "driving", "weight": 15.6, "duration": 15.6, "distance": 208.8 }, { "intersections": [ { "out": 1, "in": 2, "entry": [true, true, false], "bearings": [0, 30, 180], "location": [126.97722, 37.568884] }, { "out": 1, "in": 2, "entry": [false, true, false], "bearings": [0, 90, 240], "location": [126.977462, 37.569102] }, { "out": 0, "in": 2, "entry": [true, true, false], "bearings": [90, 180, 270], "location": [126.977886, 37.569072] }, ... 생략3) annotations
annotations는 경로를 구성하는 각 각 도로 구간(segment)에 대한 추가 상세 정보(거리, 시간 등)를 포함할지 설정하는 파라미터이다.
값 설명 사용 사례 예시 false 구간별 상세 정보를 반환하지 않는다. (기본값) 기본 경로 조회 ?annotations=false true 거리, 시간, 속도 등 모든 구간 정보를 반환한다. 교통 데이터 분석 ?annotations=true distance 각 구간의 거리 정보만 반환한다. 경로 거리 분석 ?annotations=distance duration 각 구간의 이동 시간 정보만 반환한다. 이동 시간 분석 ?annotations=duration speed 각 구간의 평균 속도를 반환한다. 교통 속도 분석 ?annotations=speed annotations=true
duration, distance, speed 등의 다양한 정보가 모두 포함되어 반환되며, 경로를 보다 정밀하게 분석할 수 있다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?annotations=true[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "distance": 9950.1, "annotation": { "metadata": { "datasource_names": [ "lua profile" ] }, "datasources": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], "weight": [2.3, 1.3, 0.8, 2, 5.4, 1, 7.2, 0.5, 0.2, 1.2, 0.2, 0.4, 0.1, 1.4, 6.2, 0.7, 0.6, 2, 1.2, 5.2, 4.6, 1.9, 0.5, 1.1, 1.2, 4.2, 5.3, 3.7, 2, 3.1, 2.5, 1.9, 1.6, 3.5, 2, 0.4, 0.6, 1.6, 1.2, 0.9, 0.6, 0.2, 0.2, 2.7, 4, 0.9, 1.5, 0.8, 1.2, 0.4, 1, 0.4, 1.6, 1.1, 3.2, 1, 0.9, 1, 0.8, 3.4, 2.3, 0.6, 0.2, 0.9, 1.3, 0.9, 0.7, 0.6, 0.7, 1.1, 1.3, 1.5, 2, 1.2, 1.7, 0.2, 1.9, 2.1, 1.3, 1.8, 1.4, 1.4, 1.4, 1.9, 2.1, 4.1, 1.5, 0.9, 1.1, 1.7, 4.2, 1.8, 3, 85.2, 0.6, 1.1, 2.3, 0.5, 1, 1.7, 1.3, 2.3, 2.5, 1.3, 0.9, 0.9, 1.5, 1.1, 0.6, 1.7, 4, 3, 2.6, 3.2, 1.7, 1.9, 1.4, 2.3, 2, 2.9, 4.6, 2.2, 2.4, 2.2, 4.8, 2.3, 4.1, 2, 1.6, 2.9, 1.2, 1.8, 1.4, 0.9, 6.5, 3.3, 3.3, 18.6, 11.9, 3.7, 13.3, 11.7, 4.2, 1.5, 2, 3.5, 1.5, 2.1, 3.2, 11.4, 1.3, 0.8, 4.6, 7.8, 0.1, 1, 0.9, 1.1, 2.6, 1.4, 3.2, 5.1, 1.1, 4.6, 2.5, 3.3, 5.9, 1.1, 0.6, 1.3, 1.7, 6.5, 4.1, 2.8, 1.6, 2.1, 2.3, 4, 0.6, 3.3, 4.7, 7.1, 1.4, 1.3, 5, 1.5, 2.6, 2.1, 3.8, 2.7, 3.7, 2.8, 3.3, 7.9, 2.1, 0.9, 3.4, 1.6, 0.9, 2.4, 0.7, 0.4, 0.4, 0.4], "nodes": [6107335405, 3825649163, 11414286300, 5851251264, 5851251263, 4806788868, 5851251268, 414685899, 5863541499, 1936511553, 5863541500, 11233115460, 5706326038, 4960162823, 3063260473, 7505703291, 3806620354, 7505703292, 2420018339, 3063260470, 2420018333, 4960120586, 11233115500, 11233115520, 871729389, 11233115540, 11233115510, 11233115510, 2463587951, 2420018320, 2135158092, 11170069520, 871729376, 11173361260, 3369577593, 9271052085, 2420018295, 2374692793, 11203083990, 414685871, 11059719420, 11203083980, 11203083990, 11173361280, 2087933396, 4276255168, 5804596023, 7311080429, 5172891764, 9327504890, 1945254534, 7816990853, 2086910499, 7169588027, 2087933427, 436852104, 2087933436, 436852103, 2374697792, 4203161544, 2087933405, 13132749780, 11203059760, 3285441983, 11059614390, 1908148229, 7311080410, 7319920021, 436852099, 1908148221, 436852098, 436852097, 1484324026, 1484324025, 4151560490, 4203029514, 436852096, 1908148211, 1484324020, 436852095, 1484324018, 436852094, 436852093, 1908148204, 1484324016, 436852092, 7179553775, 7179553778, 436852091, 5405375541, 2418536662, 436830835, 2418536661, 1484324010, 797008463, 9895468613, 1484324001, 797008723, 12997876920, 12997876920, 797009131, 797009133, 797009135, 797009137, 797009139, 797009140, 797009142, 797009143, 797009145, 5485726607, 797009147, 12997876910, 12997876910, 2837156160, 2837156156, 11170853620, 10211007220, 436879805, 7816990857, 4596976881, 10211007220, 436879801, 10211007220, 797008124, 4360970522, 797008122, 4360970525, 4360970524, 4360970526, 4360970515, 4360970516, 4360970517, 2385986710, 11204519570, 3852166172, 4360970512, 4360970513, 732031868, 1936511269, 7816990855, 5987947843, 732031876, 595776267, 595780360, 5987954176, 9481728419, 595776271, 5987954183, 595776272, 595776273, 2032644156, 2032644155, 600377807, 600377800, 11225381660, 11225381640, 4867335002, 4867335000, 7168332244, 4867334997, 4867334999, 4867334996, 357824648, 9892111593, 2280678864, 2861578308, 2429722067, 12890141610, 11083667700, 2280678860, 12890141600, 2477265762, 3827672541, 4182209842, 2477340275, 4984365472, 7816990858, 3827672469, 4867334969, 2477265761, 4867334963, 2477265747, 9632566090, 2281095539, 8376423650, 5237800475, 12741729340, 11847324490, 2280678787, 3827608168, 3146844230, 3054698333, 3112723452, 12741729340, 11847324500, 2280678683, 11847324500, 9230557523, 9632500767, 3101791329, 11183748440, 3089780834, 11034387030, 7168335697, 11179628420], "distance": [34.62967587, 20.31779619, 11.48594557, 27.30444477, 72.14514248, 12.76367174, 96.56484055, 9.538321715, 3.066500932, 21.16514643, 3.736618083, 6.582939348, 1.68206729, 25.62569401, 111.2825597, 12.51519778, 10.85909053, 36.2829057, 21.79456266, 93.167278, 83.30276171, 33.95588381, 8.351007912, 19.34966164, 21.51101558, 75.64564767, 96.27793385, 67.39603735, 36.28903108, 55.71178001, 45.67679869, 34.85585428, 28.63992489, 63.91128146, 36.057776, 7.580228659, 11.4594225, 28.43624095, 21.21719127, 15.67951017, 11.65378724, 4.218486105, 2.996688147, 49.05697439, 72.50393084, 16.04332529, 26.63932143, 15.05909491, 21.14627992, 6.357304856, 17.71059134, 7.782643289, 28.85394015, 19.59777501, 57.25941334, 18.49817271, 16.62050612, 17.49931275, 15.18622309, 60.85378147, 41.15294845, 10.62683645, 3.017448335, 16.33919903, 22.65666204, 16.16969011, 12.95331807, 11.65219243, 11.78473562, 19.21292326, 23.79962453, 27.46417404, 36.11135157, 21.58612557, 30.56452898, 2.74962966, 34.38278907, 37.39685014, 23.81523395, 31.71989275, 25.21023895, 24.73715619, 25.57990543, 33.69380007, 38.12480145, 74.31129233, 26.22006038, 16.87198535, 19.84349072, 30.83349109, 74.9381419, 32.25269663, 54.36385287, 1538.030114, 11.71279371, 20.03743968, 41.3938215, 8.680942748, 18.68663613, 31.15335166, 23.16406828, 41.30200121, 44.51075965, 24.22641863, 16.16341474, 16.80849676, 27.12632056, 20.23887532, 11.69051365, 30.39957102, 71.41473302, 54.33909135, 47.64411999, 58.03498767, 31.46115254, 33.62407128, 24.78772598, 41.58256127, 36.80108825, 51.89639448, 82.91235583, 39.91926152, 42.92121193, 40.42082631, 86.49246507, 41.51349891, 74.06773002, 35.78156261, 29.01259788, 51.70223009, 22.18391931, 31.69357116, 18.76262332, 12.60203248, 86.50516126, 43.81063395, 43.61735505, 248.2067454, 215.6521011, 66.04433645, 239.3662332, 211.6725593, 76.68086214, 26.68351938, 36.70746231, 63.94109598, 27.65896963, 38.40897422, 57.07644166, 205.7780278, 23.88211699, 14.57091479, 82.8758803, 140.88686, 2.498663686, 17.83479109, 16.31342716, 20.63253395, 46.31489271, 24.7526809, 58.29332891, 91.45575411, 19.93914512, 82.56819181, 45.18956766, 59.05779537, 105.8397251, 19.25666061, 11.57004817, 24.16792264, 30.96047593, 116.4873058, 73.38899287, 50.33247141, 29.31803619, 37.43915365, 40.97449059, 72.28012025, 10.34506073, 58.82464657, 84.26611944, 128.5417118, 24.74310019, 23.94983324, 90.2171383, 27.90899952, 46.25453054, 38.34484372, 67.75091254, 49.27312245, 67.41580978, 31.31115514, 37.07216631, 88.00199737, 23.31387865, 15.53164676, 60.85085818, 28.19361287, 15.7780846, 42.7065927, 13.11949807, 7.032725855, 7.032725855, 7.031626918], "duration": [2.3, 1.3, 0.8, 2, 5.4, 1, 7.2, 0.5, 0.2, 1.2, 0.2, 0.4, 0.1, 1.4, 6.2, 0.7, 0.6, 2, 1.2, 5.2, 4.6, 1.9, 0.5, 1.1, 1.2, 4.2, 5.3, 3.7, 2, 3.1, 2.5, 1.9, 1.6, 3.5, 2, 0.4, 0.6, 1.6, 1.2, 0.9, 0.6, 0.2, 0.2, 2.7, 4, 0.9, 1.5, 0.8, 1.2, 0.4, 1, 0.4, 1.6, 1.1, 3.2, 1, 0.9, 1, 0.8, 3.4, 2.3, 0.6, 0.2, 0.9, 1.3, 0.9, 0.7, 0.6, 0.7, 1.1, 1.3, 1.5, 2, 1.2, 1.7, 0.2, 1.9, 2.1, 1.3, 1.8, 1.4, 1.4, 1.4, 1.9, 2.1, 4.1, 1.5, 0.9, 1.1, 1.7, 4.2, 1.8, 3, 85.2, 0.6, 1.1, 2.3, 0.5, 1, 1.7, 1.3, 2.3, 2.5, 1.3, 0.9, 0.9, 1.5, 1.1, 0.6, 1.7, 4, 3, 2.6, 3.2, 1.7, 1.9, 1.4, 2.3, 2, 2.9, 4.6, 2.2, 2.4, 2.2, 4.8, 2.3, 4.1, 2, 1.6, 2.9, 1.2, 1.8, 1.4, 0.9, 6.5, 3.3, 3.3, 18.6, 11.9, 3.7, 13.3, 11.7, 4.2, 1.5, 2, 3.5, 1.5, 2.1, 3.2, 11.4, 1.3, 0.8, 4.6, 7.8, 0.1, 1, 0.9, 1.1, 2.6, 1.4, 3.2, 5.1, 1.1, 4.6, 2.5, 3.3, 5.9, 1.1, 0.6, 1.3, 1.7, 6.5, 4.1, 2.8, 1.6, 2.1, 2.3, 4, 0.6, 3.3, 4.7, 7.1, 1.4, 1.3, 5, 1.5, 2.6, 2.1, 3.8, 2.7, 3.7, 2.8, 3.3, 7.9, 2.1, 0.9, 3.4, 1.6, 0.9, 2.4, 0.7, 0.4, 0.4, 0.4], "speed": [15.1, 15.6, 14.4, 13.7, 13.4, 12.8, 13.4, 19.1, 15.3, 17.6, 18.7, 16.5, 16.8, 18.3, 17.9, 17.9, 18.1, 18.1, 18.2, 17.9, 18.1, 17.9, 16.7, 17.6, 17.9, 18, 18.2, 18.2, 18.1, 18, 18.3, 18.3, 17.9, 18.3, 18, 19, 19.1, 17.8, 17.7, 17.4, 19.4, 21.1, 15, 18.2, 18.1, 17.8, 17.8, 18.8, 17.6, 15.9, 17.7, 19.5, 18, 17.8, 17.9, 18.5, 18.5, 17.5, 19, 17.9, 17.9, 17.7, 15.1, 18.2, 17.4, 18, 18.5, 19.4, 16.8, 17.5, 18.3, 18.3, 18.1, 18, 18, 13.7, 18.1, 17.8, 18.3, 17.6, 18, 17.7, 18.3, 17.7, 18.2, 18.1, 17.5, 18.7, 18, 18.1, 17.8, 17.9, 18.1, 18.1, 19.5, 18.2, 18, 17.4, 18.7, 18.3, 17.8, 18, 17.8, 18.6, 18, 18.7, 18.1, 18.4, 19.5, 17.9, 17.9, 18.1, 18.3, 18.1, 18.5, 17.7, 17.7, 18.1, 18.4, 17.9, 18, 18.1, 17.9, 18.4, 18, 18, 18.1, 17.9, 18.1, 17.8, 18.5, 17.6, 13.4, 14, 13.3, 13.3, 13.2, 13.3, 18.1, 17.8, 18, 18.1, 18.3, 17.8, 18.4, 18.3, 18.4, 18.3, 17.8, 18.1, 18.4, 18.2, 18, 18.1, 25, 17.8, 18.1, 18.8, 17.8, 17.7, 18.2, 17.9, 18.1, 17.9, 18.1, 17.9, 17.9, 17.5, 19.3, 18.6, 18.2, 17.9, 17.9, 18, 18.3, 17.8, 17.8, 18.1, 17.2, 17.8, 17.9, 18.1, 17.7, 18.4, 18, 18.6, 17.8, 18.3, 17.8, 18.2, 18.2, 11.2, 11.2, 11.1, 11.1, 17.3, 17.9, 17.6, 17.5, 17.8, 18.7, 17.6, 17.6, 17.6] }, "duration": 598.5, "summary": "", "weight": 598.5, "steps": [] } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }annotations=duration,distance
annotations=duration,distance처럼 필요한 항목만 선택적으로 지정할 수 있어, 데이터 크기를 줄이면서 원하는 정보만 효율적으로 활용할 수 있다.
각 세그먼트변 이동 시간과 거리를 반환하여, 세부 구간 단위 거리와 시간 정보를 확인할 수 있다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?annotations=duration,distance[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "distance": 9950.1, "annotation": { "distance": [34.62967587, 20.31779619, 11.48594557, 27.30444477, 72.14514248, 12.76367174, 96.56484055, 9.538321715, 3.066500932, 21.16514643, 3.736618083, 6.582939348, 1.68206729, 25.62569401, 111.2825597, 12.51519778, 10.85909053, 36.2829057, 21.79456266, 93.167278, 83.30276171, 33.95588381, 8.351007912, 19.34966164, 21.51101558, 75.64564767, 96.27793385, 67.39603735, 36.28903108, 55.71178001, 45.67679869, 34.85585428, 28.63992489, 63.91128146, 36.057776, 7.580228659, 11.4594225, 28.43624095, 21.21719127, 15.67951017, 11.65378724, 4.218486105, 2.996688147, 49.05697439, 72.50393084, 16.04332529, 26.63932143, 15.05909491, 21.14627992, 6.357304856, 17.71059134, 7.782643289, 28.85394015, 19.59777501, 57.25941334, 18.49817271, 16.62050612, 17.49931275, 15.18622309, 60.85378147, 41.15294845, 10.62683645, 3.017448335, 16.33919903, 22.65666204, 16.16969011, 12.95331807, 11.65219243, 11.78473562, 19.21292326, 23.79962453, 27.46417404, 36.11135157, 21.58612557, 30.56452898, 2.74962966, 34.38278907, 37.39685014, 23.81523395, 31.71989275, 25.21023895, 24.73715619, 25.57990543, 33.69380007, 38.12480145, 74.31129233, 26.22006038, 16.87198535, 19.84349072, 30.83349109, 74.9381419, 32.25269663, 54.36385287, 1538.030114, 11.71279371, 20.03743968, 41.3938215, 8.680942748, 18.68663613, 31.15335166, 23.16406828, 41.30200121, 44.51075965, 24.22641863, 16.16341474, 16.80849676, 27.12632056, 20.23887532, 11.69051365, 30.39957102, 71.41473302, 54.33909135, 47.64411999, 58.03498767, 31.46115254, 33.62407128, 24.78772598, 41.58256127, 36.80108825, 51.89639448, 82.91235583, 39.91926152, 42.92121193, 40.42082631, 86.49246507, 41.51349891, 74.06773002, 35.78156261, 29.01259788, 51.70223009, 22.18391931, 31.69357116, 18.76262332, 12.60203248, 86.50516126, 43.81063395, 43.61735505, 248.2067454, 215.6521011, 66.04433645, 239.3662332, 211.6725593, 76.68086214, 26.68351938, 36.70746231, 63.94109598, 27.65896963, 38.40897422, 57.07644166, 205.7780278, 23.88211699, 14.57091479, 82.8758803, 140.88686, 2.498663686, 17.83479109, 16.31342716, 20.63253395, 46.31489271, 24.7526809, 58.29332891, 91.45575411, 19.93914512, 82.56819181, 45.18956766, 59.05779537, 105.8397251, 19.25666061, 11.57004817, 24.16792264, 30.96047593, 116.4873058, 73.38899287, 50.33247141, 29.31803619, 37.43915365, 40.97449059, 72.28012025, 10.34506073, 58.82464657, 84.26611944, 128.5417118, 24.74310019, 23.94983324, 90.2171383, 27.90899952, 46.25453054, 38.34484372, 67.75091254, 49.27312245, 67.41580978, 31.31115514, 37.07216631, 88.00199737, 23.31387865, 15.53164676, 60.85085818, 28.19361287, 15.7780846, 42.7065927, 13.11949807, 7.032725855, 7.032725855, 7.031626918], "duration": [2.3, 1.3, 0.8, 2, 5.4, 1, 7.2, 0.5, 0.2, 1.2, 0.2, 0.4, 0.1, 1.4, 6.2, 0.7, 0.6, 2, 1.2, 5.2, 4.6, 1.9, 0.5, 1.1, 1.2, 4.2, 5.3, 3.7, 2, 3.1, 2.5, 1.9, 1.6, 3.5, 2, 0.4, 0.6, 1.6, 1.2, 0.9, 0.6, 0.2, 0.2, 2.7, 4, 0.9, 1.5, 0.8, 1.2, 0.4, 1, 0.4, 1.6, 1.1, 3.2, 1, 0.9, 1, 0.8, 3.4, 2.3, 0.6, 0.2, 0.9, 1.3, 0.9, 0.7, 0.6, 0.7, 1.1, 1.3, 1.5, 2, 1.2, 1.7, 0.2, 1.9, 2.1, 1.3, 1.8, 1.4, 1.4, 1.4, 1.9, 2.1, 4.1, 1.5, 0.9, 1.1, 1.7, 4.2, 1.8, 3, 85.2, 0.6, 1.1, 2.3, 0.5, 1, 1.7, 1.3, 2.3, 2.5, 1.3, 0.9, 0.9, 1.5, 1.1, 0.6, 1.7, 4, 3, 2.6, 3.2, 1.7, 1.9, 1.4, 2.3, 2, 2.9, 4.6, 2.2, 2.4, 2.2, 4.8, 2.3, 4.1, 2, 1.6, 2.9, 1.2, 1.8, 1.4, 0.9, 6.5, 3.3, 3.3, 18.6, 11.9, 3.7, 13.3, 11.7, 4.2, 1.5, 2, 3.5, 1.5, 2.1, 3.2, 11.4, 1.3, 0.8, 4.6, 7.8, 0.1, 1, 0.9, 1.1, 2.6, 1.4, 3.2, 5.1, 1.1, 4.6, 2.5, 3.3, 5.9, 1.1, 0.6, 1.3, 1.7, 6.5, 4.1, 2.8, 1.6, 2.1, 2.3, 4, 0.6, 3.3, 4.7, 7.1, 1.4, 1.3, 5, 1.5, 2.6, 2.1, 3.8, 2.7, 3.7, 2.8, 3.3, 7.9, 2.1, 0.9, 3.4, 1.6, 0.9, 2.4, 0.7, 0.4, 0.4, 0.4] }, "duration": 598.5, "summary": "", "weight": 598.5, "steps": [] } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }4) alternatives
alternatives는 목적지까지의 대안 경로(alternative routes)를 함께 반환할지 여부를 설정하는 파라미터이다.
값 설명 사용 사례 예시 false 하나의 경로만 반환한다. (기본값) 일반적인 경로 탐색 ?alternatives=false true 가능한 경우 여러 개의 대안 경로를 반환한다. 다양한 경로 옵션 제공 ?alternatives=true 숫자 반환할 대안 경로 개수를 지정한다. 특정 개수의 경로 추천 ?alternatives=2 alternatives=false
alternatives=false는 기본값으로, 가장 최적의 단일 경로만 반환하여 일반적인 경로 탐색이나 빠른 응답이 필요한 경우에 적합하다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?alternatives=false[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }alternatives=true
alternatives=true로 설정하면 시간, 거리 등의 조건에 따라 선택 가능한 여러 경로를 함께 제공하여, 사용자에게 다양한 이동 옵션을 제시하는 내비게이션 서비스에 활용할 수 있다.
e.g. routes[0], routes[1], routes[2] ...
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?alternatives=true[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 }, { "legs": [ { "steps": [], "weight": 730.8, "summary": "", "duration": 730.8, "distance": 12044.5 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@bFggAeHkpAl~@mD|AsWxH_Lzt@{g@|l@eKzbAmn@bTgTjm@|@zsBav@zQby@", "weight": 730.8, "duration": 730.8, "distance": 12044.5 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }5) geometries
geometries는 경로를 구성하는 좌표 데이터를 어떤 형식(format)으로 반환할지를 설정하는 파라미터이다.
값 설명 사용 사례 예시 polyline Google Encoded Polyline 형식 (기본값) 경량 경로 데이터 전달 ?geometries=polyline polyline6 polyline보다 높은 정밀도의 좌표 인코딩 정밀 경로 분석 ?geometries=polyline6 geojson GeoJSON 형식으로 좌표 반환 지도 라이브러리(Mapbox, Leaflet 등)와 연동 ?geometries=geojson geometries=polyline
geometries=polyline은 기본 형식으로, 좌표를 압축 인코딩하여 문자열로 반환하기 때문에 데이터 크기가 작고 전송 효율이 높다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?geometries=polyline[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "yhhdFmk_fW@tCcLk@|Ea~@zR@bZuIvHiOtTmE`oAwq@lKiOzWeHhg@m]~t@ap@tv@kOh{A{k@", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }geometries=polyline6
geometries=polyline6은 polyline보다 더 높은 정밀도(소수점 6자리)를 제공하여 보다 정확한 경로 표현이 필요한 경우에 사용된다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?geometries=polyline6[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": "y`|sfAq{beqFB~m@ebCyLldAeuRxeEDdnGoiBz`BcbDpwEy_Ap_XezNv{BkbDrwFqzAxqKyoHb{OqiN|kPybDfz[g_M", "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }geometries=geojson
geometries=geojson은 기본 polyline 형식 대신 GeoJSON 형식으로 경로를 반환하며, 위도·경도 좌표가 JSON 구조로 제공되어 사람이 이해하기 쉽다. 다양한 프론트엔드 지도 라이브러리에서 GeoJSON을 기본적으로 지원하기 때문에, 별도의 디코딩 과정 없이 바로 활용할 수 있어 호환성과 편의성이 높다.
사용 사례
- Leaflet
- Mapbox GL
- OpenLayers
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?geometries=geojson[응답 결과]
{ "code": "Ok", "routes": [ { "legs": [ { "steps": [], "weight": 598.5, "summary": "", "duration": 598.5, "distance": 9950.1 } ], "weight_name": "routability", "geometry": { "coordinates": [ [126.977993, 37.567005], [126.977241, 37.567003], [126.977462, 37.569102], [126.987545, 37.567991], [126.987542, 37.56481], [126.989246, 37.560471], [126.991856, 37.558905], [126.992893, 37.55544], [127.001008, 37.542631], [127.003622, 37.540635], [127.005087, 37.536657], [127.009964, 37.530212], [127.017813, 37.52157], [127.020434, 37.512659], [127.027606, 37.497887] ], "type": "LineString" }, "weight": 598.5, "duration": 598.5, "distance": 9950.1 } ], "waypoints": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 } ] }Route API의 파라미터는 단독으로 사용하는 것뿐만 아니라, 두 개 이상을 조합하여 더욱 다양한 형태의 결과를 얻을 수 있다. 예를 들어 steps=true와 annotations=duration,distance를 함께 설정하면 단계별 경로 안내 정보와 세그먼트 단위의 거리·시간 데이터를 동시에 확인할 수 있어, 단순 경로 조회를 넘어 보다 정밀한 분석이 가능하다. 이처럼 목적에 따라 여러 파라미터를 조합하면 응답 데이터를 원하는 형태로 유연하게 활용할 수 있다.
[요청 예시]
http://localhost:5000/route/v1/driving/126.9780,37.5665;127.0276,37.4979?steps=true&annotations=duration,distanceOSRM Route API 파라미터 정리 (Reference)
파라미터허용 값설명overview false / simplified / full 경로 전체 geometry 반환 수준을 설정한다. false는 반환하지 않음, simplified는 단순화된 경로, full은 전체 상세 경로를 반환한다. steps true / false 단계별 네비게이션 정보 반환 여부를 설정한다. true로 설정하면 좌회전, 우회전 등의 turn-by-turn 안내 정보가 포함된다. annotations true / false / distance / duration / speed 경로의 각 도로 구간(segment)에 대한 상세 정보를 반환한다. 거리, 시간, 속도 등의 데이터 분석에 사용된다. alternatives true / false / 숫자 대안 경로(alternative route)를 반환할지 여부를 설정한다. true이면 가능한 경우 여러 경로를 반환한다. geometries polyline / polyline6 / geojson 경로 geometry의 반환 형식을 지정한다. polyline은 기본 인코딩 형식, polyline6은 더 높은 정밀도, geojson은 GeoJSON 형식이다. continue_straight true / false 경유지에서 직진을 유지할지 여부를 설정한다. true이면 가능한 경우 유턴을 피하려고 한다. bearings bearing,range 특정 좌표에서 차량의 진행 방향을 지정한다. 예: 90,20은 90도 방향 ±20도 범위를 의미한다. radiuses 숫자 / unlimited 좌표가 매칭될 수 있는 도로의 최대 거리(미터)를 지정한다. GPS 오차를 보정할 때 사용된다. approaches unrestricted / curb 웨이포인트 접근 방향을 지정한다. curb는 도로 가장자리 방향에서만 접근하도록 제한한다. exclude toll / motorway / ferry 특정 도로 유형을 경로 계산에서 제외한다. 예: 유료도로, 고속도로, 페리 등. 2. OSRM API 살펴보기
OSRM은 단순히 경로를 계산하는 route API 외에도 다양한 기능을 제공하는 서비스 API를 포함하고 있다.
이 API들은 라우팅 분석, 지도 보정, 위치 매칭, 최적 경로 탐색 등 목적에 따라 활용할 수 있다.
대표적인 API는 다음과 같다.
- route (경로 계산)
- table (거리 행렬)
- nearest (가장 가까운 도로)
- match (GPS map matching)
- trip (TSP 경로)
- tile (라우팅 그래프 타일)
이 중 route를 제외한 API 5가지를 살펴보자.
1) Table API
table API는 여러 지점 간의 거리(distance) 또는 소요 시간(duration)을 행렬(matrix) 형태로 반환한다.
출발지와 도착지를 각각 여러 개 설정할 수 있어, 모든 지점 간의 이동 비용을 한 번에 계산할 수 있다.
주로 배차 시스템, 물류 최적화, 다중 목적지 경로 분석 등에 활용된다.예를 들어, N개의 지점을 입력하면 각 지점 간의 이동 비용을 계산하여 N × N 형태의 거리/시간 행렬이 생성된다.
[요청 예시]
http://localhost:5000/table/v1/driving/126.9780,37.5665;127.0276,37.4979;127.1054,37.3596[반환 결과]
{ "code": "Ok", "destinations": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 }, { "hint": "0jA2gJ0xNoAgAAAAJwAAAA4AAAAAAAAA4a8SQue2KULZQnxBAAAAACAAAAAnAAAADgAAAAAAAAAsBQAAfHmTBxoROgJ4eZMH8A86AgIA7xAAAAAA", "location": [127.105404, 37.359898], "name": "불정로", "distance": 33.07533333 } ], "durations": [ [0, 598.5, 1647.2], [591.4, 0, 1131.7], [1668.6, 1112.1, 0] ], "sources": [ { "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 }, { "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "location": [127.027606, 37.497887], "name": "서초대로", "distance": 1.537341475 }, { "hint": "0jA2gJ0xNoAgAAAAJwAAAA4AAAAAAAAA4a8SQue2KULZQnxBAAAAACAAAAAnAAAADgAAAAAAAAAsBQAAfHmTBxoROgJ4eZMH8A86AgIA7xAAAAAA", "location": [127.105404, 37.359898], "name": "불정로", "distance": 33.07533333 } ] }2) Nearest API
nearest API는 입력한 좌표에 대해 가장 가까운 도로 위의 지점을 찾아 반환한다.
GPS 좌표가 실제 도로에서 벗어나 있는 경우, 이를 도로 네트워크에 맞게 보정하는 데 사용된다.
위치 기반 서비스에서 초기 위치 보정이나 스냅(snap) 처리에 유용하다.[요청 예시]
http://localhost:5000/nearest/v1/driving/126.9780,37.5665[반환 결과]
{ "code": "Ok", "waypoints": [ { "nodes": [0, 6107335405], "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "location": [126.977993, 37.567005], "name": "세종대로20길", "distance": 56.0525781 } ] }3) Match API
match API는 여러 개의 GPS 좌표를 입력받아 실제 도로 위의 경로로 보정(map matching)해준다.
노이즈가 포함된 GPS 로그를 기반으로 사용자가 이동한 실제 경로를 추정할 수 있다.
주행 기록 분석, 이동 경로 복원, 차량 추적 서비스 등에 활용된다.[요청 예시]
http://localhost:5000/match/v1/driving/126.9780,37.5665;126.9790,37.5670;126.9800,37.5675?radiuses=50;50;50[반환 결과]{ "code": "Ok", "matchings": [ { "confidence": 0.9665650284, "legs": [ { "steps": [], "weight": 13.6, "summary": "", "duration": 13.6, "distance": 102.7 }, { "steps": [], "weight": 20.6, "summary": "", "duration": 20.6, "distance": 104 } ], "weight_name": "routability", "geometry": "qbhdFsq_fWo@_@aCKBuB}A?", "weight": 34.2, "duration": 34.2, "distance": 206.7 } ], "tracepoints": [ { "alternatives_count": 8, "waypoint_index": 0, "distance": 102.0857274, "name": "을지로", "location": [126.978978, 37.56601], "hint": "msQ6gP___38qAAAAKgAAAAAAAAAAAAAAUWBgQgAAAAAAAAAAAAAAACoAAAAqAAAAAAAAAAAAAAAsBQAAoouRBzo2PQLQh5EHJDg9AgAA3xAAAAAA", "matchings_index": 0 }, { "alternatives_count": 14, "waypoint_index": 1, "distance": 20.62610632, "name": "남대문로9길", "location": [126.979196, 37.566899], "hint": "JcQ6ACrEOoBLAAAAAAAAAAAAAAAAAAAA-q5QQgAAAAAAAAAAAAAAAEsAAAAAAAAAAAAAAAAAAAAsBQAAfIyRB7M5PQK4i5EHGDo9AgAADxEAAAAA", "matchings_index": 0 }, { "alternatives_count": 60, "waypoint_index": 2, "distance": 25.17056347, "name": "을지로1길", "location": [126.979792, 37.567345], "hint": "JsQ6gHnEOgBLAAAAAAAAAAAAAAAAAAAAV1ZPQgAAAAAAAAAAAAAAAEsAAAAAAAAAAAAAAAAAAAAsBQAA0I6RB3E7PQKgj5EHDDw9AgAADwAAAAAA", "matchings_index": 0 } ] }4) Trip API
trip API는 여러 지점을 입력받아 최적의 방문 순서를 계산하는 TSP(외판원 문제) 기반 경로를 반환한다.
모든 지점을 한 번씩 방문하는 가장 효율적인 경로를 자동으로 계산해준다.
배송 경로 최적화, 관광 코스 추천, 다중 목적지 이동 계획 등에 활용된다.[요청 예시]
http://localhost:5000/trip/v1/driving/126.9780,37.5665;127.0276,37.4979;127.1054,37.3596[반환 결과]{ "code": "Ok", "trips": [ { "legs": [ { "steps": [], "weight": 1647.2, "summary": "", "duration": 1647.2, "distance": 28429.1 }, { "steps": [], "weight": 1112.1, "summary": "", "duration": 1112.1, "distance": 18533.9 }, { "steps": [], "weight": 591.4, "summary": "", "duration": 591.4, "distance": 9524.8 } ], "weight_name": "routability", "geometry": "yhhdFmk_fWaLhB|Ea~@~m@sIbmFenDlbAbKnhF{xAtrNkuMh[xUvq@cDpRsh@hX|[zyAsFwxAjEsX_]mTbh@sk@|Ey`@gZcdLhoKmWkHk[pYwz@bCopBjbA_vCh|@yyAllAgxDtmB}Ct{@", "weight": 3350.7, "duration": 3350.7, "distance": 56487.8 } ], "waypoints": [ { "waypoint_index": 0, "distance": 56.0525781, "name": "세종대로20길", "location": [126.977993, 37.567005], "hint": "WMQ6gP___38KAAAAIQAAAAAAAAAVAAAAR7dxQcqECkIAAAAAEG7-QQoAAAAhAAAAAAAAABUAAAAsBQAAyYeRBx06PQLQh5EHJDg9AgAA3xAAAAAA", "trips_index": 0 }, { "waypoint_index": 2, "distance": 1.537341475, "name": "서초대로", "location": [127.027606, 37.497887], "hint": "ALcAgP___38EAAAABQAAAAAAAAAFAAAAFgPhQIMWsz8AAAAAIGokQQQAAAAFAAAAAAAAAAUAAAAsBQAAlkmSBx8sPAKQSZIHLCw8AgAAbwQAAAAA", "trips_index": 0 }, { "waypoint_index": 1, "distance": 33.07533333, "name": "불정로", "location": [127.105404, 37.359898], "hint": "0jA2gJ0xNoAgAAAAJwAAAA4AAAAAAAAA4a8SQue2KULZQnxBAAAAACAAAAAnAAAADgAAAAAAAAAsBQAAfHmTBxoROgJ4eZMH8A86AgIA7xAAAAAA", "trips_index": 0 } ] }5) Tile API
tile API는 OSRM의 내부 라우팅 데이터를 벡터 타일(Vector Tile) 형태로 제공한다.
도로 네트워크, 노드, 엣지 등의 정보를 시각화하거나 디버깅할 때 사용된다.
일반적인 서비스보다는 라우팅 엔진 분석, 데이터 검증, 지도 렌더링 최적화 등에 활용된다.[요청 예시]
http://localhost:5000/tile/v1/driving/14/13742/6341.mvtOSRM은 단순한 경로 탐색 엔진을 넘어,
위치 보정부터 경로 분석, 물류 최적화, 지도 디버깅까지 폭넓은 기능을 제공한다.
특히 table, match, trip API는 다중 지점 간 관계 분석과 경로 최적화가 중요한 물류 시스템이나 모빌리티 서비스에서
매우 유용하게 활용될 수 있다.
'Navigation' 카테고리의 다른 글
[Navigation] #3 OSRM 라우팅 서버 구축 실습 (Docker, 지도 데이터 전처리, Route API) (1) 2026.03.09 [Navigation] #2 OSRM을 알아보자 (0) 2026.02.23 [Navigation] #1 경로탐색은 어떻게 하는 것일까? (1) 2026.02.19