Consuming URL Shortening Services –

هذه المقالة متوفرة أيضا باللغة العربية، اقرأها هنا.

Read more about URL Shortening Services here.



Contents of this article:

  • Contents
  • Overview
  • Introduction
  • API
  • What’s next


Another article of our endless series that talks about accessing URL shortening services programmatically.

This article is talking about shortening service, how you can use it, and how to access it via your C#/VB.NET application.


We can’t say that is not one of the well-known services nor it has anything special, however, as long as it provides an API we are very interested in it.

When you visit service website,, you can see that nothing easier from, just push your long URL into the text box and click the shortening button.

API provides you a very simple easy-to-use API. This API contains only one function that’s used for shortening URLs. Another good thing is that this function doesn’t require any kind of authentication for users. Therefore, you need just to send it your long URL (as you did with the website.)

The shortening function function is called, it accepts 3 arguments:

  1. action:
    Yet, it can accept only one value, shorturl, which orders the function to shorten the specified url.
  2. url:
    The long URL to be shortened.
  3. format:
    The format of the returned data from the function. Can be simple, xml, or json.

As you know, the .NET BCL doesn’t support JSON (some third-party components do,) and thus, we won’t cover JSON data returned from the function. Rather, we’ll concentrate on plain and XML data returned.

When the format of this function is XML, the returned data, if the function succeeded, is like the following if this is your first time you shorten this URL:

        <date>2010-12-17 20:14:04</date>
    <message> added to database</message>

If, however, this isn’t your first time you shorten this URL, you would get data like this:

    <message> already exists in database</message>

Anyway, you can retrieve the value of shorturl and forget about the rest.

Now, let’s try this function. We’ll try to shorten the URL with our function. First, connect the arguments, e.g. Now copy this address and paste it into your favorite browser. If everything was OK, you should see the short URL after clicking ‘Go’ in the browser toolbar.

Now, let’s do it in C# and VB.NET. Check the following function that tries to shorten long URLs via the API:

// C#

string Shorten(string url, bool xml)
    url = Uri.EscapeUriString(url);
    string reqUri =
        url, xml ? "xml" : "simple");

    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(reqUri);
    req.Timeout = 10000; // 10 seconds

    // if the function fails and format==txt throws an exception
    Stream stm = req.GetResponse().GetResponseStream();

    if (xml)
        XmlDocument doc = new XmlDocument();

        // error checking for xml
        if (doc["result"]["statusCode"].InnerText != "200")
            throw new WebException(doc["result"]["statusCode"].InnerText);

        return doc["result"]["shorturl"].InnerText;
    else // Text
        using (StreamReader reader = new StreamReader(stm))
            return reader.ReadLine();

Private Function Shorten(url As String, xml As Boolean) As String
	url = Uri.EscapeUriString(url)
	Dim reqUri As String = "{0}&format={1}"
	If (xml) Then
		reqUri = String.Format(reqUri, url, "xml")
		reqUri = String.Format(reqUri, url, "simple")
	End If

	Dim req As HttpWebRequest = DirectCast(WebRequest.Create(reqUri), HttpWebRequest)
	req.Timeout = 5000
	Dim stm As Stream = req.GetResponse().GetResponseStream()

	If xml Then
		Dim doc As New XmlDocument()

		' error checking for xml
		If doc("result")("statusCode").InnerText <> "200" Then
			Throw New WebException(doc("result")("statusCode").InnerText)
		End If

		Return doc("result")("shorturl").InnerText
		' Simple
		Using reader As New StreamReader(stm)
			Return reader.ReadLine()
		End Using
	End If
End Function

Notice that we have used the function System.Net.Uri.EscapeUriString() to eliminate unacceptable characters from the URL by encoding them.

Notice too that we have included our code in a Try-Catch block so we can catch exceptions before they blow up our application.

What’s next

Consider reading other articles in this series here.