Consuming URL Shortening Services - Cligs

Overview

This is another article that talks about URL shortening services. Today we are going to talk about Cligs, one of the popular shortening services on the web.

Be prepared!

Introduction

Today we are talking about another popular shortening service; it's Cligs, one of the most popular shortening services that provide lots of premium features for FREE.

Enough talking, let's begin the discussion.

In December 2009, Cligs acquired by Mister Wong (a very nice bookmarking service.)

Description

How Cligs can help you? Cligs gives you plenty of features, including the following:

• Shortening URLs (registered and non-registered users): You get a short URL that's no more than 20 characters (Tweetburner is 22 and is.gd is only 18) including the domain http://cli.gs.
• URL Management (registered users only): It allows you to manage your short URLs, to edit them, and to remove them if you like.
• Real-time Analytics (registered users only): How many clicked your link, and when.
• URL Previewing (registered and non-registered users): Preview the URL before opening it. Protects you from spam and unwanted sites.

API

Cligs provides you a very nice API with many advantages. The first advantage that we want to talk about is its simplicity. The API is very simple; it has just two functions, one for shortening URLs, and the other for expanding short URLs (to expand a URL means to get the long URL from the short one.)

Another advantage of this API is that it allows you to shorten the URLs whether you are a registered user or not. Of course a registered user need to get an API key in order to link the API calls to his accounts so he can manage the links generated by the API and to watch the analytics.

Shortening URLs

The first function is used for shortening URLs and it's called, create. This function has the following address:

http://cli.gs/api/v1/cligs/create?url={1}&title={2}&key={3}&appid={4}

The API is still in version 1, that's why you see 'v1' in the address. This function takes four parameters, only the first one is required, other parameters are used for authentication:

1. Url: Required. The URL to be shortened.
    
2. Title: Optional. For authenticated calls only. The name that would be displayed on the short URL in your control panel (used for managing your URLs.)
    
3. key: Optional. If you are a registered user and you want to link the API calls to your account, you'll need to enter your API key here.
    
4. Appid: Optional. If you have used an API key, then you have to provide your application name that used to generate this API call (help users know the source of the link.)

So how can you use this function? If this is an anonymous call (i.e. no authentication details provided,) just call the function providing the long URL in its single required argument.

If you need to link this call to a specific account, then you'll need an API key, which the user can get by signing in to his Cligs account, choosing 'My API Keys', then clicking 'Create New API Key' (if he doesn't have one you.) The last step generates an API key that's no exactly 32 characters (see figure 1.)

After you get the API key, you can push it to the function along with your application name in the appid argument.

What about the title argument? For registered users, they can access their clig list (see figure 2) and see the URLs they shortened and the titles they choose above each of the URLs.

Now, let's code! The following function makes use of the Cligs API to shorten URLs. It accepts three arguments, the long URL, the API key, and the application name. If the API key is null (Nothing in VB.NET,) the call is made anonymously, otherwise, the API key and the application name are used.

// C#

string Shorten(string url, string key, string app)
{
    url = Uri.EscapeUriString(url);
    string reqUri =
        String.Format(@"http://cli.gs/api/v1/cligs/create?url={0}", url);
    if (key != null)
        reqUri += "&key=" + key + "&appid=" + app;

    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(reqUri);
    req.Timeout = 5000;

    try
    {
        using (System.IO.StreamReader reader =
            new System.IO.StreamReader(req.GetResponse().GetResponseStream()))
        {
            return reader.ReadLine();
        }
    }
    catch (WebException ex)
    {
        return ex.Message;
    }
}

' VB.NET

Function Shorten(ByVal url As String, ByVal key As String, ByVal app As String) As String

    url = Uri.EscapeUriString(url)
    Dim reqUri As String = String.Format("http://cli.gs/api/v1/cligs/create?url={0}", url)
    If key Is Nothing Then
        reqUri &= "&key=" & key & "&appid=" & app
    End If
 
    Dim req As WebRequest = WebRequest.Create(reqUri)
    req.Timeout = 5000
 
    Try
        Dim reader As System.IO.StreamReader = New System.IO.StreamReader(req.GetResponse().GetResponseStream())
 
        Dim retValue As String = reader.ReadLine()
        reader.Close()
 
        Return retValue
    Catch ex As WebException
        Return ex.Message
    End Try

End Function

Expanding URLs

The other function we have today is the expand function that's used to get the long URL from the short one (e.g. to expand the short URL http://cli.gs/p1hUnW to be http://JustLikeAMagic.com.) This function is very simple and it has the following address:

http://cli.gs/api/v1/cligs/expand?clig={1}

This function accepts only a single argument, that's the clig (short URL) to be expanded. The clig can be specified using one of three ways:

• The clig ID. e.g. p1hUnW.
• The raw URL. e.g. http://cli.gs/p1hUnW.
• The encoded URL. e.g. http%3A%2F%2Fcli.gs%2Fp1hUnW.

You can read more about URL encoding here.

Now it's the time for code! The following function takes a clig and returns its original URL:

// C#

string Expand(string url)

{
    url = Uri.EscapeUriString(url);
    string reqUri = String.Format(@"http://cli.gs/api/v1/cligs/expand?clig={0}", url);
 
    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(reqUri);
    req.Timeout = 5000;
 
    try
    {
        using (System.IO.StreamReader reader =
            new System.IO.StreamReader(req.GetResponse().GetResponseStream()))
        {
            return reader.ReadLine();
        }
    }
    catch (WebException ex)
    {
        return ex.Message;
    }
}' VB.NET

Function Expand(ByVal url As String) As String

    url = Uri.EscapeUriString(url)
    Dim reqUri As String = String.Format("http://cli.gs/api/v1/cligs/expand?clig={0}", url)

    Dim req As WebRequest = WebRequest.Create(reqUri)
    req.Timeout = 5000

    Try
        Dim reader As System.IO.StreamReader =New System.IO.StreamReader(req.GetResponse().GetResponseStream())

        Dim retValue As String = reader.ReadLine()
        reader.Close()

        Return retValue
    Catch ex As WebException
        Return ex.Message
    End Try

End Function

Where to go next

Some other articles about URL shortening services are available here.