URL shortener API documentation
The clicky.me API allows you to automate the process of creating short URLs.Requests are sent via HTTP GET to the following script:
http://clicky.me/app/api
Jump to:
AuthenticationParameters
Example requests
Example responses
Plain text processing
Authentication
An account with Clicky Web Analytics is required to use clicky.me, so every request to the API must be authenticated. There are two ways to do this. You can send in either your Clicky username and password, or you can send in the site_id and its sitekey_admin value.Username / password
This method should be easier to implement, as you don't have to store all the sitekey_admin value for each of your sites. Instead, you just need the site ID for the site you are creating a new short URL for. If you are creating a short URL for a third party site (e.g., a site that you are not tracking with Clicky), then you must use this method, as it's the only way to authenticate your request.Note: We plan to add this kind of authentication to the stats API as well, to simplify all API requests moving forward.
site_id / sitekey_admin
You can alternatively specify the site_id and its sitekey_admin value to create a short URL for a specific site you are tracking with Clicky. You should only use this method to create short URLs that point to sites you are tracking with Clicky, otherwise you will not get any analytics on your short URLs.Parameters
username / password / site_id / sitekey_admin
Required. For authentication, you must send either your Clicky username and password, or a site_id and its sitekey_admin value.url
Required. The URL you are shortening. This must be valid URL, e.g. http://my-site.com/interesting-page.html.Don't forget to URL encode this value.
url_custom
If you want to create a custom short URL, specify the value here, e.g. url_custom=cooltitle. Custom URLs must be between 6 and 32 characters long, start with a letter, and contain only letters, numbers, and dashes.site_id
The site_id that this link will be attached to, which is where all of the analytics will show up. If you are using site_id/sitekey_admin authentaction, you have already specified this. Otherwise, you need to specify it in addition to the username/password.If this short URL is pointing to a third party web site (e.g. one you are not tracking with Clicky), you should not specify this value, otherwise you will not be able to get any analytics on this short URL.
output
The API can respond with either plain text, or XML. By default, it responds in plain text ("txt"), with a single line of output (either the shortened URL, or an error). However, you can specify output=xml if you prefer that format instead.Example requests
Note that the URLs in these requests are not URL encoded, to make the examples easier to read. But you really must URL encode them when you talk to the API!Some parts of the requests are highlighted in red to highlight the differences between the types of requests.
Username / password authentication for a site you are tracking with Clicky
Specify the site_id you that this URL points to so you get the full analytics available.
http://clicky.me/app/api?username=X&password=Y&site_id=123&url=http://mysite.com/
Username / password authentication for a site you are NOT tracking with Clicky
Do not specify a site_id if the URL points to a site that you are not tracking with Clicky. If you do, you won't get any click-through data for this short URL.
http://clicky.me/app/api?username=X&password=Y&url=http://google.com/
site_id / sitekey_admin authentication
Since you must specify a site_id for the authentication, this short URL will automatically be attached to the same site ID. You should not use this type of authentication for URLs that point to sites you are not tracking with Clicky, or you won't get any click-through data for this short URL.
http://clicky.me/app/api?site_id=123&sitekey_admin=123&url=http://mysite.com/
Username / password authentication with custom URL
http://clicky.me/app/api?username=X&password=Y&site_id=123&url=http://mysite.com/&url_custom=mysite
Example responses
Valid requests return the shortened URL, invalid requests return an error. The response will be in either plain text or XML, depending on what you specify for output. All four of these potential responses are shown below. Note that there are many types of errors, but only one specific error is shown here.Valid request, XML output
<?xml version="1.0" encoding="utf-8"?>
<response>
<shorturl>http://clicky.me/123</shorturl>
</response>
Valid request, plain text output
http://clicky.me/123
Invalid request, XML output
<?xml version="1.0" encoding="utf-8"?>
<response>
<error>Invalid username/password combination.</error>
</response>
Invalid request, plain text output
Error: Invalid username/password combination.
Plain text processing
For one line responses, plain text responses are very easy to work. This example (in PHP) shows how to do that.To make a remote request in PHP, use file_get_contents(). This requires the PHP option allow_url_fopen to be enabled, which many web hosts disable these days. If that is the case with your host, you will have to use something like the cURL library instead.
With file_get_contents, you just pass in the URL you want to request, and it returns to you a string that contains the entire contents of the response from the remote server. Then you just need to check the contents of the returned data to see if there is a valid URL in there (which means the request was successful) or not.
<?php
# URL encode!
$url = urlencode('http://mysite.com/');
# Send request, $x will contain the response from our API.
# We do a trim() also to get rid of the new line character at the end of the string.
$x = trim( file_get_contents('http://clicky.me/app/api?username=X&password=Y&site_id=123&url='.$url));
# If the returned string starts with http://, the request was successful.
if( preg_match( '#^http://#', $x )) {
# Success! Do something with $x, which contains the shortened URL.
}
else {
# Failure! $x will contain the error.
# You can output it to the user or do whatever you want with it.
}
?>
