API documentation

All API access is over HTTPS. All data is sent and received as JSON.

Authentication

The REST API require user authentication to access or create data. The authentication requires OAuth 2.0 authorization code flow. More information on the OAuth specification can be found at oauth.net.

The trackthisforme APIs are free, for both developers and users: if you use a lot these APIs for create great apps, please consider become an Awesome user to support the development: it's not required, but it will be deeply appreciated.

Registration

Registration for OAuth applications is available at /api/applications/new.

Authentication Flow

This is a description of the OAuth flow from 3rd party web sites.

1. Redirect users to request Trackthisforme access
GET https://www.trackthisfor.me/oauth/authorize
Parameters
client_id
Required string - The client ID you received from Trackthisforme when you registered.
redirect_uri
Required string - URL in your app where users will be sent after authorization.
scope
Optional string - Comma separated list of scopes.
state
Optional string - An unguessable random string. It is used to protect against cross-site request forgery attacks.
2. Trackthisforme redirects back to your site

If the user accepts your request, Trackthisforme redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter.

Exchange this for an access token:

POST https://www.trackthisfor.me/oauth/token
Parameters
client_id
Required string - The client ID you received from Trackthisforme when you registered.
redirect_uri
Required string
client_secret
Required string - The client secret you received from Trackthisforme when you registered.
code
Required string - The code you received as a response to Step 1.
grant_type
Required string - Should be 'authorization_code'.

By default, the response will take the following form:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer
3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

Access tokens should never expire. An user’s access token will be invalidated if the user explicitly revokes your application’s authorization or if trackthisforme suspends your application.

GET https://api.trackthisforme.com/user?access_token=...

Scopes

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

Requested scopes will be displayed to the user on the authorize form.

Read
Public read-only access. This is the default scope if you don't specify a scope.
Write
Use this scope to create data (elements and categories), modify or destroy them.

NOTE: Your application can request the scopes in the initial redirection. You can specify multiple scopes by separating them by a space.

https://www.trackthisfor.me/oauth/authorize?client_id=...&scope=read+write

Rate Limits

The API are limited to 500 calls every 24 hours. If the user is an Awesome user, the calls are increased to 1000.

Every request you made will return 2 X-RateLimit- headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499

When you exceed the API calls limit your request is forbidden.


HTTP/1.1 403 Forbidden
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
			

Resources

Category

A category is a container for elements.

Attribute name Description
id the id of the category.
name the name of the category. The length of name must be equal or less than 20 characters and its unique between the user's categories.
symbol the symbol of the category. The length of name must be equal or less than 8 characters. Optional.
goal the current goal that the user tries to reach. It can be a numeric value or null. Optional.
goal_str a string version of the numeric goal. If you are a javascript dev, it's better if you use this.
position the position of the category in the list of categories. Not editable.
tags an array with all the tags for this category. Not editable.
color the background color of the category. The color can be: blue (#3498DB), orange (#FE7126), green (#45BBAB), purple (#9b59b6), red (#e74c3c), asphalt (#46627f). If possible, please use these specific colors to identify the category. The default color is blue. Optional

Example:

{
  "id":3531,
  "name":"Weight",
  "symbol":"kg",
  "color":"red",
  "position":3,
  "goal":32.4,
  "goal_str":"32.4",
  "tags":[
    {
      id: 1,
      name: "health"
    }
  ]
}
							

Element

This is the basic item of trackthisfor.me. It belongs to a category.

Attribute name Description
id The id of the element.
category_id The id of the category which this element belongs.
value The value of the element. It's a numeric value.
value_str The value of the element. It's a string value. If you are a javascript dev, it's better if you use this.
date The date of the element. It's in the format ISO8601, based on the time zone of the current user.
comment A comment that describes the element. The maximum length is 250 characters.

Example:

{
  "id":103531,
  "category_id":3531,
  "comment": "this is a great comment",
  "value": 13.32,
  "value_str": "13.32",
  "date":"2013-06-05T12:13:00+02:00",
}
							

User

It describes the current user.

Attribute name Description
name The first name of the user. Optional
time_zone The current time zone of the user, as a tzinfo identifier.
date_format the default format of the dates. It can be "MM/dd/yyyy" or "dd/MM/yyyy".
avatar the url of the avatar image for the user.

Example:

{
  "name":"Francesco",
  "date_format":"MM/dd/yyyy",
  "time_zone": "Europe/Berlin",
  "avatar": "https://trackthisforme....",
}
							

Tag

A tag permits to organize the categories. The tag resource cannot be modified from the APIs.

Attribute name Description
name The name of the tag
id The id of the tag.

Example:

{
  "name":"Health",
  "id":"102",
}
							

Categories Requests

GET /categories

Get an array composed of all the user's categories.

Url
/api/v1/categories.json
HTTP request method
GET
Requires scope
read
Parameters
[]

Sample request:

GET https://www.trackthisfor.me/api/v1/categories.json

JSON sample response:

{
  categories:	[
  {
    "id":3531,
    "name":"Weight",
    "symbol":"kg",
    "position":0,
    "goal":null,
    "color":"red",
    "tags":[
      {
        id: 1,
        name: "health"
      } 
    ]   
  },{
    "id":3531,
    "name":"Running",
    "symbol":"Km",
    "position":0,
    "goal":null,
    "color":"green",
    "tags":[]
  }
]}
							

POST /categories

Create a new Category. It returns the new category created.

Url
/api/v1/categories.json
HTTP request method
POST
Requires scope
write
Parameters
  • Name: the name of the category. The length of name must be equal or less than 20 characters and its unique between the user's categories.
  • Symbol: the symbol of the category. The length of name must be equal or less than 8 characters. Optional.
  • Color: the color of the category. Optional
  • Goal: the goal of the category. Optional

Sample request:

POST https://www.trackthisfor.me/api/v1/categories.json


category[name]="Weight"
category[symbol]="Kg"
								

JSON sample response:

{
  "id":3531,
  "name":"Weight",
  "symbol":"kg",
  "position":4,
  "goal":null,
  "color":"blue"
  "tags":[
    {
      id: 1,
      name: "health"
    }
  ]
}
							

GET /categories/:id

Get a single category, plus the elements from the last 7 days

Url
/api/v1/categories/:id.json
HTTP request method
GET
Requires scope
read
Parameters
[]

Sample request:

GET https://www.trackthisfor.me/api/v1/categories/310.json

JSON sample response:

{
  "id":310,
  "name":"Weight",
  "symbol":"kg",
  "position":0,
  "goal":null,
  "tags":[
    {
      id: 1,
      name: "health"
    }
  ],
	"elements":[
    {
      "id": 33243,
      "value": 100,
      "value_str": "100.0",
      "category_id": 310,
      "stars": 4,
      "date": "2013-06-04T16:13:00+02:00",
      "comment": ""
    },
    {
      "id": 33244,
      "value": 101,
      "value_str": "101.0",
      "category_id": 310,
      "stars": 4,
      "date": "2013-06-05T12:13:00+02:00",
      "comment": ""
    }
  ]
}
							

PUT /categories/:id

Update a category. Returns the updated category.

Url
/api/v1/categories/:id.json
HTTP request method
PUT
Requires scope
write
Parameters
  • name: the name of the category. The length of name must be equal or less than 20 characters and its unique between the user's categories.
  • symbol: the symbol of the category. The length of name must be equal or less than 8 characters.
  • goal: the goal of the category. It can be null or 'null' to delete the current goal.

Sample request:

PUT https://www.trackthisfor.me/api/v1/categories.json


  category[name]="Weight"
  category[symbol]="Kg"
  category[goal]=45
								

JSON sample response:

{
  "id":3531,
  "name":"Weight",
  "symbol":"kg",
  "position":4,
  "goal":null,
  "color":"blue",
  "tags":[]
},
	
							

DELETE /categories/:id

Delete a category. It returns nothing.

Url
/api/v1/categories/:id.json
HTTP request method
DELETE
Requires scope
write
Parameters
[]

Elements Requests

GET /categories/:category_id/elements

Returns an array with all the elements of the last 7 days.

Url
/api/v1/categories/:category_id/elements
HTTP request method
GET
Requires scope
read
Parameters
[]

Sample request:

GET https://www.trackthisfor.me/api/v1/categories/310/elements

JSON sample response:

{
"elements":[
  {
    "id": 33243,
    "value": 100,
    "value_str": "100.0",
    "category_id": 310,
    "stars": 4,
    "date": "2013-06-04T16:13:00+02:00",
    "comment": ""
  },
  {
    "id": 33244,
    "value": 101,
    "value_str": "101.0",
    "category_id": 310,
    "stars": 5,
    "date": "2013-06-05T12:13:00+02:00",
    "comment": ""
  }
]
}
							

GET /categories/:category_id/elements/from/:from/to/:to

Get an array of all the elements specified in the range :from and :to. The paramethers :from and :to must be composed by date with the format MM/DD/yyyy.

Url
/api/v1/categories/:category_id/elements/from/:from/to/:to
HTTP request method
GET
Requires scope
read
Parameters
[]

Sample request:

GET https://www.trackthisfor.me/api/v1/categories/310/ elements/from/10/23/2011/to/10/31/2012

JSON sample response:

{
"elements":[
  {
    "id": 33243,
    "value": 100,
    "value_str": "100.0",
    "category_id": 310,
    "stars": 3,
    "date": "2012-10-23T16:13:00+02:00",
    "comment": ""
  },
  {
    "id": 33244,
    "value": 101,
    "value_str": "101.0",
    "category_id": 310,
    "stars": 4,
    "date": "2012-10-24T12:13:00+02:00",
    "comment": ""
  }
]
}
							

POST /categories/:category_id/elements/

Create a new Category. It returns the new category created. Please read the docs about /increase and choose the right API for your app.

Url
/api/v1/categories/:category_id/elements
HTTP request method
POST
Requires scope
write
Parameters
  • value: The value of the element.
  • date: The date of the element. Must be in the format ISO8601. Default: the date and time of creation of the element. Optional.
  • stars: A value between 1 and 5. It rapresents the satisfaction of the user. Default: 3. Optional
  • comment: A description or some notes about the element. Max length: 250 characters. Optional.

Sample request:

POST https://www.trackthisfor.me/api/v1/categories/310/elements.json

 
element[value]=12
element[stars]=4
element[date]=2013-06-12T12:13:00+02:00
element[comment]="this is a comment"
								

JSON sample response:

{
  "id": 33246,
  "value": 12,
  "value_str": "12",
  "category_id": 310,
  "stars": 4,
  "date": "2013-06-12T12:13:00+02:00",
  "comment": "this is a comment"
}
	
							

POST /categories/:category_id/elements/increase

Increase the last element of the current day. If no element is found, it creates one. NOTE: If your app is a bot (it creates automatically new elements without the consent of the user for every element), please use this request instead of the /elements request. Returns the element created or modified.

Url
/api/v1/categories/:category_id/elements/increase
HTTP request method
POST
Requires scope
write
Parameters
  • value: the numeric value to add to the existing element or which create a new element. Default: 1. Optional.

Sample request:

POST https://www.trackthisfor.me/api/v1/categories/310/elements/increase.json


element["value"]=12
								

JSON sample response:

{
  "id": 33246,
  "value": 24,
  "value_str": "24",
  "category_id": 310,
  "stars": 4,
  "date": "2013-06-12T12:13:00+02:00",
  "comment": ""
}
							

PUT /categories/:category_id/elements/:id

Update an element. Returns the update element.

Url
/api/v1/categories/:category_id/elements/:id
HTTP request method
PUT
Requires scope
write
Parameters
  • value: the name of the category. The length of name must be equal or less than 20 characters and its unique between the user's categories.
  • date: The date of the element. Must be in the format YYYY-MM-dd (example: 2013-03-10). Default: the date of the current day.
  • stars: A value between 1 and 5. It rapresents the satisfaction of the user. Default: 3
  • comment: A description or some notes about the element. Max length: 250 characters. Optional.

Sample request:

PUT https://www.trackthisfor.me/api/v1/categories/310/elements.json


element[stars]=5
element[comment]="this is a new comment"
								

JSON sample response:

{
  "id": 33246,
  "value": 12,
  "value_str": "12",
  "category_id": 310,
  "stars":5,
  "date": "2013-06-12T12:13:00+02:00",
  "comment": "this is a new comment"
}
							

DELETE /categories/:category_id/elements/:id

Delete an element. It returns nothing.

Url
/api/v1/categories/:category_id/elements/:id
HTTP request method
DELETE
Requires scope
write
Parameters
[]

User Requests

GET /users/me

Get informations and preferences about the current user.

Url
/api/v1/users/me
HTTP request method
GET
Requires scope
read
Parameters
[]

Sample request:

GET https://www.trackthisfor.me/api/v1/users/me

JSON sample response:

{
  "name":"Francesco",
  "date_format":"MM/dd/yyyy",
  "time_zone": "Europe/Berlin",
  "avatar": "https://trackthisforme....",
}