![Figure 5 - Add Web Reference Dialog in .NET 2.0]( "Add Web Reference Dialog - Web")
Another approach to get the required source files for the service is to use the svcutil.exe tool that's used internally by Visual Studio. This is a command tool that generates source files for web and WCF services. You can use this tool as follows:
svcutil.exe http://api.x.co/Squeeze.svc?wsdl /language=C#
svcutil.exe http://api.x.co/Squeeze.svc?wsdl /language=VB
Notice that we have included the address of the discovery (description) WSDL data of the services so that the tool can read it. Remember to select your language in the command.
Squeeze Service
The first function we have today and the only function of the Squeeze service (http://api.x.co/Squeeze.svc) is the Shorten() function that's used to shorten long URL files. This function simply accepts 2 arguments:
- url:
The long URL to be shortened.
- apiKey:
The API key used to authenticate the call.
There're other functions existing in the Squeeze service but they are either deprecated or reserved for internal use by Go Daddy.
After you ensure that a reference of the service is added to your project (check the previous section) you can start writing your code. The following function accepts the long URL and returned the shortened one that's -at the time of this writing- is no more than 16 characters (e.g. http://x.co/8Gg8):
// C#
string Shorten(string url, string apiKey)
{
using (xcoapi.Squeeze sq = new xcoapi.Squeeze())
{
return sq.Shorten(url, apiKey);
}
}
Notice that web services consumes lots of system resources and you should release them as soon as you finish you work with them, that's why we have used the C# using statement.
Reporting Service
The other service we have is the Reporting service (http://api.x.co/Reporting.svc) that offers you great deal of analytics and reporting functionalities that can be sorted in 3 areas:
- Click count (the number of uses of the short URL)
- Referrer sites (for the short URL)
- Uses by locations (city, region, and country.)
This service supports 5 functions:
- GetTotalMapClick():
Returns total clicks (uses) of a short URLs.
- GetMapClicksByDates():
Returns clicks of a short URL made within a given time period grouped by days.
- GetMapClicksByHour():
Returns clicks of a short URL made today grouped by hours.
- GetMapReferrersByDates():
Returns referrer links made to the short URL within a given time period grouped by days.
- GetMapLocationsByDates():
Returns clicks of a short URL made within a given time period grouped by geographic location.
Those five functions are very similar in many ways. First, they all accept two required parameters:
In addition, the last four functions work the same way. They all return arrays of objects. GetMapClicksByHour() for instance returns the number of clicks made today grouped by hours each hour is represented by an object that contain the hour number besides the clicks made in that hour, and all objects are grouped inside one array.
The other functions GetMapClicksByDates(), GetMapReferrersByDates(), and GetMapLocationsByDates() work the same way and accept the same parameters except that they accept four additional parameters represent the begin and the end dates of the time period and whether the date parameters were set or leaved empty.
How can the four parameters help? You can define both and set the two flags to indicate that we need a specific time period. You can also set one of them and set its flag to indicate that you need to start from a specific day and get analytics till now. Notice that you can't leave both empty.
The following code returns the total number of clicks for a specific short URL:
// C#
int GetTotalClicks(string shortCode, string apiKey)
{ using (xcoapirpt.ReportingClient rpt = new xcoapirpt.ReportingClient())
{ return rep.GetTotalMapClick(apiKey, shortCode);
}
}
And the following code is the same as the above except that it uses .NET 2.0:
// C#
int GetTotalClicks(string shortCode, string apiKey)
{ using (xcoapirpt.Reporting rpt = new xcoapirpt.Reporting())
{ int totalClicks;
bool succeeded;
rep.GetTotalMapClick(apiKey, shortCode, out totalClicks, out succeeded);
return succeeded ? totalClicks : -1;
}
}
Notice the slight difference between the two calls (in .NET 2.0 and higher versions.) In .NET 2.0, the returned value is specified as an output parameter.
The following code is somewhat complex than the previous. The following code returns the refer links for our short URL:
// C#
xcoapirpt.ReferrerEventInfo[] GetReferrers
(string shortUrl, string apiKey, out int totalClicks)
{ using (xcoapirpt.Reporting rep = new xcoapirpt.Reporting())
{ xcoapirpt.ReferrerEventInfo[] results =
rep.GetMapReferrersByDates(apiKey, shortUrl,
DateTime.Now - new TimeSpan(7, 0, 0, 0, 0), true, DateTime.Now, true);
totalClicks = 0;
foreach (xcoapirpt.ReferrerEventInfo r in results)
totalClicks += r.TotalSpecified ? r.Total : 0;
return results;
}
}
Notice how we specify the start and end date parameters and their flags to get only the last week analytics. Notice also the type of the array returned from the function and how we used it to get the required information.
RESTful Services
If you prefer not to use the WCF services, you can start with the REST interface provided to you by the kind-hearted WCF services. A RESTful service is simply a group of related web functions that has specific formats; some of return plaint text, some return XML data, and others return JSON.
Keep in mind that WCF services are supported natively by .NET framework and thus they are faster and easier to work with.
Squeeze Service
Not surprisingly, our RESTful Squeeze service is provided to us by the address http://api.x.co/Squeeze.svc. This service has two functions to shorten URLs, one is JSON, and the other is plain text.
The first function that returns plain text can be called using the following address:
http://api.x.co/Squeeze.svc/text/{apiKey}?url={url}
Now you have the address and ready with the input, the following function calls the previous function to shorten long URLs:
// C#
string Shorten(string url, string apiKey)
{ WebRequest req = HttpWebRequest.Create(
string.Format("http://api.x.co/Squeeze.svc/text/{0}?url={1}", apiKey, url));
req.Timeout = 10000; // 10 seconds
string shortUrl;
System.IO.Stream stm;
stm = req.GetResponse().GetResponseStream();
using (System.IO.StreamReader rdr = new System.IO.StreamReader(stm))
{ return rdr.ReadToEnd();
}
}
Reporting Service
Likewise, the Reporting service has the following address: http://api.x.co/Squeeze.svc. This service provides you with many functions like its WCF counterpart, however, all of them are JSON expect one is plain text. Because JSON is not natively supported by .NET Framework and thus requires the use of other 3rd party components (e.g. Json.NET) we won't consider those endpoints. However, we have our total clicks function that returns plain text:
// C#
int GetTotalClicks(string shortCode, string apiKey)
{ WebRequest req = HttpWebRequest.Create(
string.Format("http://x.co/Reporting.svc/map/{0}/{1}/total", apiKey, shortCode));
req.Timeout = 10000; // 10 seconds
System.IO.Stream stm;
stm = req.GetResponse().GetResponseStream();
using (System.IO.StreamReader rdr = new System.IO.StreamReader(stm))
{ return int.Parse(rdr.ReadToEnd());
}
}
Again, the short code is the only required piece of the short URL, you do not need to include the http://x.co/ (actually, you can't!)
Source Code
Download the source code files from
here.
What's next
Consider reading more about URL shortening services here.