Skip to content

Mobility Data Manipulation

Jump to bottom
joshuaselsky edited this page Mar 20, 2012 · 46 revisions

Mobility Upload

What does it do?

Allows users to upload mobility data to the system. Mobility data is not attached to a campaign.

URI

mobility/upload

Access Rules

Any authenticated ohmage user may upload mobility data.

Input Parameters

  • (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.

Data Point JSON Syntax

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.

mode_only subtype

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.
latitude A double representing latitude.
longitude A double representing longitude.
provider A non-empty string representing the location provider. (e.g., GPS or network).
accuracy A float representing accuracy in meters from actual location.
time A long value representing the milliseconds since the UNIX epoch at which time this location value was collected.
timezone The timezone ID for the timezone of the device when this location value was collected.
subtype Must be mode_only.
mode A string defining a mobility mode. Must be one of: still, walk, run, bike, drive

JSON Example

"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"
    },
    ...
]

sensor_data subtype

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.
latitude A double representing latitude.
longitude A double representing longitude.
provider A non-empty string representing the location provider. (e.g., GPS or network).
accuracy A float representing accuracy in meters from actual location.
time An integer value representing the milliseconds since the UNIX epoch at which time this location value was collected.
timezone The timezone ID for the timezone of the device when this location value was collected.
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.
time An integer value representing the milliseconds since the UNIX epoch at which time this wifi data value collected.
timezone A string value defining the timezone in which the scan took place.
scan A JSON Array of JSON Objects of the form [{"ssid":"ssid_name", "strength":0.0},...]

JSON Example

"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},...]
        }
    },
    ...
]

Example POST

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.>

Output Format

Success

{
   "result" : "success"
}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Mobility Read

What does it do?

Allows users to read mobility data.

URI

mobility/read

Access Rules

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).

Input Parameters

Supports Token-Based Authentication ...

  • (r) auth_token = A valid authentication token from user/auth_token

... or User-Password Authentication

  • (r) user = A username of the user attempting to login
  • (r) password = A password for the above user.

Additional Parameters

  • (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.

Example POST

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

Output Format

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.

Note: The mode may be "ERROR" meaning that any of the data in the sensor data fields may not be available. This is signified by having the key be missing from the JSON.

JSON Key Usage/Description
id The unique identifier for this mobility point.
m A string defining the mobility mode for this point. Not present if the data point represents a point with sensor data.
t An integer representing the milliseconds since the UNIX epoch when this data point was created.
tz A string timezone ID for the timezone on the device when this data point was created.
ts An ISO8601-formatted date-time string above the above time and timezone.
ls A string describing location status. 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.
la A double representing latitude.
lo A double representing longitude.
pr A non-empty string representing the location provider. (e.g., GPS or network).
ac A float representing accuracy in meters from actual location.
t An integer value representing the milliseconds since the UNIX epoch at which time this location value was collected.
tz The timezone ID for the timezone of the device when this location value was collected.
st The subtype which must be one of "mode_only" or "sensor_data". This will only appear if "with_sensor_data" is true.
data This will only appear if "with_sensor_data" is true as a JSONObject with the following key-value pairs.
sp The speed of the device when the recording was made as a double.
wd The WiFi data collected when the recording was made as a JSONObject.
t The time of this reading as a long value representing the milliseconds since the epoch.
tz The timezone of the device at the time of this reading as a string.
sc A JSONArray of JSONObjects where each JSONObject has the following format:
ss The SSID of the wireless access point as a string.
st The strength of the signal from the wireless access point as a double.
ad A JSONArray of JSONObjects representing the accelerometer data where each JSONObject has the following format:
x The "x" component of the accelerometer data as a double.
y The "y" component of the accelerometer data as a double.
z The "z" component of the accelerometer data as a double.

Success

{
   "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
                   },
                   ...
               ],
           }
       },
       ...
   ]

}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Mobility Read Chunked

What does it do?

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.

URI

mobility/read/chunked

Access Rules

See access rules for mobility/read above.

Input Parameters

Supports Token-Based Authentication ...

  • (r) auth_token = A valid authentication token from user/auth_token

... or User-Password Authentication

  • (r) user = A username of the user attempting to login
  • (r) password = A password for the above user.

Additional Parameters

  • (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.

Example POST

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

Output Format

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.
la A double representing latitude.
lo A double representing longitude.
pr A non-empty string representing the location provider. (e.g., GPS or network).
ac A float representing accuracy in meters from actual location.
t An integer value representing the milliseconds since the UNIX epoch at which time this location value was collected.
tz The timezone ID for the timezone of the device when this location value was collected.

Success

{
   "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
           },
       },..
   ]

}

Failure

See the error page for a description of error codes and their associated descriptions.

Back to Top

Clone this wiki locally