Heatstress Routing App¶
Thanks to recent advances in sensor system solutions together with the smart city movement, various data sources related to temperature are increasingly available. For instance, one can exploit temperature measurements to minimize the impact of heat stress on humans regarding their daily routines and walking paths 1.
Example for Heat Based Routing, taken from Rußig & Bruns, 2017 1.
Note
Related repository is https://github.com/biggis-project/path-optimizer
Related Scenarios: Smart City
About the App backend¶
The back-end exposes a simple REST-API, that can be used for routing or to find
the optimal point in time. The API can be accessed on http://localhost:8080/heatstressrouting/api/v1
.
JSON is supported as the only output format.
The following sections describe the API in detail.
Server information¶
URL: http://localhost:8080/heatstressrouting/api/v1/info
Returns some information about the running service, e.g. the supported area and time range
Parameters¶
The /info
site takes no parameters.
Returns¶
Returns some information about the running service (see sample response below):
bbox
: the bounding box of the area supported by the service as an array of[min_lat, min_lng, max_lat, max_lng]
.time_range
: the time range supported by the service, given as time stamps of the form2014-08-23T00:00
.place_types
: a list of place types supported by the optimal time api
Example¶
Sample Request:
http://localhost:8080/heatstressrouting/api/v1/info
Sample Response:
{ "service": "heat stress routing", "version": "0.0.1-SNAPSHOT", "build_time": "2016-09-27T07:50:42Z", "bbox": [ 48.99, 8.385, 49.025, 8.435 ], "time_range": { "from": "2014-08-23T00:00", "to": "2016-02-23T23:00" }, "place_types": [ "bakery", "taxi", "post_office", "ice_cream", "dentist", "post_box", "supermarket", "toilets", "bank", "cafe", "police", "doctors", "pharmacy", "drinking_water", "atm", "clinic", "kiosk", "hospital", "chemist", "fast_food" ] }
Routing¶
URL: http://localhost:8080/heatstressrouting/api/v1/routing
Computes the optimal route (regarding heat stress) between a start and a destination at a given time.
Parameters¶
The /routing
api supports the following parameter (some are optional):
start
: the start point as pair of a latitude value and longitude value (in that order) seperated by a comma, e.g.start=49.0118083,8.4251357
.destination
: the destination as pair of a latitude value and longitude value (in that order) separated by a comma, e.g.destination=49.0126868,8.4065707
.time
: the date and time the optimal route should be searched for; a time stamp of the formYYYY-MM-DDTHH:MM:SS
, e.g.time=2015-08-31T10:00:00
. The value must be in the time range returned by/info
(see above).weighting
(optional): the weightings to be used; a comma seperated list of the supported weightings (shortest
,heatindex
andtemperature
), e.g.weighting=shortest,heatindex,temperature
; the default isweighting=shortest,heatindex
; the results for theshortest
weighting are always returned, even if the value is omited in the weighings list.
Returns¶
The path and some other information for each of the weightings:
status
: the status of the request;OK
is everthing is okay,BAD_REQUEST
if a invalid request was send orINTERNAL_SERVER_ERROR
if an internal error occoured.status_code
: the HTTP status code returned.results
: the results for each weighting:weighting
: the weighting used for that result (see parameterweighting
above).start
: the coordinates of the start point as array of[lat, lng]
.destination
: the coordinates of the destination as array of[lat, lng]
.distance
: the length of the route in meter.duration
: the walking time in milli seconds.route_weights
: the route weights of the selected weightings for the route.path
: the geometry of the path found; an array of points, were each point is an array of [lat, lng]`.
Example¶
Sample Request:
http://localhost:8080/heatstressrouting/api/v1/routing?start=49.0118083,8.4251357&destination=49.0126868,8.4065707&time=2015-08-31T10:00:00&weighting=shortest,heatindex,temperature
Sample Response:
{ "status": "OK", "status_code": 200, "results": { "shortest": { "weighting": "shortest", "start": [ 49.0118083, 8.4251357 ], "destination": [ 49.0126868, 8.4065707 ], "distance": 1698.2989202985977, "duration": 1222740, "route_weights": { "temperature": 50903.955833052285, "heatindex": 50892.20496302502, "shortest": 1698.2989202985977 }, "path": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.01225359765262, 8.425994591995952 ], // points omitted ... [ 49.01272775130067, 8.406514897340614 ] ] }, "heatindex": { "weighting": "heatindex", "start": [ 49.0118083, 8.4251357 ], "destination": [ 49.0126868, 8.4065707 ], "distance": 1901.8839202985973, "duration": 1369323, "route_weights": { "temperature": 51868.74807902536, "heatindex": 51098.277424417196, "shortest": 1901.8839202985978 }, "path": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.01225359765262, 8.425994591995952 ], // points omitted ... [ 49.01272775130067, 8.406514897340614 ] ] }, "temperature": { "weighting": "temperature", "start": [ 49.0118083, 8.4251357 ], "destination": [ 49.0126868, 8.4065707 ], "distance": 1901.8839202985973, "duration": 1369323, "route_weights": { "temperature": 51868.74807902536, "heatindex": 51098.277424417196, "shortest": 1901.8839202985978 }, "path": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.01225359765262, 8.425994591995952 ], // points omitted ... [ 49.01272775130067, 8.406514897340614 ] ] } } }
Optimal time¶
URL: http://localhost:8080/heatstressrouting/api/v1/optimaltime
Performce a nearby search for a given start point and computes for every place that fulfills a specified criterion an optimal point in time, i.e. the time with the minimal heat stress.
Parameters¶
The /optimaltime
api supports the following parameter (some are optional):
start
: the start point as pair of a latitude value and longitude value (in that order) seperated by a comma, e.g.start=49.0118083,8.4251357
.time
: the date and time the optimal route should be searched for; a time stamp of the formYYYY-MM-DDTHH:MM:SS
, e.g.time=2015-08-31T10:00:00
. The value must be in the time range returned by/info
(see above).place_type
: the place type to search for; a comma seperated list of supported place types, e.g.place_type=supermarket,chemist
; a complete list of supported place list can be queried using theinfo
api (see above). Currently the following place tyes are supported:bakery
,taxi
,post_office
,ice_cream
,dentist
,post_box
,supermarket
,toilets
,bank
,cafe
,police
,doctors
,pharmacy
,drinking_water
,atm
,clinic
,kiosk
,hospital
,chemist
,fast_food
. The place types are mapped to the correspondingshop
respectivelyamenity
tags.max_results
(optional): the maximum number of results to consider for the nearby search (an positive integer), e.g.max_results=10
; the default value is 5.max_distance
(optional): the maximum direct distance (as the crow flies) between the start point and the place in meter, e.g.max_distance=500.0
; the default value is 1000.0 meter.time_buffer
(optional): the minimum time needed at the place (in minutes), i.e. the optimal time is chossen so that the place is opened for a leasttime_buffer
when the user arrives, e.g.time_buffer=30
; the default value is 15 miniutes.earliest_time
(optional): the earliest desired time, either a time stamp, e.g.earliest_time=2015-08-31T09:00
or the stringnull
(case is ignored); the default value isnull
. If bothearliest_time
andlatest_time
are specified,earliest_time
must be beforelatest_time
.latest_time
(optional): the latest desired time, either a time stamp, e.g.latest_time=2015-08-31T17:00
or the stringnull
(case is ignored); the default value isnull
. If bothearliest_time
andlatest_time
are specified,earliest_time
must be beforelatest_time
;latest_time
must be aftertime
.
Returns¶
The optimal point in time for each place found in the specified radius ranked by the optimal-value:
status
: the status of the request;OK
if everthing is okay,NO_REULTS
if not results were found,BAD_REQUEST
if a invalid request was send to the server orINTERNAL_SERVER_ERROR
if an internal server error occoured.status_code
: the HTTP status code returned.-
results
: the result for each place found during the nearby search:rank
: the rank of the place according to the optimal value (were 1 is the best rank).name
: the name of the place.osm_id
: the OpenStreetMap Node ID of the place.location
: the coordinates of the places as an array of[lat, lng]
.opening_hours
: the opening hours of the place; the format specification can be found here.optimal_time
: the optimal point in time found for that place, e.g.2015-08-31T20:00
optimal_value
: the optimal value found for the place; the value considering the heat stress acording to steadman's heatindex (Steadmean, 1979) as well as the distance between the start and the place.distance
: the length of the optimal path (see Routing above) from the start to the place in meter.duration
: the time needed to walk from the start to the place (in milli seconds).path_optimal
: the geometry of the optimal path (see Routing above).distance_shortest
: the length of the shortest path between the start and the place (in meter).duration_shortest
: the time needed to walk the shortest path between the start and the place (in milli seconds).path_optimal
: the geometry of the shortest path (see Routing above).
Example¶
Sample Request:
http://localhost:8080/heatstressrouting/api/v1/optimaltime?start=49.0118083,8.4251357&time=2015-08-31T10:00:00&place_type=supermarket&max_distance=1000&max_results=5&time_buffer=15&earliest_time=2015-08-31T09:00:00&latest_time=2015-08-31T20:00:00
Sample Response:
{ "status": "OK", "status_code": 200, "results": [ { "rank": 1, "name": "Rewe City", "osm_id": 897615202, "location": [ 49.0096613, 8.4237272 ], "opening_hours": "Mo-Sa 07:00-22:00; Su,PH off", "optimal_time": "2015-08-31T20:00", "optimal_value": 12515.36230258099, "distance": 539.1839746027457, "duration": 388207, "path_optimal": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.011967867880344, 8.425196821060705 ], // points omitted ... [ 49.00954480942009, 8.423681942364334 ] ], "distance_shortest": 468.99728441805115, "duration_shortest": 337669, "path_shortest": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.011967867880344, 8.425196821060705 ], // points omitted ... [ 49.00954480942009, 8.423681942364334 ] ] }, { "rank": 2, "name": "Oststadt Super-Bio-Markt", "osm_id": 931682116, "location": [ 49.009433, 8.4234214 ], "opening_hours": "Mo-Fr 09:00-13:00,14:00-18:30; Sa 09:00-13:00", "optimal_time": "2015-08-31T18:09:19.199", "optimal_value": 14318.962937267655, "distance": 473.346750294328, "duration": 340801, "path_optimal": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.011967867880344, 8.425196821060705 ], // points omitted ... [ 49.00944708743373, 8.4235711322383 ] ], "distance_shortest": 473.346750294328, "duration_shortest": 340801, "path_shortest": [ [ 49.01190564077309, 8.4250437301107 ], [ 49.011967867880344, 8.425196821060705 ], // points omitted ... [ 49.00944708743373, 8.4235711322383 ] ] } ] }
Error messages¶
If an error occurs, e.g. because a bade request were send to the server or an internal server errors occurs, the server is sending a JSON response with the following content:
status
: the status of the request;OK
if everthing is okay,NO_REULTS
if not results were found,BAD_REQUEST
if a invalid request was send to the server orINTERNAL_SERVER_ERROR
if an internal server error occoured.status_code
: the HTTP status code returned.messages
: an array of human readable error messages.
Example¶
Example Request:
http://localhost:8080/heatstressrouting/api/v1/optimaltime?start=Schloss,%20Karlsruhe&time=2015-08-31T10:00:00&place_type=supermarket
Example Response:
{ "status": "BAD_REQUEST", "status_code": 400, "messages": [ "start (Schloss, Karlsruhe) could not be parsed: failed to parse coordinate; 'start' must be a pair of latitude and longitude seperated by a comma (','), e.g. '49.0118083,8.4251357')" ] }
-
Rußig, J. and J. Bruns (2017). Reducing individual heat stress through path planning. GI_Forum 1, 327–340. ↩↩
-
Steadman, R. G. The Assessment of Sultriness. Part I: A Temperature-Humidity Index Based on Human Physiology and Clothing. Science Journal of Applied Meteorology, 1979, 18, 861-873, DOI: 10.1175/1520-0450(1979)018<0861:TAOSPI>2.0.CO;2 ↩