XooMLe Developer Docs

There’s not really that much to put here, so I decided to do it all in one page, plus link to the Google documentation, which is reproduced here exactly as received in the developer download from Google (Google-people, please email me and I will remove this immediately if it is against my usage agreement!)

Contents

Fundamentals

Basically, to use XooMLe you just need to “request” a webpage, then do something with the result that gets sent back to you. Some people might call this a request-response architecture, whatever – you ask XooMLe for something, it asks Google for the same thing, then formats the results in a certain format and gives it to you, from there on, you can do what you like with it.

Fancy System Diagram

To aid you in the visualization of this extremely complex system, I have developed a fancy system-diagram. (WARNING: This link goes to amateur, uber-UML!)

Methods Available

Long story short – everything you can ask the Google SOAP API, you can ask XooMLe, if you have no idea what I am talking about, consult the table below ๐Ÿ™‚

Here’s what you can ask XooMLe, and what it’ll tell you;

Google Method: doGoogleSearch

  • XooMLe URI: http://xoomle.beaulebens.com/search/
  • Successful Response Format: Returns an XML-formatted response containing the results of the Google-search that you specified, looking somewhat like this (XooMLe is currently using this XML template for results)
  • Failure Response: An XML-based error message, including all arguments you sent to XooMLe (like so). The message will change, depending on what went wrong, as outlined below.
  • Extra Features
    • maxResults: Also supports setting maxResults well above the Google-limit of 10, performing looped queries to gather the results and then sending them all back in one hit.
    • cachedVersion: Each result item will include an element called “cachedVersion” which is a URI to retrieve the cached version of that particular result.
    • xsl: You may specify a variable called “xsl” in addition to the others in the querystring. The value of this variable will be used as a reference to an external XSLT Stylesheet, and will be used to format the XML output of the document.
    • relatedInformation: If it is detected that there is related information available for a particular resultElement, then this element will contain a link to retrieve those related items from XooMLe.
    • xlink: There is now an xlink attribute added to the cachedVersion and relatedInformation elements of each result.

Google Method: doSpellingSuggestion

  • XooMLe URI: http://xoomle.beaulebens.com/spell/
  • Successful Response Format: Returns a text-only response containing the suggested correction for the phrase that you passed to Google (through XooMLe). You will get HTTP headers and stuff like that as well, but assuming you are accessing XooMLe over HTTP in the first place, the body of the response is just text.
  • Failure Response: An XML-based error message, including all arguments you sent to XooMLe (like so).

    • The message will change, depending on what went wrong, as outlined below.

Google Method: doGetCachedPage

  • XooMLe URI: http://xoomle.beaulebens.com/cache/
  • Successful Response Format: Returns the complete contents of the cached page requested, WITHOUT THE GOOGLE INFORMATION-HEADER. The header that Google adds which says it’s a cached page, etc etc is stripped out BEFORE you are given the page, so don’t expect it to be there, you should get nothing but the HTML required to render the page.
  • Failure Response: An XML-based error message, including all arguments you sent to XooMLe (like so).

    • The message will change, depending on what went wrong, as outlined below.

Asking XooMLe Something (Forming Requests)

Asking XooMLe something is really easy, you can do it in a normal hyperlink, a bookmark, a Favorite, whatever. A request to XooMLe exists as a URL, which contains some special information, it looks something like this;

http://xoomle.beaulebens.com/search/?key=YourGoogleDeveloperKey&q=dented+reality

If you have no idea what a querystring is, then here’s a quick intro;

The querystring is the portion of the address, after a “?” containing a series of paired variables in key=value format. Thus you can take;

this = that
theWeb = prettyCool
microsoft = prettyNot (and)
google = wikkid

and combine them into a querystring which would look something like this;

this=that&theWeb=prettyCool&microsoft=prettyNot&google=wikkid

Now if you stick that on the end of an address (ie. XooMLe’s address) then it tells that page some things, in this case what you would like it to do, and how you would like the results to be formatted.

http://address.com/?this=that&theWeb=prettyCool&microsoft=prettyNot&google=wikkid

Now, enough of generic examples, if you are talking to XooMLe, the address you need is;

http://xoomle.beaulebens.com/<method keyword>/

and so your requests might look something like the example above, or they might be fully-specc’d out like this one (split into lines for layout purposes only;

http://xoomle.beaulebens.com/search/
?key=YourKey
&q=dented+realty
&maxResults=1
&start=0
&hl=en
&ie=ISO-8859-1
&filter=0
&restrict=countryAU
&safeSearch=1
&lr=en
&ie=latin1
&oe=latin1
&xsl=myxsl.xsl

All of the available parameters are defined in the Google documentation, but please remember;

Another thing you might like to know – XooMLe makes use of some fancy looping to allow you to request more than the allowed 10 results in one request. If you ask XooMLe to get (for example) 300 results, then it will perform multiple queries to Google and send back 300 results to you in XML-format. Keep in mind that this still uses up your request limit (1000 queries per day) in blocks of 10 though, so in this case, you’d drop 30 queries in one hit (and it would take a while to return that many results as well).

Error Messages

If you do something wrong, XooMLe will tell you in a nice, tasty little XML-package. The errors all look something like this, but they have a different error message, and contain that “arguments” array which includes everything you asked it. Below are all the error messages that you can get, and why you will get them.

Google API key not supplied
You forgot to tell XooMLe your Google API key. You need this so that XooMLe can communicate with Google on your behalf. Specify it like this: “key=YourKeyHere” and get one from here if you don’t have one already.
Search string not specified
You were smart enough to specify that you wanted to do a search (using “search” as your method keyword) but forgot to tell XooMLe what you were searching for. Fix this by adding something like “q=Your+search+terms” (your search phrase should be URL-encoded and is subject to the same limitations as the Google API).
Invalid Google API key supplied
There’s something wrong with your Google API key (did you URL-encode it like I told you?).
Your search found no results
It’s not rocket science…
Phrase not specified
If you are going to ask for a spelling suggestion (using “spell” as your method keyword) then you should also tell XooMLe what you are trying to correct, using “phrase=stoopid+speling+here&quot. (URL-encode it)
No suggestion available
Hey, Google ain’t perfect, sometimes the attempts at spelling just don’t even warrant a response (or rather Google can’t decipher your bad spelling)
URL not specified
You want a cached page from Google? The least you could do is ask for it using “url=http://thepagehere.com”
Cached page not available
Something was wrong with the cached page that Google returned (or it couldn’t find it in it’s database).
Couldn’t contact Google server
There was a problem contacting the Google server so your request could not be processed.

Disclaimers etc.

I have shamelessly ripped these disclaimers directly from Dave Winer’s Radio UserLand website (XML-RPC Gateway to the Google API) and changed the names to protect the innocent (but potentially guilty :P)

  1. Dented Reality is providing this gateway for experimental purposes only.
  2. Use of the XooMLe is subject to the terms of use of the Google API.
  3. Dented Reality may terminate this interface at any time without notice.
  4. I may or may not upgrade this interface if Google changes theirs.
  5. If Google asks me to turn this off, I will do it, quickly.