# 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

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 form 2014-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 form YYYY-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 and temperature), e.g. weighting=shortest,heatindex,temperature; the default is weighting=shortest,heatindex; the results for the shortest 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 or INTERNAL_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 parameter weighting 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 form YYYY-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 the info 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 corresponding shop respectively amenity 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 least time_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 string null (case is ignored); the default value is null. If both earliest_time and latest_time are specified, earliest_time must be before latest_time.
• latest_time (optional): the latest desired time, either a time stamp, e.g. latest_time=2015-08-31T17:00 or the string null (case is ignored); the default value is null. If both earliest_time and latest_time are specified, earliest_time must be before latest_time; latest_time must be after time.

### 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 or INTERNAL_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,
"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 or INTERNAL_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:

{
`