-
Notifications
You must be signed in to change notification settings - Fork 25
Mobility Data Manipulation
jojenki edited this page Apr 10, 2012
·
46 revisions
Allows users to upload mobility data to the system. Mobility data is not attached to a campaign or a class.
mobility/upload
Any authenticated ohmage user may upload mobility data.
- (r) user = A valid username.
- (r) password = The hashed password for the above user.
- (r) client = A short description of the software client performing the upload.
- (r) data = A JSON Array of mobility data points.
Mobility data points come in two flavors: mode_only and sensor_data. The former contains only a mobility mode while the latter contains the mobility mode and the sensor data belonging to that mode.
| JSON Key | Usage/Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| time | The integer milliseconds since the UNIX epoch representing the time when this data point was created. | ||||||||||||
| timezone | The timezone ID for the timezone on the device when this data point was created. | ||||||||||||
| location_status | A string describing location status. Must be one of: unavailable, valid, inaccurate, stale. If the status is unavailable, it is an error to send a location object. | ||||||||||||
| location | A JSON object for housing location data.
|
||||||||||||
| subtype | Must be mode_only. | ||||||||||||
| mode | A string defining a mobility mode. Must be one of: still, walk, run, bike, drive |
"data":[
{
"time":1328659200,
"timezone":"PT",
"subtype":"mode_only",
"location_status":"accurate"
"location": {
"latitude":41.891,
"longitude":-87.628,
"accuracy":10,
"provider":"GPS",
"time":1328659369,
"timezone":"PT"
},
"mode":"still"
},
...
]
| JSON Key | Usage/Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| time | The integer milliseconds since the UNIX epoch representing the time when this data point was created. | ||||||||||||
| timezone | The timezone ID for the timezone on the device when this data point was created. | ||||||||||||
| location_status | A string describing location status. Must be one of: unavailable, valid, inaccurate, stale. If the status is unavailable, it is an error to send a location object. | ||||||||||||
| location | A JSON object for housing location data.
|
||||||||||||
| subtype | Must be sensor_data. | ||||||||||||
| mode | A string defining a mobility mode. Must be one of: still, walk, run, bike, drive. | ||||||||||||
| speed | A double representing device speed. | ||||||||||||
| accel_data | A JSON Array of JSON Objects of the form [{"x":0.0,"y":0.0,"z":0.0}, ...]. | ||||||||||||
| wifi_data | A JSON object for housing wi-fi scan data.
|
"data":[
{
"time":1328659200,
"timezone":"PT",
"subtype":"sensor_data",
"location_status":"accurate"
"location": {
"latitude":41.891,
"longitude":-87.628,
"accuracy":10,
"provider":"GPS",
"time":1328659369,
"timezone":"PT"
},
"mode":"still",
"speed":0.0,
"accel_data":[{"x":0.0,"y":0.0,"z":0.0},...],
"wifi_data":{
"time":1328660189,
"timezone":"PT",
"scan":[{"ssid":"ssid_name", "strength":0.0},...]
}
},
...
]
POST /app/mobility/upload HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
user=username
&password=hashed_password
&client=curl
&data=<A JSON Array of JSON Objects matching either the mode_only or sensor_data syntax.>
curl --trace-ascii ~/curltrace.txt -d @/mobility_data_and_auth_params.txt http://localhost:8080/app/mobility/upload
curl --trace-ascii ~/curltrace.txt -H "Content-Encoding: gzip" --data-binary @/mobility_data_and_auth_params.tgz http://localhost:8080/app/mobility/upload
{
"result" : "success"
}
See the error page for a description of error codes and their associated descriptions.
Allows users to read mobility data.
mobility/read
Mobility data is private to the user uploading the data. There is a configuration flag in ohmage that allows privileged class users to view other user's mobility data provided that the two users have a class in common and the requesting user is privileged in the common class (or classes).
- (r) auth_token = A valid authentication token from user/auth_token. May also be set using the Set-Cookie header.
- (r) user = A username of the user attempting to login
- (r) password = A password for the above user.
- (r) client = A short description of the software client performing the upload.
- (r) date = An ISO8601-formatted date from which to retrieve mobility data points.
- (o) username = The username of the user whose data is desired. This is only applicable if the requesting user is an admin or if the server allows it (the "mobility_enabled" flag from config/read) and the requesting user is privileged in any class to which the desired user belongs.
- (o) with_sensor_data = true/false Indicates whether or not to return the sensor data with the regular data. The default is false. Deprecated in favor of 'column_list'.
- (o) column_list = A comma-separated list of columns.
POST /app/mobility/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
user=username
&password=hashed_password
&client=curl
&date=2012-02-29
curl -v -d "client=curl&start_date=2012-03-15&auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e" https://dev.andwellness.org/app/mobility/read
The output is "minified" JSON due to the possible high frequency of mobility data collection. The typical number of points is 1440 per day (once per minute).
The output contains the standard result element along with a JSON Array of JSON Objects with the following schema.
| Column Name | JSON Key | Data Returned | ||||||||||||||||||||||||||||||||||||
| mobility:id | id | A string representing this point's unique identifier. | ||||||||||||||||||||||||||||||||||||
| mobility:time | t | A long representing the number of milliseconds since the Unix epoch when this point was generated. This is in UTC. | ||||||||||||||||||||||||||||||||||||
| mobility:timestamp | ts | An ISO8601-formatted string representing when this point was generated based on the time zone. This is in the given timezone, see "mobility:timezone". | ||||||||||||||||||||||||||||||||||||
| mobility:timezone | tz | The time zone of the device when this point was generated. | ||||||||||||||||||||||||||||||||||||
| location | l | A JSON object representing the location information.
|
||||||||||||||||||||||||||||||||||||
| mobility:mode | m | The mode of this point as generated by the user's device. | ||||||||||||||||||||||||||||||||||||
| mobility:subtype | st | The sub-type of this Mobility point. One of "mode_only" or "sensor_data". | ||||||||||||||||||||||||||||||||||||
| mobility:sensor_data | data | The sensor data representing this point if this point's sub-type is "sensor_data". If not, this will be omitted from the JSON.
|
||||||||||||||||||||||||||||||||||||
| classifier_data | cd | The classifier data generated for this point by the server if this point's sub-type is "sensor_data" and its more is not "error". If this mode is not a "sensor_data" sub-type or its mode is "error", it will be omitted from the JSON.
|
- If any column header is given, for example "sensor:accel_data", and any of its sub-columns are given, for example "accel:x", the result will be the greater of the columns. In this example, all accelerometer data columns would be returned because "sensor:accel_data" exists, and "accel:x" would be effectively ignored.
- The mode may be "ERROR" meaning that any of the data in the sensor data fields may not be available and that the classification information will definitely be missing. Whenever any data is missing, its corresponding key will be omitted.
The following is an example output where the following keys were given, "mobility:id, mobility:mode, mobility:timestamp, mobility:time, mobility:timezone, location, mobility:sub_type, sensor_data, sensor_data:speed, classification:mode". Note that "sensor_data:speed" is overridden by "sensor_data".
{
"result" : "success"
"data" : [
{
"id":"81DB3AE9-16CB-4B63-B2F6-9E30404B7C65",
"m":"still",
"ts":"2012-02-07 18:07:44",
"t":1328666862,
"tz":"PT",
"ls":"valid",
"l":{
"la":41.891,
"lo":-87.628,
"pr":"GPS",
"t":1328666862,
"tz":"PT"
"ac":30
},
"st":"sensor_data",
"data":{
"sp":83.4389,
"wd":{
"t":1328666321,
"tz":"America/Los_Angeles",
"sc":[
{
"ss":"72:3b:39:11:8a",
"st":-3.389289
},
...
]
},
"ad":[
{
"x":3982.3902,
"y":89.8928094,
"z":39.93092899
},
...
],
},
"cd":{
"m":"walking"
}
},
...
]
}
See the error page for a description of error codes and their associated descriptions.
Allows users to read a "chunked" version of mobility data over a date range. Mobility data is aggregated into ten-point chunks where the count of the mobility modes is returned in each chunk.
mobility/read/chunked
See access rules for mobility/read above.
- (r) auth_token = A valid authentication token from user/auth_token. May also be set using the Set-Cookie header.
- (r) user = A username of the user attempting to login
- (r) password = A password for the above user.
- (r) client = A short description of the software client performing the upload.
- (r) start_date = An ISO8601-formatted date indicating the start of a date range.
- (r) end_date = An ISO8601-formatted date indicating the end of a date range.
- (o) chunk_mins = The number of minutes per chunk. The default is 10.
POST /app/mobility/read/chunked HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
user=username
&password=hashed_password
&client=curl
&start_date=2012-02-29
&end_date=2012-03-15
curl -v -d "start_date=2012-03-15&end_date=2012-03-16&auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e&client=curl" https://dev.andwellness.org/app/mobility/read/chunked
The output is "minified" JSON due to the possible high frequency of mobility data collection.
The output contains the standard result element along with a JSON Array of JSON Objects with the following schema.
| JSON Key | Usage/Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| mc | A JSON Object defining mobility modes and their counts in the format {"still:1,"walk":2,"run":7} TODO - need to verify the modes allowed in the object -- we used to have an INVALID mode indicating that for some portion of the chunk there was no data. | ||||||||||||
| d | An integer representing the chunk duration in milliseconds. | ||||||||||||
| tz | A string timezone ID for the timezone on the device when this data point was created. | ||||||||||||
| ts | An ISO8601-formatted date-time string representing the time at which the earliest point in this chunk was generated. | ||||||||||||
| ls | A string describing location status of the first point in the chunk. Must be one of: unavailable, valid, inaccurate, stale. If the status is unavailable, the location object below will not be present. | ||||||||||||
| l | A JSON object for housing location data for the first point in the chunk. If the location status is "unavailable", this will not exist.
|
{
"result" : "success"
"data" : [
{
"mc":{"still:1,"walk":2,"run":7},
"d":600000,
"ts":"2012-02-07 18:07:44",
"tz":"PT",
"ls":"valid",
"l":{
"la":41.891,
"lo":-87.628,
"pr":"GPS",
"t":1328666862,
"tz":"PT",
"ac":30
},
},..
]
}
See the error page for a description of error codes and their associated descriptions.
Allows users to read the dates on which they uploaded Mobility data.
mobility/dates/read
A user may read information about another user if the requesting user is an admin or if the server is configured to allow privileged users in a class to read other users' Mobility information (this flag can be obtained from config/read) and the requesting user is an admin in at least one class to which the user whose information is desired belongs.
- (r) auth_token = A valid authentication token from user/auth_token. May also be set using the Set-Cookie header.
- (r) user = A username of the user attempting to login
- (r) password = A password for the above user.
- (r) client = A short description of the software client performing the upload.
- (o) start_date = An ISO8601-formatted date which limits the results to only those dates on or after this one.
- (o) end_date = An ISO8601-formatted date which limits the results to only those dates on or before this one.
- (o) username = The username of the user whose data is desired. This is only applicable if the requesting user is an admin or if the server allows it and the requesting user is privileged in any class to which the desired user belongs.
POST /app/mobility/dates/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
Set-Cookie: abcfcd36-ab25-4494-8434-7798cb1d718e
user=username
&client=curl
&start_date=2012-02-29
curl -v -d "client=curl&start_date=2012-03-15&auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e" https://dev.andwellness.org/app/mobility/dates/read
The output is a JSON object with two keys. One will always be "result", and its value will always be one of "success" or "failure". For success, the second key will be "data", and its value will be a JSON array of ISO8601-formatted dates.
{
"result" : "success"
"data" : [
"2012-02-29",
"2012-03-03",
...
]
}
See the error page for a description of error codes and their associated descriptions.