Sign inSign up

smartroadsense/srs-data-api

By smartroadsense

•Updated over 6 years ago

Image
0

375

smartroadsense/srs-data-api repository overview

Logo of the project

⁠SmartRoadSense Data API

Setup and usage

A simple JSON-based RESTful API to access SRS raw and aggregated data.

⁠Setup

The containerized version of the API service can be launched by executing the following command

docker run --rm -it --env-file api.env -p 5555:5555 smartroadsense/srs-data-api

The service will be available on port 5555 of the host machine.

The api.env file should have the following structure:

# Fill in required values
APIKEY=
PGHOST=
PGUSER=
PGPASS=
PGPORT=
SRS_EXPORTER_RAW_DB=
SRS_EXPORTER_AGG_DB=

# Debug enabled by default
SRS_API_DEBUG=True
FLASK_DEBUG=0

# Do not modify unde this line
SRS_API_PORT=5555
SRS_API_HOST=0.0.0.0
SSH_USER=
SSH_PASS=

⁠API Documentation

The SRS Data API is organized around REST. Our API has predictable resource-oriented URLs, uses POST HTTP verb, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

⁠Authentication

The SRS Data API uses API keys to authenticate requests. You should use the API Key you received adding it to the body as a multipart/form-data ContentType as follows

k:[your api key]

⁠Data endpoint

⁠Results

The SRS Data API returns JSON-encoded responses and a standard 200 HTTP response code.

A standard response has four main fields: data_type, bbox, args, and data:

  • data_type it could be raw or agg.
  • bbox is an array of four float values, representing the bounding box coordinates (namely, minimum latitude, minimum longitude, maximum latitude, maximum longitude) received in the Request's body.
  • args is an array containing all the filters received in the Request's body.
  • count is how many points are being returned.
  • full_count is how many points there are available and could be returned without using limit and offset filters.
  • data is an array of data point (raw or aggregated). The array can be empty.
⁠Aggregated API Results

In case of an a reponse from a the aggregated API endpoint the data array will be composed of aggregated data elements in the form of:

{
    "geom": "{\"type\":\"Point\",\"coordinates\":[13.193053076527,43.34704095282]}",
    "latitude": 43.34704095282,
    "longitude": 13.193053076527,
    "highway": "secondary",
    "osm_id": 123771045,
    "ppe": 0.937945374450832,
    "updated_at": "Tue, 25 Aug 2015 18:44:53 GMT"
}

where:

  • geom is a GeoJSON string representing the data point position;
  • latitude is a float representing the latitude of the data point position;
  • longitude is a float representing the longitude of the data point position;
  • highway is the kind of road associated with the data point;
  • osm_id is the OpenStreetMap ID of the road associated with the data point;
  • ppe is the averaged estimate of the road surface quality in that zone (a circular area centered at the position with a radious of 20 meters);
  • updated_at is the last time the data has been updated.
⁠Raw API Results

In case of an a reponse from a the raw API endpoint the data array will be composed of raw data elements in the form of:

{
    "geom": "{\"type\":\"Point\",\"coordinates\":[12.70958,42.94598]}",
    "latitude": 42.94598,
    "longitude": 12.70958,
    "ppe": 0.058
}

where:

  • geom is a GeoJSON string representing the data point position;
  • latitude is a float representing the latitude of the data point position;
  • longitude is a float representing the longitude of the data point position;
  • ppe is the single estimate of the road surface quality in that point.
⁠Errors

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with SRS's servers (these are rare, but in the unfortunate case of an error in the 500 range you should take notice of the request's parameters and drop a line to [email protected]⁠).

4xx and 5xx errors come with a msg with a brief description of the cause in order to help in avoiding repeated service call misbehaviours.

⁠URL

The service base URI is the following

https://smartroadsense.it/data/v1/

The URL of a valid API call to query raw or aggregated includes the geographical bounding-box for the data. A valid URL will have the following structure:

POST https://smartroadsense.it/data/v1/<dataype>/<bb_long_min>/<bb_lat_min>/<bb_long_max>/<bb_lat_max>

Where parameters have the following meaning and format:

  • <datatype> identify which kind of data you are looking for. It can either be agg for aggregated data or raw for raw data collected in the last 7 days.
  • <bb_lat_min> is a float number representing the minimum latitude value of the bounding-box.
  • <bb_long_min> is a float number representing the minimum longitude value of the bounding-box.
  • <bb_lat_max> is a float number representing the maximum latitude value of the bounding-box.
  • <bb_long_max> is a float number representing the maximum longitude value of the bounding-box.

Bounding-box coordinated uses the EPSG 4326 projection (WGS 84)⁠.

⁠Example

A valid SRS Data API call querying for raw data collected within the Belfast city center should be something like:

POST https://smartroadsense.it/data/v1/raw/-5.948649/54.593696/-5.914145/54.608313

or using cURL:

$ curl -X POST --form "k=my_api_key" https://smartroadsense.it/data/v1/raw/-5.948649/54.593696/-5.914145/54.608313

⁠Quering AGGREGATED data

Data samples taken by means of the SRS mobile application are collected by the SRS cloud server. Collected data is periodically aggregated across time and space in order to obtain aggregated values roughly representing the average of each sample collected by different users (driving possibly different vehicles) in particular section of a road.

Aggregated data can be queried through an aggregated API call of the form

POST https://smartroadsense.it/data/v1/agg/<bb_long_min>/<bb_lat_min>/<bb_long_max>/<bb_lat_max>

cURL: $ curl -X POST --form "k=my_api_key" https://smartroadsense.it/data/v1/agg/<bb_long_min>/<bb_lat_min>/<bb_long_max>/<bb_lat_max>

⁠Filters

In addition of the mandatory bounding-box, the API for aggregated data exposes a number of options for data filtering tasks. Each filter has to be specified adding it to the request body as a multipart/form-data data (just like the API Key).

  • min_ppe (float) allows to filter out all the data points with a PPE1⁠ value lower than the specified parameter.
  • max_ppe (float) allows to filter out all the data points with a PPE1⁠ value greater than the specified parameter.
  • min_quality (float) allows to filter out all the aggregated data points with a QUALITY2⁠ value lower than the specified parameter.
  • max_quality (float) allows to filter out all the aggregated data points with a QUALITY2⁠ value greater than the specified parameter.
  • min_samples (int) allows to filter out all the aggregated data points calculates from a number of indivual samples lower than the specified parameter.
  • max_samples (int) allows to filter out all the aggregated data points calculates from a number of indivual samples greater than the specified parameter.
  • min_date (date in DD-MM-YYYY format) allows to filter out all the data points collected before a certain time and date.
  • max_date (date in DD-MM-YYYY format) allows to filter out all the data points collected after a certain time and date.
  • osm_id (int) allows to restrict the query to those data points associated with a particular road. The parameter represents the OpenStreetMap ID of the road.
  • limit (int) allows to restrict the query to the first n data points returned.
  • offset (int) allows to skip the first n data points returned.

All filters are optional.

1⁠: PPE is a sytentic index used to estimate the quality if the road surface. It can vary between 0 and infinite.

2⁠: The quality value represents the overall quality of the raw data set associated to the averaged PPE value of this particular aggregated value.

⁠Example

A cURL request of the aggreagted data API featuring all the optional filters could be like this:

curl -X POST \
  https://smartroadsense.it/data/v1/agg/42.62/11.66/44.0/14.1 \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Cache-Control: no-cache' \
  -H 'content-type: multipart/form-data' \
  -F min_ppe=0.9 \
  -F max_ppe=1.0 \
  -F min_quality=0.2 \
  -F max_quality=2.0 \
  -F min_date=02-12-2019 \
  -F max_date=06-12-2019 \
  -F min_samples=3 \
  -F max_samples=10 \
  -F osm_id=123771045 \
  -F 'k=[my_api_key]'
⁠Quering RAW data

Data points collected by each mobile client are stored individually in cloud. Each record can be queried through the raw API call.

A simple call to the raw API endpoint (about raw data points collected in Belfast city center) whould be like:

POST https://smartroadsense.it/data/v1/raw/<bb_long_min>/<bb_lat_min>/<bb_long_max>/<bb_lat_max>

cURL: $ curl -X POST --form "k=my_api_key" https://smartroadsense.it/data/v1/raw/<bb_long_min>/<bb_lat_min>/<bb_long_max>/<bb_lat_max>

⁠Filters
  • min_ppe (float) allows to filter out all the data points with a PPE value lower than the specified parameter1⁠.
  • max_ppe (float) allows to filter out all the data points with a PPE value greater than the specified parameter1⁠.
  • min_date (date in DD-MM-YYYY format) allows to filter out all the data points collected before a certain time and date.
  • max_date (date in DD-MM-YYYY format) allows to filter out all the data points collected after a certain time and date.
  • mark (string) allows to restrict the query to those data points marked with a particular mark by the mobile app.
  • osm_id (int) allows to restrict the query to those data points associated with a particular road. The parameter represents the OpenStreetMap ID of the road.
  • limit (int) allows to restrict the query to the first n data points returned.
  • offset (int) allows to skip the first n data points returned.

All filters are optional.

⁠Example

A cURL request of the raw data API featuring all the optional filters could be like this:

curl -X POST \
  https://smartroadsense.it/data/v1/raw/42.62/11.66/44.0/14.1 \
 -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Cache-Control: no-cache' \
  -H 'content-type: multipart/form-data' \
  -F min_ppe=0.9 \
  -F max_ppe=1.0 \
  -F min_date=02-12-2019 \
  -F max_date=06-12-2019 \
  -F mark=Mantova-1 \
  -F osm_id=123771045 \
  -F 'k=[my_api_key]'

⁠Last Update endpoint

This endpoint returns the last time and date where a raw data is uploaded or an agg data is calculated. Filters and Url parameters are just like the ones for Data endpoints.

⁠Results

Results are just like the data endpoint but instead of data, count, full_count there is a last_update entry:

A standard response has four main fields: data_type, bbox, args, and data:

  • data_type it could be raw or agg.
  • bbox is an array of four float values, representing the bounding box coordinates (namely, minimum latitude, minimum longitude, maximum latitude, maximum longitude) received in the Request's body.
  • args is an array containing all the filters received in the Request's body.
  • last_update last time an aggreagated data is calculated or a raw data is received.

last_update has three subfields:

  • string the datetime value represented in textual form.
  • date the date value represented using the pattern YYYYMMDD (e.g., 1st November 1987 would be 19871101).
  • time the time value represented using the pattern HHMMSS (e.g., six thirty-five pm and 27 seconds would be 183527).
⁠URL

The URL of a valid API call to query raw or aggregated includes the geographical bounding-box for the data. A valid URL will have the following structure:

POST https://smartroadsense.it/data/v1/<dataype>/<bb_long_min>/<bb_lat_min>/<bb_long_max>/<bb_lat_max>/last_update

Just like the data endpoint plus a /last_update suffix.

Url parameters follows the same rules of data endpoint.

⁠Example

A valid SRS Last Update API call querying for raw data collected within the Belfast city center should be something like:

POST https://smartroadsense.it/data/v1/raw/-5.948649/54.593696/-5.914145/54.608313/last_update

or using cURL:

$ curl -X POST --form "k=my_api_key" https://smartroadsense.it/data/v1/raw/-5.948649/54.593696/-5.914145/54.608313/last_update

⁠Licensing

The code in this project is licensed under MIT license.

Tag summary

Content type

Image

Digest

Size

362.2 MB

Last updated

over 6 years ago

docker pull smartroadsense/srs-data-api