Skip to content

Configuration via ors-config.json

WARNING

The ors-config.json is deprecated! Migrate to ors-config.yml.

The "old" configuration method is supported for a while for convenience. The description below is kept as long as openrouteservice still supports configuration via JSON file, but we do not recommend using this configuration method. Please consider migrating your JSON configuration to the new style. Note that currently all settings in a provided JSON configuration file will override any settings in the YAML file.

ors

The top level element.

keytypedescriptionexample value
servicesobjectan object comprising the servicesservices
loggingobjectthe logging propertieslogging
system_messagelistList of system message objectssystem messages

ors.services

keytypedescriptionexample value
ors.services.routingobjectsettings for routing and its profilesrouting
ors.services.isochronesobjectsettings for isochrones restrictionsisochrones
ors.services.matrixobjectsettings for matrix restrictionsmatrix
ors.services.snapobjectsettings for snapsnap

ors.services.routing

keytypedescriptionexample value
enabledbooleanEnables or disables (true/false) the end-point. Default value is true.true
modestringCan be either "normal" or "preparation". If "preparation" then graphs will be built and the service will be shut down afterwards."normal"
descriptionstring"This is a routing file from openrouteservice"
routing_namestringSpecifies the gpx name tag that is returned in a gpx response"openrouteservice"
sourceslistthe osm file to be used, formats supported are .osm, .osm.gz, .osm.zip and .pbf["heidelberg.osm.gz"]
init_threadsnumberThe number of threads used to initialize (build/load) graphs. Higher numbers requires more RAM.2
attributionstringAttribution added to the response metadata"openrouteservice.org, OpenStreetMap contributors"
elevation_preprocessedbooleanEnables or disables reading ele tags for nodes. Default value is false. If enabled, GH's elevation lookup is prevented and all nodes without ele tag will default to 0. Experimental, for use with the ORS preprocessorfalse
profilesobjectprofiles

ors.services.routing.profiles
keytypedescriptionexample value
activelistDefines a list of active routing profiles. The element name XXX must correspond to a notation "profile-XXX", which is used in the following sections. Can be one or many of "car", "hgv", "bike-regular", "bike-mountain", "bike-road", "bike-electric", "walking", "hiking" or "wheelchair"["car", "bike-regular"]
default_paramsobjectSet parameters that is applied to every profile by defaultdefault_params
profile-XXXobjectSettings that are applied to the specific profile. You may run multiple profiles at once.profile-XXX

ors.services.routing.profiles.default_params
keytypedescriptionexample value
encoder_flags_sizenumberThe number of bytes used for FlagEncoders8
graphs_root_pathstringThe root path to a directory for storing graphs"../graphs"
elevation_providerstringThe name of an elevation provider. Possible values are multi, cgiar or srtm"multi"
elevation_cache_pathstringThe path to a directory in which SRTM tiles will be stored"elevation_cache"
elevation_cache_clearbooleankeep elevation data once it has been downloadedfalse
elevation_smoothingbooleansmooth out elevation datafalse
instructionsbooleanSpecifies whether way names will be stored during the import or nottrue
maximum_distancenumberThe maximum allowed total distance of a route100000
maximum_segment_distance_
with_dynamic_weights
numberThe maximum allowed distance between two way points when dynamic weights are used50000
maximum_waypointsnumberThe maximum number of way points in a request50
maximum_snapping_radiusnumberMaximum distance around a given coordinate to find connectable edges100
maximum_distance_round_trip_routesnumberThe maximum allowed total distance of a route for the round trip algo100000
maximum_distance_alternative_routesnumberThe maximum allowed total distance of a route for the alternative route algo100000
maximum_alternative_routesnumberThe maximum number of alternative routes in a request3
maximum_avoid_polygon_areanumberThe maximum allowed total area of a polygon in square kilometers, optional200000000
maximum_avoid_polygon_extentnumberThe maximum extent (i.e. envelope side length) of a polygon in kilometers, optional20000
location_index_resolutionnumberThe minimum resolution in meters of tiles in the location index. Lower values yield faster queries at a cost of increased memory requirements. Reducing the resolution reduces the lookup radius which can be compensated by increasing location_index_search_iterations. Corresponds to GraphHopper's index.high_resolution configuration parameter.500 (default)
location_index_search_iterationsnumberThe maximum number of iterations performed in coordinates lookup. Higher values yield a broader search area, but might reduce query performance. It only affects the storage lookup but not its layout so changing this parameter does not require rebuilding the location index. Corresponds to GraphHopper's index.max_region_search configuration parameter.4 (default)
maximum_speed_lower_boundnumberSpecifies the threshold for the query parameter maximum_speed.80 (default)
interpolate_bridges_and_tunnelsbooleanInterpolate elevation of bridges and tunnels.true (default)
preparationobject...preparation
executionobject...execution

ors.services.routing.profiles.default_params.preparation
keytypedescriptionexample value
min_network_sizenumberMinimum size (number of edges) of an independent routing subgraph200
methodsobjectmethods
ors.services.routing.profiles.default_params.preparation.methods
keytypedescriptionexample value
chobjectSettings for preprocessing contraction hierarchiesch
lmobjectSettings for preprocessing landmarkslm
coreobjectSettings for preprocessing landmarkscore
ors.services.routing.profiles.default_params.preparation.methods.ch
keytypedescriptionexample value
enabledbooleantrue
threadsnumber1
weightingsstring"recommended"
ors.services.routing.profiles.default_params.preparation.methods.lm
keytypedescriptionexample value
enabledbooleantrue
threadsnumber1
weightingsstring"recommended,shortest"
landmarksnumberTotal number of precomputed landmarks, the subset used during the query is set in active_landmarks16
ors.services.routing.profiles.default_params.preparation.methods.core
keytypedescriptionexample value
enabledbooleantrue
threadsnumber1
weightingsstring"recommended,shortest"
landmarksnumberTotal number of precomputed landmarks, the subset used during the query is set in active_landmarks32
lmsetsstring"highways,tollways;highways;tollways;country_193;allow_all"

ors.services.routing.profiles.default_params.execution
keytypedescriptionexample value
methodsobjectmethods
ors.services.routing.profiles.default_params.execution.methods
keytypedescriptionexample value
chobjectSettings for using contraction hierarchies in routingch
lmobjectSettings for using landmarks in routinglm
coreobjectSettings for using landmarks in routingcore
ors.services.routing.profiles.default_params.execution.methods.lm
keytypedescriptionexample value
active_landmarksnumberNumber of landmarks used for computing the route8
ors.services.routing.profiles.default_params.execution.methods.core
keytypedescriptionexample value
active_landmarksnumberNumber of landmarks used for computing the route6

ors.services.routing.profiles.profile-XXX
keytypedescriptionexample value
profilesstringname of the profile when called via the APIdriving-car
parametersobjectthe specific profile parameters of an profileparameters
ors.services.routing.profiles.profile-XXX.parameters
keytypedescriptionexample value
encoder_optionsstring`"turn_costs=true\
elevationbooleanThis will enable the elevation information in the responsetrue
maximum_distancenumberMaximum distance a route can have in meters100000
maximum_snapping_radiusnumberMaximum distance around a given coordinate to find connectable edges100
maximum_distance_round_trip_routesnumberThe maximum allowed total distance of a route for the round trip route algo100000
maximum_distance_alternative_routesnumberThe maximum allowed total distance of a route for the alternative route algo100000
maximum_alternative_routesnumberThe maximum number of alternative routes in a request3
maximum_avoid_polygon_areanumberThe maximum allowed total area of a polygon in square kilometers, optional200000000
maximum_avoid_polygon_extentnumberThe maximum extent (i.e. envelope side length) of a polygon in kilometers, optional20000
ext_storagesobjectControls which external storages are enabledexternal storages
gtfs_filestringOnly for pt profile: location of gtfs-file used. Can either be a zip-file or the unzipped folder."src/test/files/vrn_gtfs_cut.zip"
ors.services.routing.profiles.profile-XXX.parameters.encoder_options
keytypedescriptionexample value
problematic_speed_factornumberFor wheelchair profile only! Travel speeds on edges classified as problematic for wheelchair users are multiplied by this factor, use to set slow traveling speeds on such waysproblematic_speed_factor=0.7
preferred_speed_factornumberFor wheelchair profile only! Travel speeds on edges classified as preferable for wheelchair users are multiplied by this factor, use to set faster traveling speeds on such wayspreferred_speed_factor=1.2
ors.services.routing.profiles.profile-XXX.parameters.ext_storages
keytypedescriptionexample value
WayCategoryobjectReturns the way category in the route response, Compatible for any profile type{}
WaySurfaceTypeobjectReturns the way surface in the route response, Compatible for any profile type{}
HillIndexobjectReturns the ascent/descent in the route response, Compatible for any profile type{}
TrailDifficultyobjectReturns the trail difficulty in the route response, Compatible for profile-hiking{}
RoadAccessRestrictionsobjectRoadAccessRestrictions are where roads are restricted to certain vehicles to certain circumstances, e.g. access=destination. The use_for_warnings parameter tells the ors that this storage can be used for generating warning messages in the route response. For RoadAccessRestrictions, this means that whenever a route goes over a way which has some restrictions, a warning message will be delivered with the response and the roadaccessrestrictions extra info automatically added.{ use_for_warnings: true }
WheelchairobjectCompatible for wheelchair{ KerbsOnCrossings: "true" }
OsmIdobjectReturns the OsmId of the way, Compatible for wheelchair{}
BordersobjectBorders allows the restriction of routes to not cross country borders, compatible for any profile typeBorders
ors.services.routing.profiles.profile-XXX.parameters.ext_storages.Borders
keytypedescriptionexample value
boundariesstringThe path to a file containing geojson data representing the borders of countries'borders.geojson.tar.gz'
idsstringPath to a csv file containing a unique id for each country, its local name and its English name'ids.csv'
openbordersstringPath to a csv file containing pairs of countries where the borders are open (i.e. Schengen borders)'openborders.csv'

ors.services.isochrones

keytypedescriptionexample value
enabledbooleanEnables or disables (true/false) the end-point (default: true)true
maximum_range_distancelistPossible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile[{profiles: "any", value: 50000}, {profiles: "driving-car, driving-hgv", value: 100000}]
maximum_range_timelist[{profiles: "any", value: 18000},{profiles: "driving-car, driving-hgv", value: 3600}]
maximum_intervalsnumberMaximum number of intervals/isochrones computed for each location10
maximum_locationsnumberMaximum number of locations in one request2
allow_compute_areanumberSpecifies whether area computation is allowedtrue
ors.services.isochrones.fastisochrones
keytypedescriptionexample value
maximum_range_distancelistPossible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile[{profiles: "any", value: 50000}, {profiles: "driving-car, driving-hgv", value: 100000}]
maximum_range_timelist[{profiles: "any", value: 18000},{profiles: "driving-car, driving-hgv", value: 3600}]
ors.services.isochrones.fastisochrones.profiles.default_params
keytypedescriptionexample value
enabledbooleantrue
threadsnumber1
weightingsstring"recommended,shortest"
maxcellnodesnumberMaximum number of nodes allowed in single isochrone cell5000

ors.services.matrix

keytypedescriptionexample value
enabledbooleanEnables or disables (true/false) the end-point (default: true)true
maximum_routesnumberMaximum amount of routes the matrix should compute. E.g. 2500 could be a 50x50 matrix or 1x2500 matrix2500
maximum_routes_flexiblenumberMaximum amount of routes for using custom profiles that do not support contraction hierarchies25
maximum_search_radiusnumberMaximum allowed distance between the requested coordinate and a point on the nearest road. The value is measured in meters5000
maximum_visited_nodesnumberMaximum allowed number of visited nodes in shortest path computation. This threshold is applied only for Dijkstra algorithm100000
allow_resolve_locationsnumberSpecifies whether the name of a nearest street to the location can be resolved or not. Default value is truetrue
attributionstringAttribution added to the response metadata"openrouteservice.org, OpenStreetMap contributors"

ors.services.snap

keytypedescriptionexample value
enabledbooleanEnables or disables (true/false) the end-point (default: true)true
attributionstringAttribution added to the response metadata"openrouteservice.org, OpenStreetMap contributors"
maximum_locationsnumberMaximum number of locations in one request5000

ors.logging

keytypedescriptionexample value
enabledbooleanEnables or disables the end-point (default: true)true
level_filestringCan be either DEBUG_LOGGING.json or PRODUCTION_LOGGING.json"DEBUG_LOGGING.json"
locationstringLocation of the logs"/var/log/ors"
stdoutbooleantrue

ors.system_message

Array of message objects where each has

keytypedescriptionexample value
activebooleanEnables or disables this messagetrue
textstringThe message text"The message text"
conditionobjectoptional; may contain any of the conditions from the table below
conditionvaluedescription
time_beforeISO 8601 datetime stringmessage sent if server local time is before given point in time
time_afterISO 8601 datetime stringmessage sent if server local time is after given point in time
api_version1 or 2message sent if API version requested through matches value
api_formatString with output formats ("json", "geojson", "gpx"), comma separatedmessage sent if requested output format matches value
request_serviceString with service names ("routing", "matrix", "isochrones"), comma separatedmessage sent if requested service matches one of the given names
request_profileString with profile names, comma separatedmessage sent if requested profile matches one of the given names
request_preferenceString with preference (weightings for routing, metrics for matrix, rangetype for isochrones) names, comma separatedmessage sent if requested preference matches one of the given names
Example:
system_message: [
    {
        active: true,
        text: "This message would be sent with every routing bike fastest request. E.g. 'The fastest weighting for cycling profiles is deprecated, use recommended weighting instead. API will be kept for compatibility until release of version 7.0.0'",
        condition: {
            "request_service": "routing",
            "request_profile": "cycling-regular,cycling-mountain,cycling-road,cycling-electric",
            "request_preference": "fastest"
        }
    },
    {
        active: true,
        text: "This message would be sent with every request for geojson response.",
        condition: {
            "api_format": "geojson"
        }
    },
    {
        active: true,
        text: "This message would be sent with every request on API v1 from January 2020 until June 2050. E.g. 'The V1 API is deprecated. You should switch to using the V2 API.'",
        condition: {
            "api_version": "1",
            "time_after": "2020-01-01T00:00:00Z",
            "time_before": "2050-06-01T00:00:00Z"
        }
    },
    {
        active: true,
        text: "This message would be sent with every request. E.g. 'Scheduled downtime due to version upgrade on March 15th 2020, 12:00 AM CET for approx. 3 hours.'"
    }
]