Skip to content

Instantly share code, notes, and snippets.

@hannesjung

hannesjung/pumatrac-api.md Secret

Last active October 20, 2016 21:54
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save hannesjung/5c8cc24ebaf0d13d0196 to your computer and use it in GitHub Desktop.
Save hannesjung/5c8cc24ebaf0d13d0196 to your computer and use it in GitHub Desktop.
Download ZIP
API description for the MIT hackathon on January 30th/31st
Raw
pumatrac-api.md

PUMATRAC API for MIT

API

The API is available at https://pumatrac-geo-api.herokuapp.com.

Authentication

You will have to provide an API key as Authorization header for every request.

Authorization: Bearer 1cfb51cd69904221818dafc4069f9d61

User Management

You have to create an account with the PUMATRAC app (via e-mail registration). Afterwards you can get your own user_id with the following request.

POST /user_id

Request Parameters:

  • email is required
  • password is required - base64 encoded string

Response:

  • 200 OK
  • 400 Bad Request
  • 404 Not Found

Example: curl -H "Authorization: Bearer 1cfb51cd69904221818dafc4069f9d61" -X POST --data "email=demo@puma.com&password=ZGVtbzEyMw==" https://pumatrac-geo-api.herokuapp.com/user_id

Response JSON example:

{
    "user_id": "2143d242-afff-42eb-9f6d-7981b8ea170c"
}

Activities

Activities represent the main entity of the PUMATRAC data. It provides a variety of useful information like GPS data, weather info, …

Mode

Each activity has a mode, which specifies the sport the activity is about. Known modes are: outdoor, treadmill, cycling_outdoor, cycling_indoor, walking_outdoor, walking_indoor, yoga_bikram, yoga_hot, yoga_power, yoga_vinyasa, boxing, swimming, aerobics, pilates, barre, rowing_machine, stair_machine, weightlifting, football, american_football, hiking, mountain_biking, golf, hockey, kayak, lacrosse, rowing, tennis, basketball, baseball, softball, cricket, gymnastics, martial_arts, surfing, skiing, snowboarding, volleyball

Weather

Activities track weather conditions. Known weather types are: thunderstorm_light, thunderstorm, rain_light, rain, snow_light, snow, fog, clear, cloud_light, cloud, storm, hail_light, hail

GPS coordinates

/activities returns a list of matching activities. Use the returned IDs to fetch the extended data (incl. GPS coordinates) of each activity in a separate request to /activities/{ID}.

Pagination

Requests to /activities are returned in sets of 100 items. Pass a page parameter to get more activities. Each response contains a paging hash with prev and next values, indicating the available pages before and after the current one.

Activities by country

GET /activities

Request parameters:

  • country is required - country code (e.g. ”us”)
  • mode is optional - get all activities with a specific mode code (e.g. ”outdoor”)
  • min_distance is optional - get all activities with a minimum distance in km
  • from_timestamp is optional - get all activities after a specific UNIX timestamp, combine with to_timestamp to specify a time range
  • to_timestamp is optional - get all activities until a specific UNIX timestamp, combine with from_timestamp to specify a time range
  • page is optional - set page number, see paging in the response

Response:

  • 200 OK
  • 400 Bad Request

Example: curl -H "Authorization: Bearer 1cfb51cd69904221818dafc4069f9d61" https://pumatrac-geo-api.herokuapp.com/activities?country=us&mode=outdoor

Response JSON example:

{
    "summary" : {
        "total_count" : 32295
    },
    "paging" : {
        "prev" : null,
        "next" : 2
    },
    "activities" : [
        {
            "id" : "11869bd7-9bd3-46a1-889c-bbe60d644312",
            "mode" : "outdoor",
            "start_time" : "2556-10-05T15:27:12.000Z",
            "end_time" : "2556-10-05T15:29:22.000Z",
            "paused_seconds" : 2,
            "timezone" : null,
            "timezone_offset" : null,
            "duration" : 128,
            "distance" : 0.287593,
            "max_speed" : 16.44041,
            "mean_speed" : 8.088461,
            "min_altitude" : 188,
            "max_altitude" : 198,
            "mean_altitude" : 192.25,
            "average_time_per_km" : 445,
            "calories" : 17,
            "city" : "Southgate",
            "country" : "us",
            "weather" : "fog",
            "daylight" : true,
            "temperature" : 20.84,
            "humidity" : 99,
            "pressure" : 1013,
            "wind_speed" : 2.61,
            "start_position" : [
                42.2240994125998,
                -83.2307746634662
            ],
            "steps" : null,
            "stride_length" : null
        }
    ]
}

Activities by bounding box (coordinates)

GET /activities

This request is similar to Activities by country, but insead of the country parameter, the parameter bounds is required.

Request parameters:

  • bounds is required - format: box:lat1,lng1:lat2,lng2
  • mode is optional
  • min_distance is optional
  • from_timestamp is optional
  • to_timestamp is optional
  • page is optional

Response:

  • 200 OK
  • 400 Bad Request

Example: curl -H "Authorization: Bearer 1cfb51cd69904221818dafc4069f9d61" https://pumatrac-geo-api.herokuapp.com/activities?bounds=box:50.3,13.1:52.2,15.7&mode=outdoor

Response JSON example:

{
    "summary" : {
        "total_count" : 89
    },
    "paging" : {
        "prev" : null,
        "next" : null
    },
    "activities" : [
        {
            "id" : "11869bd7-9bd3-46a1-889c-bbe60d644312",
            "mode" : "outdoor",
            "start_time" : "2556-10-05T15:27:12.000Z",
            "end_time" : "2556-10-05T15:29:22.000Z",
            "paused_seconds" : 2,
            "timezone" : null,
            "timezone_offset" : null,
            "duration" : 128,
            "distance" : 0.287593,
            "max_speed" : 16.44041,
            "mean_speed" : 8.088461,
            "min_altitude" : 188,
            "max_altitude" : 198,
            "mean_altitude" : 192.25,
            "average_time_per_km" : 445,
            "calories" : 17,
            "city" : "Southgate",
            "country" : "us",
            "weather" : "fog",
            "daylight" : true,
            "temperature" : 20.84,
            "humidity" : 99,
            "pressure" : 1013,
            "wind_speed" : 2.61,
            "start_position" : [
                42.2240994125998,
                -83.2307746634662
            ],
            "steps" : null,
            "stride_length" : null
        }
    ]
}

Activities by user ID

GET /activities

This request is similar to Activities by country, but insead of the country parameter, the parameter user_id is required.

Request parameters:

  • user_id is required
  • mode is optional
  • min_distance is optional
  • from_timestamp is optional
  • to_timestamp is optional
  • page is optional

Response:

  • 200 OK
  • 400 Bad Request

Example: curl -H "Authorization: Bearer 1cfb51cd69904221818dafc4069f9d61" https://pumatrac-geo-api.herokuapp.com/activities?user_id=2143d242-afff-42eb-9f6d-7981b8ea170c&mode=outdoor

Response JSON example:

{
    "summary" : {
        "total_count" : 12
    },
    "paging" : {
        "prev" : null,
        "next" : null
    },
    "activities" : [
        {
            "id" : "11869bd7-9bd3-46a1-889c-bbe60d644312",
            "mode" : "outdoor",
            "start_time" : "2556-10-05T15:27:12.000Z",
            "end_time" : "2556-10-05T15:29:22.000Z",
            "paused_seconds" : 2,
            "timezone" : null,
            "timezone_offset" : null,
            "duration" : 128,
            "distance" : 0.287593,
            "max_speed" : 16.44041,
            "mean_speed" : 8.088461,
            "min_altitude" : 188,
            "max_altitude" : 198,
            "mean_altitude" : 192.25,
            "average_time_per_km" : 445,
            "calories" : 17,
            "city" : "Southgate",
            "country" : "us",
            "weather" : "fog",
            "daylight" : true,
            "temperature" : 20.84,
            "humidity" : 99,
            "pressure" : 1013,
            "wind_speed" : 2.61,
            "start_position" : [
                42.2240994125998,
                -83.2307746634662
            ],
            "steps" : null,
            "stride_length" : null
        }
    ]
}

Detailed activity data incl. GPS

GET /activities/:id

Returns all the data from a single activity - including all GPS coordinates as well as all weight_exercises if the mode is weightlifting.

Response:

  • 200 OK
  • 400 Bad Request

Example: curl -H "Authorization: Bearer 1cfb51cd69904221818dafc4069f9d61" https://pumatrac-geo-api.herokuapp.com/activities/7e5ebc3f-8ec1-4f30-bcf7-f75fa4c97000

Response JSON example:

{
    "activity" : {
        "id" : "7e5ebc3f-8ec1-4f30-bcf7-f75fa4c97000",
        "mode" : "outdoor",
        "start_time" : "2013-10-24T16:19:04.000Z",
        "end_time" : "2013-10-24T16:45:43.000Z",
        "paused_seconds" : 3,
        "timezone" : "Europe/Berlin",
        "timezone_offset" : 2,
        "duration" : 1596,
        "distance" : 3.6829,
        "max_speed" : 12.96,
        "mean_speed" : 8.305857,
        "min_altitude" : 169.5117,
        "max_altitude" : 204.0345,
        "mean_altitude" : 186.08,
        "average_time_per_km" : 433,
        "calories" : 287,
        "city" : "Kreisfreie Stadt Görlitz",
        "country" : "de",
        "weather" : "cloud",
        "daylight" : false,
        "temperature" : 16.13,
        "humidity" : 75,
        "pressure" : 992,
        "wind_speed" : 2.71,
        "start_position" : [
            51.1540421750873,
            14.9914692621818
        ],
        "steps" : null,
        "stride_length" : null,
        "positions" : [
            {
                "latitude" : 51.1540421750873,
                "longitude" : 14.9914692621818,
                "speed" : -1,
                "height" : 190.336669921875,
                "accuracy_x" : 30,
                "accuracy_y" : 24,
                "timestamp" : "2013-10-24T16:19:04.000Z",
                "paused" : null,
                "battery_level" : null
            },
            {
                "latitude" : 51.1543687759444,
                "longitude" : 14.992003692328,
                "speed" : 3.59999990463257,
                "height" : 193.820495605469,
                "accuracy_x" : 10,
                "accuracy_y" : 8,
                "timestamp" : "2013-10-24T16:19:24.000Z",
                "paused" : null,
                "battery_level" : null
            }
        ]
    }
}
@gregbeams
Copy link

Hi! I've picked up a thesis project at MEL in the media lab and I'm using this api to build a competition based application. This goes over how to access the event information, but not POST any new data. Could we meet, or could you point me to another person, in order to go over the api in more detail?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment