Caplet: Your Daily Time Capsule

API Reference

Data In

Posting data to Caplet is straightforward. A client must send a HTTP POST request to http://caplet.me/mobile/upload/ including the following parameters:

• username: (string) The username of the user account that you wish to post a caplet to.
• password: (string) The password of the user account that you wish to post a caplet to.
• mood: (string) The selected mood, from the list below.
• text: (string) The entered text.
• latitude: (float) The calculated latitude.
• longitude: (float) The calculated longitude.
• hidden: (bool [0, 1]) 1 if the caplet should be hidden from aggregate visualizations, 0 if not.
• photo: (file) The associated photo.

Possible moods are (auto-generated):

• amused
• anxious
• awkward
• bored
• content
• determined
• devious
• disappointed
• disillusioned
• embarrassed
• exhausted
• exhilarated
• frustrated
• furious
• giddy
• grateful
• intrigued
• irritated
• lonely
• nostalgic
• optimistic
• perplexed
• regretful
• relieved
• surprised

The response will be in a text/plain format. If the post succeeded, it will be:

Success! Thanks, [first_name] :)

...where [first_name] is the user's first name. If the post failed, the response will be:

Upload failed. [reason]

...where [reason] is some (hopefully useful) string documenting the error that occurred.

Data Out

Retrieving data from Caplet is marginally more complicated. All data is returned in JSON format. To request the content of a caplet, one must know that caplet's unique ID and, of course, the username and password of its owner.

To request a list of caplet ids for a user, simply send a HTTP GET request to http://caplet.me/api/list/. The required parameters are username and password. An optional boolean parameter desc is accepted, defining whether the results are ordered chronologically ascending (earliest is first) or descending. desc defaults to false (so the ordering is ascending). For example:

http://caplet.me/api/list/?username=bob&password=secretofbob

...would return something like:

{'caplets': [57, 62, 80, 105, 206, 452]}

A similar request:

http://caplet.me/api/list/?username=bob&password=secretofbob&desc=true

...would return:

{'caplets': [452, 206, 105, 80, 62, 57]}

Note that while caplet ids will almost always be ascending in chronological order, it's not guaranteed.

Once you've got a caplet id, you can request data for that caplet using http://caplet.me/api/individual/, defining, along with username and password, an id parameter. For example:

http://caplet.me/api/list/?username=bob&password=secretofbob&id=105

That would return something like:

{
	'caplet': {
		'mood': 'optimistic',
		'text': 'This new Caplet API is gonna be awesome!',
		'time': {
			'hour': 17,
			'month': 5,
			'second': 11,
			'year': 2010,
			'day': 5,
			'minute': 23
		},
		'weather': {
			'image': 'http://google.com/ig/images/weather/partly_cloudy.gif',
			'weather': 'partly cloudy',
			'temperature': 79,
			'humidity': 28
		},
		'location': {
			'lat': '39.954650',
			'lon': '-75.195550'
		},
		'photo': {
			'avg_color_r': 97,
			'avg_color_g': 95,
			'avg_color_b': 79,
			'tiny_url': 'http://caplet.me/resources/images/photos/....png',
			'thumb_url': 'http://caplet.me/resources/images/photos/....png',
			'photo_url': 'http://caplet.me/resources/images/photos/....jpg'
		},
		'user': {
			'username': 'bob',
			'first_name': 'Bob',
			'last_name': 'Smith'
		}
	}
}
	

Things to note:

• The root key is 'caplet'.
• All images (weather image, different photo sizes) are absolute URLs.
• Average colors are out of the standard 255.
• tiny_url is NOT a TinyURL link, but rather an absolute URL to the tiniest size of photo that Caplet stores: 20x20 px.
• The size of thumb_url is 75x75 px.
• The size of the original photo varies.

If an error occurs during these API calls, the response will consist of an error key:

{ 'error' : 'Cannot access this caplet.' }

Last updated: May 6, 2010.