The Wordtracker system can be accessed via XML-RPC.
The Wordtracker Web Service provided at xmlrpc.wordtracker.com has a dummied version at test.xmlrpc.wordtracker.com which allows you to play with the interface without having an account.
Each procedure in the API requires an access key. In the dummy server the access key is always "guest". All the results for the dummy version are fixed, although some parameters (eg the access key) are checked.
In order to connect to the XML-RPC API, you will need an XML-RPC client. For the examples below we use the one at http://www.xml-rpc.net/. The version used here is v0.8.1. Add a reference to the CookComputing.XmlRpc.dll in your C# project (Windows project or ASP.net project).
To get up and running quickly, create a new code file in your project, for the web service interface as follows:
using System;
using CookComputing.XmlRpc;
[XmlRpcUrl("http://test.xmlrpc.wordtracker.com")]
interface IWordTracker
{
[XmlRpcMethod("ping")]
bool ping(string key);
}
This file defines the input and response types for each of the available web service methods. In the page where you want to call the web service, add the following 'Using' directive:
using CookComputing.XmlRpc;
and add the following code to the Page_Load event:
IWordTracker WordTracker = (IWordTracker)XmlRpcProxyGen.Create(typeof(IWordTracker));
try {
if (WordTracker.ping("guest")) {
Response.Write("Successfully pinged guest account.");
}
} catch (Exception Ex) {
Response.Write(Ex.Message);
}
This should produce the output...
Successfully pinged guest account.
The first thing this code does is create a client pointing at the dummy version of the service. Ping is a special procedure that confirms that your account is active. Here, because we are using the guest account, it will always return success if the access key used is "guest". For the Cookcomputing XML-RPC client, we pass the access key parameter as described in the interface we set up (IWordTracker) in our separate code file.
In practice there are several things that can go wrong.
The Cookcomputing XML-RPC client Exceptions are mapped onto .NET exceptions and the error messages can easily be analyzed. The general exception type is XmlRpcException but you can use more specific Exception types such as XmlRpcTypeMismatchException or XmlRpcFaultException to handle certain errors.
For example:
try {
...
} catch(XmlRpcFaultException fex) {
Response.Write("Fault Response: " + fex.FaultCode + " " + fex.FaultString);
}
For further information on error handling with the XML-RPC.NET client, please check out http://www.xml-rpc.net/faq/xmlrpcnetfaq.html
We are now ready to tackle a more useful procedure...
A typical call to Wordtracker is to find the search popularity of a selection of keyphrases. This is achieved with one of get_exact_phrase_popularity, get_embedded_phrase_popularity and get_all_words_popularity. The simplest is get_exact_phrase_popularity, which will search the database for phrases which people have typed into metacrawlers. They can be retrieved exactly with get_exact_phrase_popularity.
The following example uses the dummy version of get_exact_phrase_popularity to demonstrate the general approach. First, we need to add the definition of the function we're going to call (get_exact_phrase_popularity) to our interface IWordTracker.
What is important in our interface, is the way you map the data types that are required by the WordTracker web service, to a data type that is recognized by C#. The return parameter can be cast to the data type 'XmlRpcStruct ', which is effectively a Hashtable, and can be accessed as such. Simple return values like bool or int do not need conversion. If the data types are incorrectly defined, an InvalidCastException is likely to occur.
So now our interface looks like this...
[XmlRpcUrl("http://test.xmlrpc.wordtracker.com")]
interface IWordTracker
{
[XmlRpcMethod("ping")]
bool ping(string key);
[XmlRpcMethod("get_exact_phrase_popularity")]
XmlRpcStruct get_exact_phrase_popularity(
string id,
string[] key phrases,
string Case,
bool include_misspellings,
bool include_plurals,
string adult,
int max,
int timeout);
}
...and we can call the function get_exact_phrase_popularity by using the following code...
IWordTracker WordTracker = (IWordTracker)XmlRpcProxyGen.Create(typeof(IWordTracker));
string [] keyWordArray = {"mp3", "britney spears"};
XmlRpcStruct mystruct;
try {
mystruct = WordTracker.get_exact_phrase_popularity(
"guest",
keyWordArray,
"case_folded",
false,
true,
"exclude_adult",
100,
10);
foreach (DictionaryEntry d in mystruct) {
Response.Write (d.Key + " : " + d.Value);
}
} catch(XmlRpcFaultException fex) {
Response.Write("Fault Response: " + fex.FaultCode + " " + fex.FaultString);
} catch (Exception Ex) {
Response.Write (Ex.Message);
}
We create the client as before, but this time we need to pass in rather more parameters.
The dummy version of the Wordtracker API does actually perform some basic parameter checks. The only valid value for the case parameter "case_folded". For anything else a XmlRpcException is returned. Similarly, the adult parameter must be one of "adult_only", "include_adult", and "exclude_adult".
The dummy version of the interface is simplistic in that it returns a count of 999 for each phrase queried. As an aside, although this dummied procedure returns a single result for each keyphrase, we will see that the real system could produce multiple results.
When run, the sample should output...
mp3 = 999
britney spears = 999
The above examples have all used a stubbed version of the web services. Once you have a Wordtracker web services account you will be sent an access key. This will allow you to run the following sample against the live server.
Before you can access the live server, you need to modify the Interface file, so that the interface points to the live URL. So change the first line in the interface from...
[XmlRpcUrl("http://test.xmlrpc.wordtracker.com")]...to...
[XmlRpcUrl("http://xmlrpc.wordtracker.com")]Alternatively, you can simply create a new interface and keep the old one for when you want to connect to the test server. The following sample will now return live results...
IWordTracker WordTracker = (IWordTracker)XmlRpcProxyGen.Create(typeof(IWordTracker));
string [] keyWordArray = {"mp3", "britney spears"};
XmlRpcStruct mystruct;
try {
mystruct = WordTracker.get_exact_phrase_popularity(
"guest", //Replace with your own access key
keyWordArray,
"case_folded",
false,
true,
"exclude_adult",
100,
10);
foreach (DictionaryEntry d in mystruct) {
Response.Write (d.Key + " : " + d.Value);
}
} catch(XmlRpcFaultException fex) {
Response.Write("Fault Response: " + fex.FaultCode + " " + fex.FaultString);
} catch (XmlRpcException Ex) {
Response.Write (Ex.Message);
}
The first thing we do to rework the stub example is change the URL to the live server at http://xmlrpc.wordtracker.com/. The string "guest" in the above code must be changed to your actual access key. You must have access to the get_exact_phrase_popularity procedure from your account to be able to run this example, if not you will have to experiment with one that you do have.
The XML-RPC spec specifies that the struct type is unordered. If you want ordered results, you will have to sort the components yourself.
Here, we simply print them on separate lines...
mp3 = 16734
britney spears = 14245
Britney Spears = 4100
MP3 = 2040
mp3s = 1263
Mp3s = 574
Mp3 = 556
Britney spears = 330
BRITNEY SPEARS = 276
MP3s = 90
britney Spears = 50
MP3S = 12
Britney SPears = 11
mP3 = 6
bRITNEY sPEARS = 6
BRITNEY Spears = 4
britney Spearss = 2
britney spearss = 2
BRitney SPears = 2
BRitney spears = 2
That's it, you're done.