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://ws.apache.org/xmlrpc/. The version used here is v1.2-b1 dated 24 September 2003. Place the xmlrpc-1.2-b1.jar in your classpath.
To get up and running quickly, create the file CrudePing.java as follows:
import org.apache.xmlrpc.XmlRpcClient;
import java.util.Vector;
public class CrudePing {
public static void main( String args[] ) throws Exception {
XmlRpcClient client = new XmlRpcClient( "http://test.xmlrpc.wordtracker.com/" );
Vector params = new Vector();
params.addElement( "guest" );
Object result = client.execute( "ping", params );
if ( result != null )
System.out.println( "Successfully pinged guest account." );
}
}
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. Then we set up a Vector to hold the parameters to the procedure to be called, in this case "ping". 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 Apache XML-RPC client, we pass the access key parameter as part of a Vector.
In practice there are several things that can go wrong.
If you receive the compile error
package org.apache.xmlrpc does not exist
this is most likely due to the jar file not being in your classpath. Another possibility is that permissions are not set to allow the compiler to read the jar file. Note: The unpacked file has a very restrictive set of permissions. If you are using Unix, you will have to...
chmod 644 xmlrpc-1.2-b1.jar
...to allow it to function correctly.
If you receive a server error...
java.lang.NoClassDefFoundError: org/apache/xmlrpc/XmlRpcClient
...when running the sample, this will be because the JVM cannot find the jar file. Again, check your class path.
CrudePing wouldn't win any prizes for safety. Here is a version which attempts to report all possible errors, some more likely than others.
import org.apache.xmlrpc.XmlRpcClient;
import org.apache.xmlrpc.XmlRpcException;
import java.util.Vector;
import java.io.IOException;
import java.net.MalformedURLException;
public class Ping {
public static void main( String args[] ) {
XmlRpcClient client;
try {
client = new XmlRpcClient( "http://test.xmlrpc.wordtracker.com/" );
}
catch ( MalformedURLException ex ) {
System.out.println( "You have mangled the URL." );
return;
}
Vector params = new Vector();
params.addElement( "guest" );
Object result = null;
try {
result = client.execute( "ping", params );
}
catch ( IOException ex ) {
System.out.println( "Network error: The server may not exist." );
return;
}
catch ( XmlRpcException ex ) {
System.out.println( "Procedure returned error message: '" + ex.getMessage() + "'." );
return;
}
if ( result == null ) {
System.out.println( "The server didn't return XML." );
return;
}
if ( ! (result instanceof Boolean) ) {
System.out.println( "The procedure didn't return a boolean." );
return;
}
if ( ((Boolean) result) != Boolean.TRUE ) {
System.out.println( "This should never happen." );
return;
}
System.out.println( "Successfully pinged guest account." );
}
}
The most likely problem is that the URL does not point to a valid host. If this happens, the client library will raise an IOException.
A less likely problem is that it is a valid host, but not an XML-RPC server. This will cause the return from XmlRpcClient to be null.
If you get an XmlRpcException, this can be due to using an access key other than "guest", or attempting to connect to the live server.
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. It omits error checking to reduce clutter.
import org.apache.xmlrpc.XmlRpcClient;
import org.apache.xmlrpc.XmlRpcException;
import java.util.Vector;
public class GetDummyExactPhrasePopularity {
public static void main( String args[] ) throws Exception {
XmlRpcClient client = new XmlRpcClient( "http://test.xmlrpc.wordtracker.com/" );
// keyphrases parameter
Vector keyphrases = new Vector();
keyphrases.add( "mp3" );
keyphrases.add( "britney spears" );
// start building the parameter list
Vector params = new Vector();
// access key parameter
params.add( "guest" );
params.add( keyphrases );
// case parameter
params.add( "case_distinct" );
// include_misspellings parameter
params.add( Boolean.FALSE );
// include_plurals parameter
params.add( Boolean.TRUE );
// adult parameter
params.add( "exclude_adult" );
// max parameter
params.add( new Integer(100) );
// timeout parameter
params.add( new Integer(10) );
try {
Object result = client.execute( "get_exact_phrase_popularity", params );
System.out.println( result );
}
catch ( XmlRpcException ex ) {
System.out.println( "Procedure returned error message: '" + ex.getMessage() + "'." );
return;
}
}
}
We create the client as before, but this time we need to pass in rather more parameters. Note how the array of keyphrases is encoded as a Vector.
The dummy version of the Wordtracker API does actually perform some basic parameter checks. If the case parameter is not one of the Strings "case_distinct", "case_folded", or "case_sensitive", 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.
import org.apache.xmlrpc.XmlRpcClient;
import org.apache.xmlrpc.XmlRpcException;
import java.util.*;
public class GetExactPhrasePopularity {
public static void main( String args[] ) throws Exception {
XmlRpcClient client = new XmlRpcClient( "http://xmlrpc.wordtracker.com/" );
Vector keyphrases = new Vector();
keyphrases.add( "mp3" );
keyphrases.add( "britney spears" );
Vector params = new Vector();
params.add( "guest" ); // edit this line
params.add( keyphrases );
params.add( "case_distinct" );
params.add( Boolean.FALSE );
params.add( Boolean.TRUE );
params.add( "exclude_adult" );
params.add( new Integer(100) );
params.add( new Integer(10) );
Object untypedResult;
try {
untypedResult = client.execute( "get_exact_phrase_popularity", params );
}
catch ( XmlRpcException ex ) {
System.out.println( "Procedure returned error message: '" + ex.getMessage() + "'." );
return;
}
if (! (untypedResult instanceof Hashtable)) {
System.out.println( "Expected return of type Hashtable,
but got " + untypedResult.getClass());
return;
}
Hashtable result = (Hashtable) untypedResult;
Enumeration en = result.keys();
while (en.hasMoreElements()) {
String key = (String) en.nextElement();
Integer popularity = (Integer) result.get( key );
System.out.println( key + " = " + popularity );
}
}
}
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.
This example demonstrates how to unpack an XML-RPC struct returned from a call into its components. Here is the output.
BRITNEY SPEARS = 264
mp3s = 1270
BRitney spears = 2
Britney Spears = 4076
MP3S = 12
Mp3s = 575
mp3 = 17126
britney spearss = 2
mP3 = 6
BRITNEY Spears = 4
Britney SPears = 15
Mp3 = 572
MP3s = 85
bRITNEY sPEARS = 7
MP3 = 2098
Britney spears = 329
britney Spears = 52
BRitney SPears = 2
britney spears = 13470
britney Spearss = 2
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.