Welcome to the Twicli API. The Twicli platform is totally open to developers who may wish to integrate a photo, video and audio sharing service into their desktop and mobile applications.

Please note that our API is in beta. If you wish to integrate please see the basic and advanced methods below.

You may want to follow @TwicliAPI for announcements and updates. You can also contact us via this form.

API Key

Sending an API key with your request is optional and, if sent, will help us track which apps are using the service.

Benefits of using an API key

In the next release of Twicli, your app will be advertised on Twicli with via YourApp next to posts you send. If no API key is sent then via API will be displayed instead.

By providing an API key, Twicli staff will be able to track which apps are using the API.

You will receive free advertising on Twicli in the top right ad placeholder.

Your generated API key

l011p5egoxkv8ldq1tbwk6ffvasg

Start sending this API key with your requests immediately and your app name should start to appear next to posts in the latest release of Twicli.

Basic Methods

Application developers will most likely be familiar with these methods already from using other APIs.

uploadPhoto - Upload a photo to Twicli.

URL

http://twic.li/api/uploadPhoto

Function

This method simply uploads a photo to Twicli. The photo will instantly appear in the users photo listing. No tweet is sent.

Method

POST

Data should be submitted as multipart/form-data.

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
photo	Required	Binary	Binary data for the photo
username	Required	Text	Twitter username
password	Required	Text	Twitter password
show_map	Optional	Integer 0 for No 1 for Yes	Display a Google Map on the photo page? Note: Map is only displayed if EXIF geodata actually exists. Privacy is important so please make it clear that this feature exposes the exact location the photo was taken.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Maximum photo filesize: 5MB.
Minimum photo dimensions: 100 x 100 pixels.
Supported formats: JPG, GIF, PNG.
Supported MIME types: image/jpeg, image/pjpeg, image/gif, image/png.
username and password must be valid Twitter login details.

Example Responses

XML - Success

<response status="ok">
  <content type="photo">
    <id>ek</id>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/ek</url>
    <num_comments>2</num_comments>
    <num_user_tags>0</num_user_tags>
    <num_views>51</num_views>
    <latitude>39.5245</latitude>
    <longitude>2.46233</longitude>
    <show_map>1</show_map>
    <camera_make>Apple</camera_make>
    <camera_model>iPhone</camera_model>
    <timestamp>1251243361</timestamp>
    <sizes>
      <original_url>http://twic.li/api/photo.jpg?id=ek&size=original</original_url>
      <large_url>http://twic.li/api/photo.jpg?id=ek&size=large</large_url>
      <medium_url>http://twic.li/api/photo.jpg?id=ek&size=medium</medium_url>
      <small_url>http://twic.li/api/photo.jpg?id=ek&size=small</small_url>
      <square_url>http://twic.li/api/photo.jpg?id=ek&size=square</square_url>
      <tile_url>http://twic.li/api/photo.jpg?id=ek&size=tile</tile_url>
      <largest_available_url>http://twic.li/api/photo.jpg?id=ek&size=largest_available</largest_available_url>
    </sizes>
  </content>
</response>

XML - Fail

<response status="fail">
<error_code>1x07</error_code>
<error_text>Invalid file type. We support JPG, GIF and PNG images</error_text>
</response>

Error Codes

Code	Description
1x01	Missing required POST parameter photo
1x02	Missing required POST parameter username
1x03	Missing required POST parameter password
1x04	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
1x05	Twitter user does not exist
1x06	There was an internal error during your photo upload
1x07	Invalid file type. We support JPG, GIF and PNG images
1x08	Your photo is too large. Please keep files under 5MB
1x09	There was a problem with your photo. Please re-save it as a JPG
1x10	Your photo was too small. Minimum resolution 100 x 100

Code Samples

PHP using cURL

<?php

// This script will upload testimage.jpg through the Twicli uploadPhoto API method.
// Note: testimage.jpg must be in the same directory as this PHP script.

set_time_limit(0);

// Define POST variables array
$postfields = array();
$postfields['username'] = 'username';
$postfields['password'] = 'password';
$postfields['show_map'] = 0;
$postfields['photo'] = '@testimage.jpg';

$api_url = 'http://twic.li/api/uploadPhoto';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, 3);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

uploadPhotoAndTweet - Upload a photo to Twicli and send a status update to Twitter.

URL

http://twic.li/api/uploadPhotoAndTweet

Function

This method uploads a photo to Twicli and sends a status update to Twitter. The photo will instantly appear in the users photo listing.

Method

POST

Data should be submitted as multipart/form-data.

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
photo	Required	Binary	Binary data for the photo
username	Required	Text	Twitter username
password	Required	Text	Twitter password
tweet	Optional	Text	The text to be sent as a tweet. The photo URL is added to the end of the tweet text automatically.
show_map	Optional	Integer 0 for No 1 for Yes	Display a Google Map on the photo page? Note: Map is only displayed if EXIF geodata actually exists. Privacy is important so please make it clear that this feature exposes the exact location the photo was taken.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Maximum photo filesize: 5MB.
Minimum photo dimensions: 100 x 100 pixels.
Supported formats: JPG, GIF, PNG.
Supported MIME types: image/jpeg, image/pjpeg, image/gif, image/png.
Photo URLs are inserted automatically so the maximum character length of the tweet text should be roughly 20 characters less than usual 140 chars.
username and password must be valid Twitter login details.

Example Responses

XML - Success

XML - Fail

<response status="fail">
<error_code>1x07</error_code>
<error_text>Invalid file type. We support JPG, GIF and PNG images</error_text>
</response>

Error Codes

Note: These error codes are exactly the same as the uploadPhoto method.

Code	Description
1x01	Missing required POST parameter photo
1x02	Missing required POST parameter username
1x03	Missing required POST parameter password
1x04	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
1x05	Twitter user does not exist
1x06	There was an internal error during your photo upload
1x07	Invalid file type. We support JPG, GIF and PNG images
1x08	Your photo is too large. Please keep files under 5MB
1x09	There was a problem with your photo. Please re-save it as a JPG
1x10	Your photo was too small. Minimum resolution 100 x 100

Code Samples

PHP using cURL

<?php

// This script will upload testimage.jpg through the Twicli uploadPhotoAndTweet API method and send a status update to Twitter.
// Note: testimage.jpg must be in the same directory as this PHP script.

set_time_limit(0);

// Define POST variables array
$postfields = array();
$postfields['username'] = 'username';
$postfields['password'] = 'password';
$postfields['tweet'] = 'Tweet text goes here';
$postfields['show_map'] = 0;
$postfields['photo'] = '@testimage.jpg';

$api_url = 'http://twic.li/api/uploadPhotoAndTweet';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, 3);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

photo.jpg - Displays a photos image in its chosen size. This method outputs a .jpg image.

URL

http://twic.li/api/photo.jpg

URL (With Example Parameters)

http://twic.li/api/photo.jpg?id=aeA&size=medium

Function

This method takes an photo id and size parameter and returns a jpg image. Note: In the next release of Twicli, this API method will also provide data for users who have been tagged into this photo.

Method

GET

Requires Authentication

FALSE

Parameters

Name	Required	Expected Input	Details
id	Required	Text	The content id. The id for http://twic.li/aeA would be aeA.
size	Required	Text	The size to be returned. Valid sizes are as follows: original large medium small square tile largest_available
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

id must be valid.
Do not send the full URL (http://twic.li/aeA) to the id parameter. Just send aeA.
id is case sensitive.

Example Responses

Success

This method uses a HTTP 301 Redirect to send you to the actual image file.

The example below is a medium sized image.

URL used in example: http://twic.li/api/photo.jpg?id=ek&size=medium

XML - Fail

<response status="fail">
<error_code>5x04</error_code>
<error_text>Invalid id. Content does not exist or is not a photo</error_text>
</response>

Error Codes

Code	Description
5x01	Missing required GET parameter id
5x02	Missing required GET parameter size
5x03	Invalid input for GET parameter size
5x04	Invalid id. Content does not exist or is not a photo
5x05	This photo is not available in size size

Code Samples

XHTML

uploadVideo - Upload a video to Twicli.

URL

http://twic.li/api/uploadVideo

Function

This method simply uploads a video to Twicli. The video will instantly appear in the users video listing. No tweet is sent.

Method

POST

Data should be submitted as multipart/form-data.

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
video	Required	Binary	Binary data for the video
username	Required	Text	Twitter username
password	Required	Text	Twitter password
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Maximum video filesize: 100MB.
Supported formats: MPEG, WMV, MOV, MP4, 3GP, M4V.
Supported MIME types: video/mp4, video/3gpp, video/quicktime, video/x-m4v, video/x-msvideo, video/mpeg, application/octet-stream.
username and password must be valid Twitter login details.

Example Responses

XML - Success

<response status="ok">
  <content type="photo">
    <id>abd</id>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/abd</url>
    <num_comments>2</num_comments>
    <num_views>51</num_views>
    <timestamp>1251243361</timestamp>
    <video_file_url>http://twic.li/api/video.flv?id=abd</video_file_url>
    <thumb_image_url>http://b.static.picli.com/vti/l/0a3bce36c539c69edd5a9cc5.jpg</thumb_image_url>
  /content>
</response>

XML - Fail

<response status="fail">
<error_code>2x06</error_code>
<error_text>There was an internal error during your video upload</error_text>
</response>

Error Codes

Code	Description
2x01	Missing required POST parameter video
2x02	Missing required POST parameter username
2x03	Missing required POST parameter password
2x04	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
2x05	Twitter user does not exist.
2x06	There was an internal error during your video upload
2x07	Invalid file type. We support MPEG, WMV, MOV, MP4, 3GP, M4V
2x08	Your video is too large. Please keep files under 100MB
2x09	Sorry, we do not support this video codec

Code Samples

PHP using cURL

<?php

// This script will upload testvideo.mov through the Twicli uploadVideo API method.
// Note: testvideo.mov must be in the same directory as this PHP script.

set_time_limit(0);

// Define POST variables array
$postfields = array();
$postfields['username'] = 'username';
$postfields['password'] = 'password';
$postfields['video'] = '@testvideo.mov';

$api_url = 'http://twic.li/api/uploadVideo';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, 3);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

uploadVideoAndTweet - Upload a video to Twicli and send a status update to Twitter.

URL

http://twic.li/api/uploadVideoAndTweet

Function

This method uploads a video to Twicli and sends a status update to Twitter. The video will instantly appear in the users video listing.

Method

POST

Data should be submitted as multipart/form-data.

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
video	Required	Binary	Binary data for the video
username	Required	Text	Twitter username
password	Required	Text	Twitter password
tweet	Optional	Text	The text to be sent as a tweet. The video URL is added to the end of the tweet automatically.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Maximum video filesize: 100MB.
Supported formats: MPEG, WMV, MOV, MP4, 3GP, M4V.
Supported MIME types: video/mp4, video/3gpp, video/quicktime, video/x-m4v, video/x-msvideo, video/mpeg, application/octet-stream.
Video URLs are inserted automatically so the maximum character length of the tweet text should be roughly 20 characters less than the usual 140 chars.
username and password must be valid Twitter login details.

Example Responses

XML - Success

<response status="ok">
  <content type="video">
    <id>abd</id>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/abd</url>
    <num_comments>2</num_comments>
    <num_views>51</num_views>
    <timestamp>1251243361</timestamp>
    <video_file_url>http://twic.li/api/video.flv?id=abd</thumb_image_url>
    <thumb_image_url>http://b.static.picli.com/vti/l/0a3bce36c539c69edd5a9cc5.jpg</thumb_image_url>
  </content>
</response>

XML - Fail

<response status="fail">
<error_code>2x06</error_code>
<error_text>There was an internal error during your video upload</error_text>
</response>

Error Codes

Note: These error codes are exactly the same as the uploadVideo method.

Code	Description
2x01	Missing required POST parameter video
2x02	Missing required POST parameter username
2x03	Missing required POST parameter password
2x04	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
2x05	Twitter user does not exist
2x06	There was an internal error during your video upload
2x07	Invalid file type. We support MPEG, WMV, MOV, MP4, 3GP, M4V
2x08	Your video is too large. Please keep files under 100MB
2x09	Sorry, we do not support this video codec

Code Samples

PHP using cURL

<?php

// This script will upload testvideo.mov through the Twicli uploadVideoAndTweet API method.
// Note: testvideo.mov must be in the same directory as this PHP script.

set_time_limit(0);

// Define POST variables array
$postfields = array();
$postfields['username'] = 'username';
$postfields['password'] = 'password';
$postfields['tweet'] = 'Tweet text goes here';
$postfields['video'] = '@testvideo.mov';

$api_url = 'http://twic.li/api/uploadVideoAndTweet';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, 3);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

video.flv - Displays a video file. This method outputs a .flv flash video.

URL

http://twic.li/api/video.flv

URL (With Example Parameters)

http://twic.li/api/video.flv?id=abd

Function

This method takes a video id and returns a flash video for it.

Method

GET

Requires Authentication

FALSE

Parameters

Name	Required	Expected Input	Details
id	Required	Text	The content id. The id for http://twic.li/abd would be abd.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

id must be valid.
Do not send the full URL (http://twic.li/abd) to the id parameter. Just send abd.
id is case sensitive.

Example Responses

Success

This method uses a HTTP 301 Redirect to send you to the actual flash video file.

Example URL: http://twic.li/api/video.flv?id=abd

XML - Fail

<response status="fail">
<error_code>6x02</error_code>
<error_text>Invalid ID. Content does not exist or is not a video</error_text>
</response>

Error Codes

Code	Description
6x01	Missing required GET parameter id
6x02	Invalid id. Content does not exist or is not a video

uploadAudio - Upload an audio file to Twicli.

URL

http://twic.li/api/uploadAudio

Function

This method simply uploads an audio file to Twicli. The audio will instantly appear in the users audio listing. No tweet is sent.

Method

POST

Data should be submitted as multipart/form-data.

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
audio	Required	Binary	Binary data for the audio file
username	Required	Text	Twitter username
password	Required	Text	Twitter password
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Maximum audio filesize: 50MB.
Supported formats: MP3, M4A, WAV.
Supported MIME types: audio/mpg, audio/mpeg, audio/m4a, audio/x-m4a, audio/mpeg3, audio/x-mpeg-3, audio/x-wav, audio/mp4a-latm, application/octet-stream.
username and password must be valid Twitter login details.

Example Responses

XML - Success

<response status="ok">
  <content type="audio">
    <id>anD</id>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/anD</url>
    <num_comments>2</num_comments>
    <num_views>51</num_views>
    <timestamp>1251243361</timestamp>
    <audio_file_url>http://twic.li/api/audio.mp3?id=anD</audio_file_url>
  </content>
</response>

XML - Fail

<response status="fail">
<error_code>3x06</error_code>
<error_text>There was an internal error during your audio upload.</error_text>
</response>

Error Codes

Code	Description
3x01	Missing required POST parameter audio
3x02	Missing required POST parameter username
3x03	Missing required POST parameter password
3x04	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
3x05	Twitter user does not exist
3x06	There was an internal error during your audio upload
3x07	Invalid file type. We support MP3, M4A, WAV.
3x08	Your audio file is too large. Please keep files under 50MB
3x09	Sorry, we do not support this audio codec

Code Samples

PHP using cURL

<?php

// This script will upload testaudio.mp3 through the Twicli uploadAudio API method.
// Note: testaudio.mp3 must be in the same directory as this PHP script.

set_time_limit(0);

// Define POST variables array
$postfields = array();
$postfields['username'] = 'username';
$postfields['password'] = 'password';
$postfields['audio'] = '@testaudio.mp3';

$api_url = 'http://twic.li/api/uploadAudio';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, 3);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

uploadAudioAndTweet Upload an audio file to Twicli and send a status update to Twitter.

URL

http://twic.li/api/uploadAudioAndTweet

Function

This method uploads an audio file to Twicli and sends a status update to Twitter. The audio will instantly appear in the users audio listing.

Method

POST

Data should be submitted as multipart/form-data.

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
audio	Require	Binary	Binary data for the audio file
username	Required	Text	Twitter username
password	Required	Text	Twitter password
tweet	Optional	Text	The text to be sent as a tweet. The audio URL is added to the end of the tweet automatically.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Maximum audio filesize: 50MB.
Supported formats: MP3, M4A, WAV.
Supported MIME types: audio/mpg, audio/mpeg, audio/m4a, audio/x-m4a, audio/mpeg3, audio/x-mpeg-3, audio/x-wav, audio/mp4a-latm, application/octet-stream.
Audio URLs are inserted automatically so the maximum character length of the tweet text should be roughly 20 characters less than the usual 140 chars.
username and password must be valid Twitter login details.

Example Responses

XML - Success

XML - Fail

<response status="fail">
<error_code>3x06</error_code>
<error_text>There was an internal error during your audio upload</error_text>
</response>

Error Codes

Note: These error codes are exactly the same as the uploadAudio method.

Code	Description
3x01	Missing required POST parameter audio
3x02	Missing required POST parameter username
3x03	Missing required POST parameter password
3x04	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
3x05	Twitter User does not exist
3x06	There was an internal error during your audio upload
3x07	Invalid file type. We support MP3, M4A, WAV
3x08	Your audio file is too large. Please keep files under 50MB
3x09	Sorry, we do not support this audio codec

Code Samples

PHP using cURL

audio.mp3 - Displays an audio file. This method outputs an .mp3 file.

URL

http://twic.li/api/audio.mp3

URL (With Example Parameters)

http://twic.li/api/audio.mp3?id=g6

Function

This method takes an audio id and returns an mp3 audio file.

Method

GET

Requires Authentication

FALSE

Parameters

Name	Required	Expected Input	Details
id	Required	Text	The content id. The id for http://twic.li/g6 would be g6.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

id must be valid.
Do not send the full URL (http://twic.li/abd) to the id parameter. Just send abd.
id is case sensitive.

Example Responses

Success

This method uses a HTTP 301 Redirect to send you to the actual audio file.

Example URL: http://twic.li/api/audio.mp3?id=g6

XML - Fail

<response status="fail">
<error_code>7x02</error_code>
<error_text>Invalid ID. Content does not exist or is not audio.</error_text>
</response>

Error Codes

Code	Description
7x01	Missing required GET parameter id
7x02	Invalid id. Content does not exist or is not audio

Advanced Methods

For developers who want to try something new...

getContent - Returns information for an individual piece of content (photo, video, audio or set).

URL

http://twic.li/api/getContent

URL (With Example Parameters)

http://twic.li/api/getContent?id=aeA

Function

This method takes an id and returns information for that piece of content. Information is also provided that distinguishes between the various content types (photos, videos, audio and sets).

Method

GET

Requires Authentication

FALSE

Parameters

Name	Required	Expected Input	Details
id	Required	Text	The content id. The id for http://twic.li/aeA would be aeA.
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

id must be valid.
Do not send the full URL (http://twic.li/aeA) to the id parameter. Just send aeA.
id is case sensitive.

Example Responses

XML - Success

<response status="ok">
  <content type="photo">
    <id>ek</id>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/ek</url>
    <num_comments>2</num_comments>
    <num_user_tags>0</num_user_tags>
    <num_views>51</num_views>
    <latitude>39.5245</latitude>
    <longitude>2.46233</longitude>
    <show_map>1</show_map>
    <camera_make>Apple</camera_make>
    <camera_model>iPhone</camera_model>
    <timestamp>1251243361</timestamp>
    <sizes>
      <original_url>http://twic.li/api/photo.jpg?id=ek&size=original<original_url>
      <large_url>http://twic.li/api/photo.jpg?id=ek&size=large<large_url>
      <medium_url>http://twic.li/api/photo.jpg?id=ek&size=medium<medium_url>
      <small_url>http://twic.li/api/photo.jpg?id=ek&size=small<small_url>
      <square_url>http://twic.li/api/photo.jpg?id=ek&size=square<square_url>
      <tile_url>http://twic.li/api/photo.jpg?id=ek&size=tile<tile_url>
      <largest_available_url>http://twic.li/api/photo.jpg?id=ek&size=largest_available<largest_available_url>
    </sizes>
  </content>
</response>

XML - Fail

<response status="fail">
<error_code>4x02</error_code>
<error_text>Invalid id. Content does not exist.</error_text>
</response>

Error Codes

Code	Description
4x01	Missing required GET parameter id
4x02	Invalid id. Content does not exist

Code Samples

PHP using cURL

<?php

// This script will request data for an individual photo through the Twicli getContent API method.
set_time_limit(0);

$api_url = 'http://twic.li/api/getContent?id=aeA';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

getUsersContent - Returns a list of a users uploaded content for the requested content type (photos/videos etc).

URL

http://twic.li/api/getUsersContent

URL (With Example Parameters)

http://twic.li/api/getUsersContent?username=twiclistaff&content_type=photos

Function

This method takes either a userid OR username parameter. This function returns a list of a particular users content depending on the content_type. Works with photos, videos and audio listings.

Method

GET

Requires Authentication

FALSE

Parameters

Name	Required	Expected Input	Details
userid	Optional	Integer	Twitter user id. Ignore if username is provided instead.
username	Optional	Text	Twitter username. Ignore if userid is provided instead.
content_type	Required	Text	Type of content to be returned. Valid options are "photos", "videos" and "audio".
api_key	Optional	Text	Your API key. Click here for more information

Limitations & Notes

Can only return photos, videos and audio. No set information is available.
If no content exists for that user you will receive an empty response tag in the returned XML. Not an error code.

Example Responses

XML - Success

<response status="ok">
  <content type="photo">
    <id>ek</id>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/ek</url>
    <num_comments>2</num_comments>
    <num_user_tags>0</num_user_tags>
    <num_views>51</num_views>
    <latitude>39.5245</latitude>
    <longitude>2.46233</longitude>
    <show_map>1</show_map>
    <camera_make>Apple</camera_make>
    <camera_model>iPhone</camera_model>
    <timestamp>1251243361</timestamp>
    <sizes>
      <original_url>http://twic.li/api/photo.jpg?id=ek&size=original<original_url>
      <large_url>http://twic.li/api/photo.jpg?id=ek&size=large<large_url>
      <medium_url>http://twic.li/api/photo.jpg?id=ek&size=medium<medium_url>
      <small_url>http://twic.li/api/photo.jpg?id=ek&size=small<small_url>
      <square_url>http://twic.li/api/photo.jpg?id=ek&size=square<square_url>
      <tile_url>http://twic.li/api/photo.jpg?id=ek&size=tile<tile_url>
      <largest_available_url>http://twic.li/api/photo.jpg?id=ek&size=largest_available<largest_available_url>
    </sizes>
  </content>
  <content type="photo">
  ... etc   ... etc </response>

XML - Fail

<response status="fail">
<error_code>10x01</error_code>
<error_text>Missing required GET parameters userid OR username</error_text>
</response>

Error Codes

Code	Description
10x01	Missing required GET parameters userid OR username
10x02	Missing required GET parameter content_type

tagUserIntoPhoto - Tag a Twitter user into a photo based on coords from the top left of the large image size.

URL

http://twic.li/api/tagUserIntoPhoto

Function

This method will tag a twitter user into a photo based on coordinates from the top left of the large size image.

Method

POST

Requires Authentication

TRUE

Be sure to provide the username and password parameters.

Parameters

Name	Required	Expected Input	Details
id	Required	Text	The content id. The id for http://twic.li/aeA would be aeA.
username	Required	Text	Twitter username of the person doing the tagging.
password	Required	Text	Twitter password of the person doing the tagging.
tagged_username	Required	Text	Twitter username of the person being tagged into the photo.
x_coord	Required	Integer (ie. 232)	Horizontal width (in pixels) between furthest left boundary (0px left) and start of the tag region. Please refer to the Visual Diagram.
y_coord	Required	Integer (ie. 78)	Vertical width (in pixels) between furthest top boundary (0px top) and start of the tag region. Please refer to the Visual Diagram.
x_offset	Required	Integer (ie. 87)	Horizontal width (in pixels) between furthest left tag region boundary (x_offset) and end of the tag region. Please refer to the Visual Diagram.
y_offset	Required	Integer (ie. 98)	Vertical width (in pixels) between furthest top tag region boundary (y_offset) and end of the tag region. Please refer to the Visual Diagram.
api_key	Optional	Text	Your API key. Click here for more information

Visual Diagram

Limitations & Notes

id must be valid.
Do not send the full URL (http://twic.li/aeA) to the id parameter. Just send aeA.
id is case sensitive.
username and password must be valid Twitter login details.
tagged_username must be a valid Twitter username.
Due to a change in large image size, any id created before arq (20th September 2009) is not eligible for user tags via API.
Success codes will differ depending on whether User A owns the photo they are tagging User B into. If they own it then they are able to tag the user into the photo immediately. If not, the tag will need to be approved by the owner of the photo.
x_coord, y_coord, x_offset and y_offset must be sent as positive integers. Do not include px or any other unit.
When displaying a tagging interface to a user, always use the large size dimensions. See the photo.jpg method for more information on photo sizes.
x_offset should not be larger than the width of the photo.
y_offset should not be larger than the height of the photo.
When a user is successfully tagged into a photo a notification is sent from @TwicliBot within 10 minutes. The 10 minute interval is to ensure users are not spammed (if they are tagged into a lot of photos consecutively). Notifications are aggregated and sent as one tweet.

Example Responses

XML - Success

<response status="ok">
  <success_code>9x02</success_code>
  <success_text>You have tagged @sampicli into this photo</success_text>
  <tagged_user>
    <screen_name>sampicli</screen_name>
    <user_id>21186869</user_id>
    <url>http://twic.li/ek</url>
    <x_coord>301</x_coord>
    <y_coord>271</y_coord>
    <x_offset>85</x_offset>
    <y_offset>102</y_offset>
    <timestamp>1251243361</timestamp>
  </tagged_user>
</response>

XML - Fail

<response status="fail">
<error_code>8x09</error_code>
<error_text>Invalid ID. Content does not exist or is not a photo</error_text>
</response>

Error Codes

Code	Description
8x01	Missing required POST parameter id
8x02	Missing required POST parameter username
8x03	Missing required POST parameter password
8x04	Missing required POST parameter tagged_username
8x05	Missing required POST parameter x_coord
8x06	Missing required POST parameter y_coord
8x07	Missing required POST parameter x_offset
8x08	Missing required POST parameter y_offset
8x09	Invalid id. Content does not exist or is not a photo
8x10	This photo can not accept tagged users via Twicli API
8x11	Failed to authorize your Twitter account. Either password is incorrect or API rate limit is exceeded
8x12	Twitter user does not exist
8x13	Tagged Twitter user does not exist
8x14	This user has already been tagged into this photo. The tag may be awaiting approval from the photographer

Success Codes

Code	Description
9x01	You have tagged yourself into this photo
9x02	You have tagged @tagged_username into this photo
9x03	You have tagged yourself into this photo. Your tag must be approved by @photographer before it appears
9x04	You have tagged @tagged_username into this photo. Your tag must be approved by @photographer before it appears

Code Samples

PHP using cURL

<?php

// This script will tag the Twitter user 'sampicli' into a photo through the Twicli tagUserIntoPhoto API method.

set_time_limit(0);

// Define POST variables array
$postfields = array();
$postfields['id']              = 'aus';
$postfields['username']        = 'username';
$postfields['password']        = 'password';
$postfields['tagged_username'] = 'sampicli';
$postfields['x_coord']         = 95;
$postfields['y_coord']         = 105;
$postfields['x_offset']        = 100;
$postfields['x_offset']        = 120;

$api_url = 'http://twic.li/api/tagUserIntoPhoto';

// Initialize cURL and set options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $api_url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, 3);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);

// Execute cURL and store the API's response
$response = curl_exec($curl);

// Display the output
var_dump($response);

?>

Coming Soon...

These methods are under development and will be released in the future.

tagUserIntoVideo - Tag a Twitter user into a video.

tagUserIntoAudio - Tag a Twitter user into an audio file.

createSet - Creates an empty set ready for content to be added using the method below.

addToSet - Joins a series of photo_ids, video_ids and audio_ids together into a set.

API Documentation

API Key

Benefits of using an API key

Your generated API key

Basic Methods

URL

Function

Method

Requires Authentication

Parameters

Limitations & Notes

Example Responses

XML - Success

XML - Fail

Error Codes

Code Samples

PHP using cURL

URL

Function

Method

Requires Authentication

Parameters

Limitations & Notes

Example Responses

XML - Success

XML - Fail

Error Codes

Code Samples

PHP using cURL

URL

URL (With Example Parameters)

Function

Method

Requires Authentication

Parameters

Limitations & Notes

Example Responses

Success

XML - Fail

Error Codes

Code Samples

XHTML

URL

Function

Method

Requires Authentication

Parameters

Limitations & Notes

Example Responses

XML - Success

XML - Fail

Error Codes

Code Samples

PHP using cURL

URL

Function

Method

Requires Authentication

Parameters

Limitations & Notes

Example Responses

XML - Success

XML - Fail

Error Codes

Code Samples

PHP using cURL

URL

URL (With Example Parameters)

Function

Method

Requires Authentication

Parameters

Limitations & Notes

Example Responses

Success

XML - Fail

Error Codes

URL

Function

Method