GraphHopper Routing Web API 完全指南/route、/info 与 /isochrone 端点实战【免费下载链接】graphhopperOpen source routing engine for OpenStreetMap. Use it as Java library or standalone web server.项目地址: https://gitcode.com/GitHub_Trending/gr/graphhopper导读GraphHopper 是面向 OpenStreetMap 数据的开源路由引擎既可作 Java 库嵌入也可作为独立 Web 服务器运行。本文以官方文档 docs/web/api-doc.md 为核心系统讲解开源路由服务器暴露的 HTTP 接口/route路径规划、/info服务与区域信息与/isochrone等时线。读完本文你将掌握 GET/POST 两种请求方式的全部参数语义、JSON 响应结构的每个字段、错误处理约定以及 Hybrid / Flexible / Public Transit 三种路由模式的区别并能在自己的服务器上直接构造可用的请求。一、前置知识URL 路径与请求方式本地实例默认监听http://localhost:8989三个核心端点为端点方法作用/routeGET / POST计算两点或多点之间的路径/infoGET返回服务版本、区域范围、可用 profile、编码值等元信息/isochroneGET计算从一点出发在给定时间/距离内可到达的区域多边形一个最简单的路径请求http://localhost:8989/route?point52.5300591%2C13.3565022point52.5060440%2C13.4378107其中%2C是逗号的 URL 编码即请求两个坐标点52.5300591,13.3565022与52.5060440,13.4378107纬度在前、经度在后两点之间即可得到一条路线。point参数可以重复出现多次顺序即途经顺序至少需要两个点。从源码看该端点在 RouteResource.java 中声明为Path(route)GET 与 POST 分别对应doGet与doPost方法/info对应 InfoResource.java 中的Path(info)/isochrone对应 IsochroneResource.java 中的Path(isochrone)。注意响应头中会附带X-GH-Took字段值为本次请求的耗时毫秒可直接用于性能观测见 RouteResource.java。二、HTTP POST突破 URL 长度限制GET 请求受 URL 长度限制当一次请求包含大量途经点时不再适用此时应改用 POST以 JSON 作为请求体。POST 与 GET 语义完全一致唯一区别是单数参数名改为复数形式。受影响的参数有point→pointssnap_prevention→snap_preventionscurbside→curbsidespoint_hint→point_hints而details保持不变。务必牢记坐标顺序差异GET 端点中point使用latitude,longitude顺序而 POST 的 JSON 中points使用[longitude, latitude]顺序。例如 GET 的point10,11point20,22对应如下 JSON{ points: [[11,10], [22,20]] }在 GHRequest.java 中points被定义为ListGHPoint经JsonProperty(points)序列化后即为上述数组结构。这一点从 GHPointDeserializer.java 的反序列化逻辑可以得到印证POST 请求体中的每个数组元素均按[lon, lat]解析。此外custom_model自定义模型参数仅支持 POST 请求因为其 JSON 结构复杂无法通过 URL 查询串表达详见下文 Flexible 模式。三、官方参数总览/route下表是/route端点的全部官方参数。所有参数的常量名均可对应 Parameters.java 中的定义例如instructions、calc_points、timeout_ms、via_point_instructions、pass_through、curbside_strictness、snap_prevention等。参数默认值说明point-指定用于计算路径的多个坐标点顺序即途经顺序至少两个点localeen返回转弯指引turn instructions的语言如pt_PT葡萄牙语、de德语instructionstrue是否计算并返回转弯指引profile-路径计算使用的 profile如car、bike、footelevationfalse为true时在 polyline 或 GeoJson 中加入第三维——海拔。重要开启后必须使用修改过的解码方法或将points_encoded设为false见points_encoded说明且如果车辆不支持海拔请求会失败可查看/info的 features 对象确认points_encodedtrue为false时point与snapped_waypoints以数组形式返回每点按[lon, lat, elevation]排列为true时坐标被编码为字符串节省带宽但客户端需要专门解码。仓库中 Java 侧的解码参考可查看 ResponsePathSerializer.java。特别注意开启elevationtrue时不要使用第三方客户端points_encoded_multiplier1e5当points_encodedtrue时用于把points字符串解码为坐标数组的精度因子calc_pointstrue是否计算并返回路径的坐标点设为false时只输出距离与时间响应更小point_hint-可选。在把point中的 GPS 坐标吸附snapping到最近道路时该提示会优先选择名称相似的道路。例如某个地址附近有两条相近的道路可用它指定优先走哪条街只填写路名、不要带门牌号以提高名称匹配质量snap_prevention[tunnel, bridge, ferry]吸附是指为point中的 GPS 坐标找到最近道路的过程。snap_prevention可禁止把点吸附到特定类型的道路上例如设为bridge时即使桥是最近的道路也会避免吸附。目前支持的值motorway、trunk、ferry、tunnel、bridge、ford。多值写法snap_preventionferrysnap_preventionmotorway。注意一旦吸附完成路径算法仍可能经过桥梁或其他被禁类型如需彻底避开需要使用custom_modeldetails-可选。请求附加的路径细节average_speed、street_name、edge_id、road_class、road_environment、max_speed、time等还可在graph.encoded_values中配置其他值。多值写法detailsaverage_speeddetailstime。每个 detail 片段返回格式为[fromRef, toRef, value]其中ref引用响应中 points 的索引若某段属性不存在value可为nullcurbsideany可选仅适用于边路由edge-based routing。指定起点/终点/途经点相对驾驶方向应位于哪一侧。可选值right、left、any需为每个 point 指定一次。与下文 heading 参数类似curbside_strictnessstrict可选。设为strict时若curbside无法满足例如单向道路指定了错误一侧将抛出异常不需要此行为时用softtimeout_ms无穷大可选。将请求运行时间限制为「给定毫秒数」与「服务端超时配置」两者中的较小值via_point_instructionstrue为true时指引中包含途经点指令如 Reached waypoint X到达途经点 X源码佐证在 RouteResource.java 的doGet方法中可以看到上述参数的 JAX-RS 声明其中points_encoded_multiplier默认值正是1e5instructions、calc_points、points_encoded默认trueelevation默认false。snap_prevention的默认值并非硬编码而是读取配置项routing.snap_preventions_default见 RouteResource.java默认展开为tunnel, bridge, ferry。四、三种路由模式及其专属参数GraphHopper 的路由引擎按加速数据结构分为三种模式CHContraction Hierarchies默认快速模式、Hybrid基于 Landmarks 的混合模式与 Flexible灵活模式。profile 在服务端配置阶段决定是否构建 CH / LM 数据结构请求端通过参数在模式间切换。4.1 Hybrid混合模式如果在配置中启用了 hybrid 模式即可在享受大部分 flexible 特性的同时获得加速。参数默认值说明ch.disablefalse设为true即为指定 profile 使用 hybrid 模式前提是该 profile 已启用 hybridLMlm.active_landmarks4不建议修改4.2 Flexible灵活模式通过每次请求携带ch.disabletrue或在服务端把profiles_ch配置为空列表来禁用 CH即可解锁以下灵活特性。唯一例外是algorithmalternative_route备选路线它无需ch.disabletrue也可使用。参数默认值说明ch.disablefalse与下表一个或多个参数配合使用custom_model-自定义路径计算逻辑。详见 自定义模型文档。仅 POST 请求可用algorithmastarbi路径计算算法可选dijkstra、astar、astarbi、alternative_route、round_tripheadingNaN为某个点指定优先朝向。可只为起点指定一个值也可为所有点各指定一个按顺序一一对应。角度为以正北为 0 的顺时针方向角取值 0–360 度。该参数也影响algorithmround_trip生成的行程并强制其初始方向heading_penalty300未满足指定 heading 时的惩罚值。惩罚以秒计对应相对无 heading 路径可接受的时间延迟。源码中常量定义见 Parameters.java 的DEFAULT_HEADING_PENALTY 300pass_throughfalse为true时结合heading_penalty在途经点避免 U 形转弯round_trip.distance10000当algorithmround_trip时配置生成的往返行程的大致长度米round_trip.seed0当algorithmround_trip时若首次结果不理想通过随机种子引入随机性alternative_route.max_paths2当algorithmalternative_route时最多计算的备选路径条数增大可能导致备选质量变差alternative_route.max_weight_factor1.4备选路线相对最优路线可长的权重倍数增大可能导致备选质量变差alternative_route.max_share_factor0.6备选路线与最优路线最大可共用的比例增大可能导致备选质量变差源码佐证round_trip.*、algorithm、timeout_ms、pass_through、heading_penalty等常量的组织方式可见 Parameters.javaRouting内部类与ROUND_TRIP相关前缀如ROUND_TRIP.distance、ROUND_TRIP.seed。custom_model必须配合profile参数使用否则 RouteResource.java 的 POST 处理会抛出专门异常The profile parameter is required when you use thecustom_modelparameter。4.3 Public Transit公共交通模式仅当使用ptprofile由gtfs.file配置启用见 InfoResource.java时适用。本仓库中的对应实现可参考 reader-gtfs 模块。参数默认值说明point-计算路径的多个坐标点顺序即途经顺序至少两个点localeen转弯指引的语言如pt_PT、dept.earliest_departure_time-行程最早出发时间ISO-8601 格式yyyy-MM-ddTHH:mm:ssZ如2020-12-30T12:56:00Zpt.arrive_byfalse为true时pt.earliest_departure_time被解释为行程最晚到达时间pt.profilefalse为true时返回一系列行程itineraries每个都是在指定时间窗口内从 A 到 B 的最优方案这种 profile 查询也叫 range query。时间窗口由pt.profile_duration指定默认上限 50 条可通过pt.limit_solutions调整pt.profile_durationPT60M1 小时profile 查询的时间窗口仅当pt.profiletrue时生效。时长字符串如PT200Spt.limit_street_time无限制公共交通上下车前后步行/骑行的最大时长即不在公共交通上的时间。时长字符串如PT30Mpt.ignore_transfersfalse是否忽略换乘次数这一优化标准pt.limit_solutions无限制最多搜索的方案数量五、JSON 响应结构详解请牢记文档未列出的响应属性在未来版本中可能被移除不应作为依赖。JSON 结果的核心结构如下JSON 路径/属性说明paths可能的路径数组paths[0].distance路径总距离单位米paths[0].time路径总耗时单位毫秒paths[0].ascend总爬升上坡单位米paths[0].descend总下降下坡单位米paths[0].points路径坐标。若points_encodedtrue或未指定返回编码字符串否则返回[lon, lat, elevation]顺序的数组见points_encoded参数paths[0].points_encoded为true表示 points 已编码为false时paths[0].points为路径的 GeoJson顺序 lon,lat,elevation更易处理但更耗带宽paths[0].bbox路径包围盒格式minLon, minLat, maxLon, maxLatpaths[0].snapped_waypoints吸附后的输入点。points_encodedtrue或未指定时返回编码字符串否则返回数组见points_encodedpaths[0].instructions路径指引信息。最后一条永远是 Finish结束指令耗时 0ms、距离 0 米。注意指引目前仍在积极开发中偶尔可能包含误导信息导航给用户时务必同时展示地图图像paths[0].instructions[0].text引导用户沿路径前进的文字描述语言取决于locale参数paths[0].instructions[0].street_name需要转入的街道名称paths[0].instructions[0].distance该指令对应的距离单位米paths[0].instructions[0].time该指令对应的时长单位毫秒paths[0].instructions[0].interval包含首尾索引的数组相对paths[0].points用于定位该指令生效的路径点区间paths[0].instructions[0].sign指示显示的转向符号编号如 2 表示右转。完整对照如下paths[0].instructions[0].exit_number[可选] 仅 USE_ROUNDABOUT 指令包含。离开环岛时的出口计数paths[0].instructions[0].exited[可选] 仅 USE_ROUNDABOUT 指令包含。为true表示应驶出环岛为false表示途经点或终点位于环岛内因此本指令不应驶出环岛paths[0].instructions[0].turn_angle[可选] 仅 USE_ROUNDABOUT 指令包含。环岛内的弧度顺时针0 r 2*PI逆时针-2PI r 0旋转方向未定义时为NaNsign字段的完整取值对照KEEP_LEFT -7 TURN_SHARP_LEFT -3 TURN_LEFT -2 TURN_SLIGHT_LEFT -1 CONTINUE_ON_STREET 0 TURN_SLIGHT_RIGHT 1 TURN_RIGHT 2 TURN_SHARP_RIGHT 3 FINISH 4 REACHED_VIA 5 USE_ROUNDABOUT 6 KEEP_RIGHT 7 其余数值请为客户端实现默认处理完整响应示例{ paths: [{ bbox: [ 13.362853824187303, 52.469481955531585, 13.385836736460217, 52.473849308838446 ], distance: 2138.3027624572337, instructions: [ { distance: 1268.519329705091, interval: [ 0, 10 ], sign: 0, text: Geradeaus auf A 100, time: 65237 }, { distance: 379.74399999999997, interval: [ 10, 11 ], sign: 0, text: Geradeaus auf Strasse, time: 24855 }, { distance: 16.451, interval: [ 11, 11 ], sign: 0, text: Geradeaus auf Tempelhofer Damm, time: 1316 }, { distance: 473.58843275214315, interval: [ 11, 12 ], sign: -2, text: Links abbiegen auf Tempelhofer Damm, B 96, time: 37882 }, { distance: 0, interval: [ 12, 12 ], sign: 4, text: Ziel erreicht!, time: 0 } ], points: oxg_Iy|ppAlwCdE}LfFsN|_EjeEtAaMhsGVuDNcDb{PFyGdAi]FoC?qsXQ_?, points_encoded: true, details:{ street_name:[[0,1,Rue Principale],[1,13,D19E],[13,18,D19],..] }, time: 129290 }] }注意示例中points是一段 Polyline 编码字符串points_encoded: true而details.street_name以[起始索引, 结束索引, 街道名]三段式返回与上文details参数的格式约定一致。该序列化逻辑在 ResponsePathSerializer.java 中实现。六、/info服务与区域信息如果需要了解服务端区域信息或做连通性测试ping请访问/infohttp://localhost:8989/info示例输出{ build_date:2023-02-21T16:52, bbox:[13.072624,52.333508,13.763972,52.679616], version:8.0, elevation: false, profiles: [{ name: foot, }], ... }属性说明JSON 路径/属性说明versionGraphHopper 版本bbox区域最大包围盒格式minLon, minLat, maxLon, maxLatfeatures每个受支持车辆的 JSON 对象含名称与支持的特性如 elevationbuild_date[可选] GraphHopper 构建日期import_date[可选] OSM 数据导入时间encoded_values可用于 path details 或 custom_model 的编码值列表profiles支持的 profiles 数组源码佐证在 InfoResource.java 中可以看到bbox直接取自baseGraph.getBounds()即导入数据的实际地理范围profiles遍历config.getProfiles()生成且当配置了gtfs.file时会额外追加名为pt的 profileelevation由服务端是否启用高程hasElevation决定import_date、data_date分别来自存储属性datareader.import.date与datareader.data.date。而encoded_values的生成逻辑InfoResource.java会遍历所有编码值枚举型EnumEncodedValue列出全部可选枚举值布尔型BooleanEncodedValue列出true/false数值型DecimalEncodedValue、IntEncodedValue标记为number/number配置了graph.encoded_values.private的私有编码值则会被过滤不返回。七、错误输出与 HTTP 状态码当请求出错时例如某个点远离道路导致无法吸附响应形如{ message: Cannot find point 2: 2248.224673, 3.867187, hints: [{message: something, ...}] }有时点会偏离道路而得到cannot find point这通常不代表路由引擎存在 bug——当点离道路过远时一定程度的失败是符合预期的。JSON 路径/属性说明message错误信息。未做翻译不应直接展示给终端用户hints关于错误详情的可选列表如[{message: first error message in hints}]HTTP 错误码约定HTTP 状态码原因500服务器内部错误。极可能是系统 bug强烈建议记录 message 与请求链接以便上报501仅支持特定的车辆列表400请求本身有误从源码看/route的 GET 分支在ghResponse.hasErrors()时返回400 Bad Request并携带MultiException实体RouteResource.javaPOST 分支则直接抛出MultiExceptionRouteResource.java由 Jersey 异常映射器统一转换为 HTTP 响应。另外注意/route同样支持 XML 与 GPX 输出typejson|xml|gpxGPX 由 GpxConversions.java 生成目前备选路线alternatives尚不支持 GPX 输出且返回时会作为附件GraphHopper.gpx下载RouteResource.java。八、/isochrone等时线计算除路径规划外等时线端点为/isochrone若需要点列表而非多边形可参考/spt端点。典型请求http://localhost:8989/isochrone参数总览参数默认值说明profile-等时线计算使用的 profilebuckets1把给定的time_limit划分为buckets份生成buckets个嵌套等时线时间间隔为time_limit - n*time_limit/buckets其中n[0,buckets)对distance_limit同理适用reverse_flowfalse为false时流量从点到多边形例如30 分钟内从你的店铺出发能到达多少潜在客户为true时流量从多边形内部到点例如30 分钟内有多少客户能到达你的店铺point-起始坐标必填字符串格式为latitude,longitudetime_limit600车辆行驶时间单位秒distance_limit-1车辆行驶距离单位米默认 -1 表示不启用pt.earliest_departure_time-行程最早出发时间。仅当使用ptprofile 时适用且必填其他参数见上文 Public Transit 章节源码佐证在 IsochroneResource.java 中buckets通过Range(min 1, max 20)限制为 1–20time_limit默认 600 秒、distance_limit默认 -1。除文档表格外该端点还支持若干额外参数weight_limit权重上限默认 -1优先级高于distance_limit源码中先判断weight_limit 0再判断distance_limit 0最后回落到time_limit见 IsochroneResource.javatypejson或geojson默认jsongeojson 返回标准的 FeatureCollection见 IsochroneResource.javatolerance多边形简化容差米默认 0full_geometry默认false为true时返回完整 MultiPolygon否则只保留包含起始点或点数最多的主连通分量。实现上/isochrone内部会禁用 CH 与 Landmarks 加速hintsMap.putObject(Parameters.CH.DISABLE, true)与Parameters.Landmark.DISABLE见 IsochroneResource.java基于 ShortestPathTree.java 构建最短路径树再经 Triangulator.java 三角化与 ContourBuilder.java 等值线提取生成多边形。reverse_flow参数直接决定ShortestPathTree的流向IsochroneResource.java。仓库中另有 IsochroneExample.java 展示 Java 库方式调用等时线的完整流程可作为对照参考。九、客户端接入建议API 是语言无关的纯 HTTP 接口你既可以直接解析 JSON也可以使用官方维护的 JS / Java 客户端封装。在本仓库内可以重点参考以下实现与测试作为自研客户端的范本Java 客户端GraphHopperWeb.javaclient-hc模块完整实现了/route请求构造与编码点解码矩阵与地理编码客户端GraphHopperMatrixWeb.java、GraphHopperGeocoding.java响应解析ResponsePathSerializer.java 是服务端 JSON 序列化的核心也是理解响应字段语义的最佳入口请求对象GHRequest.java 定义了 POST 请求体的全部字段测试用例RouteResourceRepresentationTest.java、ResponsePathRepresentationTest.java、GraphHopperWebTest.java 覆盖了请求序列化与响应反序列化的诸多边界情况是校验客户端行为的可靠依据。说明若使用elevationtrue务必使用官方/自研且支持高程的解码逻辑或直接points_encodedfalse切勿使用未适配高程的第三方客户端否则坐标解码将出错。总结本文以官方 Web API 文档为骨架系统梳理了 GraphHopper 开源路由服务器的三个核心 HTTP 端点/routeGET 轻量请求与 POST 大批量请求覆盖 16 个通用参数及 Hybrid / Flexible / Public Transit 三套模式专属参数/info版本、bbox、profiles、encoded_values 等服务元信息是客户端自动发现能力的入口/isochrone时间/距离/权重三种限制方式下的等时线多边形计算。同时结合仓库源码RouteResource.java、InfoResource.java、IsochroneResource.java、Parameters.java补充了各参数的默认值来源、服务端校验规则与内部算法链路。掌握以上内容后你可以直接基于纯 JSON 协议在任何语言中构建路由客户端或借助本仓库的 client-hc 模块快速集成路径规划能力。【免费下载链接】graphhopperOpen source routing engine for OpenStreetMap. Use it as Java library or standalone web server.项目地址: https://gitcode.com/GitHub_Trending/gr/graphhopper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考