Cuthut

Cuthut API Documentation

About our API
Requests
Coming Soon
- Specific/ detailed statistics

REST

We try our best to conform to the principles of the REST (Representational State Transfer) style of architecture. The majority of our API requests allow you to simply change the file extension to get the results in different formats. We currently support these data formats; PHP, XML, and JSON.

If a request does not allow multiple data formats, we will highlight that in the documentation.

Request Parameters

Any/ all parameters in a request must be UTF-8. You may URL encode your request parameters if you wish. However, this is not required.

Error Messages

Different requests have different error messages. We will highlight the different error messages for each individual request.

Basic Create

You may use the "Basic Create" request to simple create a short url out of the long url provide, and the new short url is echoed out on the page. It works as follows in PHP;

$longurl = "http://google.com/";
$apiurl = "http://cuthut.com/api/?url=" . $longurl;

$shorturl = file_get_contents($apiurl);
echo $shorturl; /* will echo "http://cuthut.com/Zbk" */

Sample Requests:

http://cuthut.com/api/?url=http://google.com/
http://cuthut.com/api/?url=http://gilesvangruisen.com/

Request Parameters:

url: required, the valid, long url you wish to shorten

Formats: php
Error Messages:

If no URL is provided, or URL is invalid (?), it will echo "Invalid or no URL"

Create Request

This a more complex version of Basic Create. Along with shortening the provided URL, it will also returns more information about it such as number of clicks, time created, and more. Example using PHP and the XML api.

$longurl = "http://google.com/";
$apiurl = "http://cuthut.com/api/create.xml?url=" . $longurl;

$xmlfile = simplexml_load_file($apiurl);

echo $xmlfile->short; /* shortened URL e.g. http://cuthut.com/Zbk */
echo $xmlfile->shortcode; /* short code e.g, Zbk */
echo $xmlfile->long; /* long url e.g. http://google.com/ */
echo $xmlfile->time; /* timestamp for when the short URL was
created e.g. 2009-08-30 01:29:22 */
echo $xmlfile->clicks; /* number of clicks e.g. 12 */
echo $xmlfile->source; /* where the url was shortened e.g. web */

Sample Requests:

http://cuthut.com/api/create.format?url=http://google.com/&customchshort=google
http://cuthut.com/api/create.format?url=http://gilesvangruisen.com/&custo mchshort=gvg&customchsource=myappname

Request Parameters:

url: required, the valid, long url you wish to shorten, must be the first parameter in request
chcustomshort: optional, the custom shortcode you wish to use for a new short link, can be either second or third parameter in request
chcustomsource: optional, the custom source you wish to use for a new short link, can be either second or third parameter in request

Formats: php, xml, json
Error Messages:

If no URL is provided, or URL is invalid (?), it will echo "Invalid or no URL"

Read Request

Use the read request to read statistics for a cuthut shortened URL. It will return the short url, shortcode, long url (url it redirects to), time created, number of clicks, and the source. Example using PHP and the XML api.

$shortcode = "Zbk";
$apiurl = "http://cuthut.com/api/read.xml?url=" . $longurl;

$xmlfile = simplexml_load_file($apiurl);

echo $xmlfile->short; /* shortened URL e.g. http://cuthut.com/Zbk */
echo $xmlfile->shortcode; /* short code e.g, Zbk */
echo $xmlfile->long; /* long url e.g. http://google.com/ */
echo $xmlfile->time; /* timestamp for when the short URL was
created e.g. 2009-08-30 01:29:22 */
echo $xmlfile->clicks; /* number of clicks e.g. 12 */
echo $xmlfile->source; /* where the url was shortened e.g. web */

Sample Requests:

http://cuthut.com/api/read.format?url=Zbk
http://cuthut.com/api/read.format?url=http://gilesvangruisen.com/

Request Parameters:

url: required, as you see in the sample requests, this can be either a shortcode for a cuthut shortened url, or a long url that has ben previously shortened with cuthut

Formats: php, xml, json
Error Messages:

If no URL/ shortcode is provided, or it doesn't exist on our servers, it will return "Invalid or no URL"

Additional Notes:

Unlike the Create Request, the Read Request will not shorten a url if it doesn't already exist on our servers, it simply returns the statistics.

Specific/ detailed statistics

We're working hard on an update to our api that will give you the ability to have a request for a specific type of statistic, as well as time specific requests. If you'd like more information on this update to our api, feel free to tweet us @cuthut or contact our lead developer, Giles Van Gruisen. Be sure to specify "I have a Cuthut-related enquiry" when you submit the form.

What determines a valid URL?

Valid URLs must contain the http:// prefix, but the "www" is not necessarily. It may be a sub-domain. The valid URL must not be an already shortened Cuthut URL, but it may be a URL to somewhere else on our site such as the blog, or the faq pages. The URL also must not be a from another URL shortening service. If you'd like to see our list of URL shortening services, please feel free to tweet us @cuthut.