Tad.ly API
Overview
Tad.ly allows user to access data using an application programming interface or simply, an API. The API can be used to shorten links, customize links or retrieve data. The API is free and does not require any special access other than registering an account with Tad.ly. Once you register you will get an API key which will enable you to use the API and track the links you shorten with the API.
Please register to get an API key.
Do not share this key with anyone, as they will be able to shorten or customize links under your account.
All API functions require this key as the 'key' paramater unless otherwise stated!
Sections
- /links/data
- /links/shorten
- /links/expand
- /users/authenticate
- /links/clicks
- /links/referrers
- /links/countries
- /users/slugs
How to use this API
Below are a list of the functions that make up this API. The URL of each function will be located at "http://tad.ly/api/<function_name>" (for example "http://tad.ly/api/links/data").Each function lists paramaters that MUST be passed (unless otherwise stated) and as the specified type. In addition to these paramaters all functions require an API key (unless otherwise stated), which you can learn about above. All paramaters must be POSTed, the API will not accept GET.
Below is an example of shortening a URL using PHP and PHP's built in cURL library.
<?php
// The Paramaters of the function we are posting to
$paramaters = array('json' => json_encode(array(
// This is the paramater list
'key' => 'YOUR_API_KEY',
'url' => 'http://www.php.net'
)));
// Make the cURL request
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://tad.ly/api/links/shorten');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $paramaters);
// Get the contents of the page
$contents = curl_exec($curl);
// Close cURL
curl_close($curl);
// Format the data in an array
$data = json_decode($contents, true);
// Confirm it worked
switch($data['status'])
{
case 200:
echo 'Yay it worked!';
break;
case 403:
echo 'Bad API key';
break;
default:
echo 'Error #'.$data['status'].': '.$data['status_txt'];
break;
}
// Do something with the data
print_r($data);
?>
Requirements and Formatting
All API functions will output information in JavaScript Object Notation or JSON.All API functions will return an HTTP Status Code and text. If status does not return "200" then there was an error. Some examples are:
- 200 - The API call was successful.
- 403 - You have an invalid API key.
- 500 - There was an issue with a paramater you passed, review this guide to ensure everything is correct.
API Functions
/links/data
Description
This will return data about given slug(s), such as the title, full URL, created timestamp and click data. This function is ideal for listing a variety of links on a single page. If you are just looking for the URL of the given slug, see /links/expand.Paramaters
- array slugs - Pass an array of slugs to retrieve data on.
Return Values
- string title - The title of the page it links to.
- string full_url - The full URL of the given slug.
- string slug - The slug of the link.
- int created - A UNIX timestamp of when it was created.
- int clicks_local - The number of clicks on this link.
- int clicks_global - The number of clicks sitewide on this URL.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"links":[
{
"clicks_global":10,
"clicks_local":7,
"created":"1282582181",
"full_url":"http://www.google.com",
"slug":"SlXD1w",
"title":"Google"
},
{
"clicks_global":0,
"clicks_local":0,
"created":"1283176289",
"full_url":"http://www.php.net",
"slug":"php",
"title":"PHP: Hypertext Preprocessor"
}
]
}
}
/links/shorten
Description
This will shorten a given long URL and return information about it.Paramaters
- string url - Pass the URL you wish to shorten.
Return Values
- string url - The full URL.
- string slug - The slug of the link.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"link":{
"url":"http:\/\/www.php.net",
"slug":"php"
}
}
}
/links/expand
Description
Returns the URL of a given slug.Paramaters
- string slug - The slug you wish to expand.
Return Values
- string url - The full URL.
- string slug - The slug of the link.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"link":{
"url":"http:\/\/www.php.net",
"slug":"php"
}
}
}
/users/authenticate
Description
Given a username and password, this function returns the API key of the authenticated user. Note: This function does not require an API key to be called.Paramaters
- string username - The username you wish to authenticate.
- string password - The password you wish to authenticate.
Return Values
- boolean valid - True on a valid authentication, otherwise false.
- string api_key - The API key. Note: This is not set if 'valid' is false.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"valid":true,
"api_key":"API_KEY_HERE"
}
}
/links/clicks
Description
Returns the total clicks for the given time period.Paramaters
- string period - This must be equal to either 'today', 'week', 'month', or 'all'.
- string/array slugs - This can either be a single slug or an array of slugs.
Return Values
- int clicks - The total number of clicks.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"clicks":8
}
}
/links/referrers
Description
Returns the referrers for the given time period.Paramaters
- string period - This must be equal to either 'today', 'week', 'month', or 'all'.
- string/array slugs - This can either be a single slug or an array of slugs.
Return Values
- array referrers - The array keys are the referring domain, while the values are the clicks.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"referrers":{
"Direct":"4",
"http://www.somesite.com":"3"
}
}
}
/links/countries
Description
Returns the countries for the given time period.Paramaters
- string period - This must be equal to either 'today', 'week', 'month', or 'all'.
- string/array slugs - This can either be a single slug or an array of slugs.
Return Values
- array countries - The array keys are the country, while the values are the clicks.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"countries":{
"Canada":"7",
"United States":"1"
}
}
}
/users/slugs
Description
Returns all of the links shortened by the user of the supplied API key.Paramaters
- No function specific paramaters, just pass the API key.
Return Values
- string url - The long URL of the link.
- string slug - The slug of the link.
Example Output
{
"status":200,
"status_txt":"OK",
"output":{
"links":[
{
"slug":"rkqN5L",
"url":"http:\/\/www.google.com"
},
{
"slug":"SlXD1w",
"url":"http:\/\/www.php.net"
}
]
}
}
