Trackingo API

Trackingo API key

You must register first at Trackingo to get your API Key

Overview

Trackingo API is a XML-RPC implementation to interact with the Trackingo system.

Current version

Note that Trackingo is Beta. Both the API and the system behavior may change unexpectedly and your application can stop working any time.

The current API version is 0.1 (June 19, 2010).

Main index

How to connect with this API?
List of available methods
- Overview table
- Documentation about the methods
API's limitations
Contact with the author

How to connect with this API?

The URL where you must connect to is: trackingo.com/xmlrpc. The port you use is not important for the connection.

List of available methods

Overview table:

Method name	Params	Response
`list.getTracks`	`[string]` API_KEY, `[string]` SESSION_TOKEN, `[int]` LIST_ID	`[Array]` Array of structs with all the information
`list.getList`	`[string]` API_KEY, `[string]` SESSION_TOKEN, `[int]` LIST_ID	`[struct]` Struct with information about the tracking list
`list.create`	`[string]` API_KEY, `[string]` SESSION_TOKEN, `[struct]` INSERTION_DATA	`[struct]` Struct with an info message and the `LIST_ID`
`list.dateCalendar`	`[string]` API_KEY, `[string]` SESSION_TOKEN, `[struct]` CALENDAR_PARAMS	`[string]` The calendar in the date selected.
`user.getLists`	`[string]` API_KEY, `[string]` SESSION_TOKEN, `[string]` USER_NAME (can be empty)	`[Array]` Array with structs about each tracking list that user have.
`user.login`	`[string]` API_KEY, `[struct]` LOGIN_PARAMS	`[string]` A `SESSION_TOKEN` to identify that user for later requests.
`user.valid`	`[string]` API_KEY, `[string]` SESSION_TOKEN	`[bool]` True or false depending if the session is valid or not.
`track.insert`	`[string]` API_KEY, `[string]` SESSION_TOKEN, `[struct]` INSERTION_PARAMS	`[string]` An info message about the operation.
`category.properties`	`[string]` API_KEY, `[int]` CATEGORY_ID	`[struct]` The struct with all the category's properties.
`category.list`	`[string]` API_KEY	`[Array]` An array of structs with information about each category.

Documentation about the methods

list.getTracks

It retrieves all data in a tracking list in a struct with the computable data, the displayable data and his date.

list.getList

It retrieves the main information about the tracking list: owner's username, most recent data, tracking list's category, permanent link and the graph or the calendar.

list.create

Create a new tracking list. The struct of the INSERTION_DATA must have:

cat => [INT] CATEGORY_ID
description => [STRING] A description about the tracking list (more than 10 characters)
tags => [STRING] A comma separated values with tags for the tracking list. Almost one

Also, the tracking list can have:

measure => [STRING] A measurement unit for the data
name => [STRING] If the category needs to have a name cause it can have more than one tracking list with the same category, you could set up a name (more than 10 characters if needed)
private => [BOOL] If you want that only the owner can view the tracking list, set up "private" to 1.

It returns the LIST_ID of the new tracking list and an info message.

It's important that the tracking list will be useless until no data is inserted into.

list.dateCalendar

Calendar params are:

year => [INT] Year of the calendar
month => [INT] Month of the calendar
list => [INT] The tracking list you need to explore between months

That method is useful if you want to show a tracking list with calendars and you need to be able to explore it between months. The functions who retrieves the calendar, sets his navigation links in a Javascript function called change_month(year,month).

user.getLists

If you don't specify the USER_NAME (setting it with empty string (""), zero or any empty value) the system assumes that it will retrieve the tracking lists of the SESSION_TOKEN user.

The structs it retrieves have that pattern:

id => [INT] The LIST_ID of the tracking list
name => [STRING] The full name of the tracking list. Including the category name and the list name (if is seted)
permalink => [STRING] The permalink to go directly to the tracking list at Trackingo.com. You need later to combine it, for example, with that data you get "alex-tracking-weight" and you need to prepend something like "http://www.trackingo.com/tracking/" to build the link.

user.login

The method to log in a user is (at the moment) only with Facebook. Probably this limitation will be resolved in the future.

The struct with the LOGIN_PARAMS must math this pattern:

fb_userid => [STRING] The number of the Facebook User Id. Like the number is so so long, it must be sent in a string. Otherwise will be probably truncated.
fb_first_name => [STRING] The name of the Facebook User.
fb_last_name => [STRING] The last name of the Facebook User.

All the required information can be obtained with the Facebook Open Graph API

Important: if the user doesn't exists, the system will create it.

user.valid

That method is needed to check if a TOKEN_SESSION is valid or not.

Keep in mind that if you pass an invalid TOKEN_SESSION to another method you will receive an error.

track.insert

The INSERTION_PARAMS struct must have that parameters:

data => [SCALAR] The data you want to insert. Can have any scalar value.
date => [dateTime.iso8601] A date with the format iso8061 for the introduced data.
cat => [INT] the id of the category where you will place your data

Also, you might need to specify the LIST_ID where place the data, and that will be named "list" ([INT]).

The owner of the entered data will be the owner of the TOKEN_SESSION.

An important thing to keep in mind is that an common error is the one with the code 513 which means that you are trying to insert a data without any list of this category. You'll need before to create a list with the method list.create and after, store the data.

category.properties

This method is useful to prepare the environment for the enter data form. You'll get information like this:

"name": Likely redundant but can be useful if you only have access via CATEGORY_ID and you could need also the name.
"type": The data type required for the category. Can be (boolean, float, int and string)
"date": It specifies the date needed. Can be ("0000-00-00" which means that the hour/minute/second are useless or "0000-00-00 00:00:00" which means that, in this case, the hour and the minutes are needed (the seconds will be ignored anyway).
"multiple": It specifies if the category can have more than one tracking list with the same category. Note that then you will need to ask the user the name of the tracking list if you need to use the list.create method.
"possibles" (optional): A comma-separated-values string with each value accepted by the category. Any other value will be an error in the insertion of data.
"minimum" and "maximum" (both are optional): The minimum and the maximum values accepted by the category.

category.list

This method retrieves all the categories available at Trackingo.com. This is useful to generate a menu where the user will be able to select which category needs to enter data.

The struct of each category match this pattern:

id => [INT] The CATEGORY_ID for this category.
name => [STRING] The name of the category (in English)
permalink => [STRING] A permanent link to the category. Can be created to make a link to something like "http://www.trackingo.com/input/medicines".
canInsert => [BOOL] True or false depending if you can insert data in that category or not. For example, a parent category like "Health" can't store data in it.
privateByDefault => [BOOL] True or false depending if the category, by default, could be private. Is only useful for the create list form, to set "checked" a checkbox asking if set private the list.
isFather => [INT] 2, 1 or 0 depending if the category is top parent, medium parent or a final child. For example, "Health" is the parent of the medium parent "Disease" and "Migraine" is a disease's child.

API's limitations

As you see, the API is very basic: you only can retrieve and insert information. Nothing about edit or delete. In future versions of this API probably the number of methods will increase significantly.

The number of requests you can make is a private data, but I can say that is something about one request per second (this is an average). If you think that you need more requests and you always reach the limit but you aren't doing an abusive use, you can go to the contact section to ask for an higher limit.

Contact with the author

If you have an advice, you've found a bug, you've any question, etc. Send me an e-mail to alex@trackingo.com

Every e-mail will be read and kept in mind.

Extra

A Facebook app was developed using this API: Trackingo Facebook app