dotMobimobiThinkingmobiForgemobiReadyDeviceAtlasgoMobi
background image

Getting started with the ready.mobi API

Section Feature Image
Posted by ruadhan - 19 Mar 2009
Twitter share icon Facebook share icon Google Plus share icon

Note: We are not currently issuing new keys for the ready.mobi API

Ready.mobi is a well known page testing tool offered by dotMobi. When you supply a page URL to ready.mobi, it evaluates how well the page is likely to display on mobile devices by testing against the Mobile Web Best Practices, and dotMobi compliance rules.

The ready.mobi page checker also has a simple web service API. The API allows you to run mobile-readiness tests on your webpages without having to use the standard ready.mobi web interface. Upon request for a page test, the ready.mobi API will return its results as an XML document. The API thus facilitates programmatic use of the ready.mobi service. The possibilities are endless...!

Before you start

Before you get started with the API, you need to get an API key (it's free!). Send us an email at ready.tech@mtld.mobi. Note that the API is still in beta, and that access to the API is limited by a quota system - i.e. your key is good for only so many requests per minute, per hour, per day, per month, so it is important to throttle your requests. This is easily done by adding a suitable delay to your code between requests.

Using the API

The URL at which the API can be accessed is: http://api.ready.mobi. To use the API, an HTTP GET request should be made to this URL, with query parameters as outlined in the next section.

An API key, provided by dotMobi, must be provided in the request. This key will be used by ready.mobi to identify who is making an API request. It also facilitates the tracking of the number of API requests over a specified period of time. Should requests be made too frequently, then an HTTP 403 (Forbidden) response code will be sent to the client. The client should not make another request until a suitable time has elapsed.
Example usage: http://api.ready.mobi/?uri=mtld.mobi&key=MY_KEY

Parameters

The following parameters can be sent with requests to the web API:

  • key (required): Your API key
  • url (optional): The URL of the page to be tested. If you omit this parameter, then you should instead supply the markup parameter
  • ua (optional): The user agent string that ready.mobi will send when it makes its request for a page. If this parameter is not supplied, then the ready.mobi default UA string will be used
  • accept (optional): The accept header that ready.mobi will send when it makes its request for a page. If this parameter is not supplied, then the ready.mobi default Accept header will be used
  • acceptCharset (optional): The AcceptCharset header that ready.mobi will send when it makes its request for a page. If this parameter is not supplied then the ready.mobi default AcceptCharset header will be used
  • markup (optional): Markup that you would like ready.mobi to test. See below.

Arbitrary headers

It is also possible to have ready.mobi send arbitrary headers, specified by you, along with its page requests. To do this, simply prefix the name of the header to send with the string 'hdr_' and append the header name and value pair to the API request. For example to send a header called 'foo' with a value of 'bar' you would request the following URL:
http://api.ready.mobi/?uri=mtld.mobi&key=MY_KEY&hdr_foo=bar

Posting markup directly

The ready.mobi API also supports direct posting of markup for testing. This requires that you submit an HTTP POST request, with the markup to be tested sent in the markup parameter. This is intended to facilitate page testing during the development cycle or other situations where the page is not live on a publicly accessible URL.

Note that if you test markup by posting directly to ready.mobi not all of the tests can be performed. This is because some of the tests depend on factors external to the markup. For instance, some of the tests depend on HTTP headers sent with a page, while others require access to resources referenced within the markup, and so on. Because ready.mobi does not perform all the tests when markup is posted directly, a standard ready.mobi score between 1 and 5 is NOT assigned to the results. Instead, a percentage is given which takes account of the tests which were actually performed and passed.

403 is not a bug!

As mentioned earlier, if you make too many requests to the API (currently set at 6 per minute), or if your key is not valid, you will receive an HTTP 403 forbidden response. To the uninitiated, this might look like a bug, but it isn't! If you receive a 403 response, you should wait a suitable amount of time, and then make your API request again. If you always get this response, you should check that you have a valid key.

Code Samples

We now give some basic code examples to demonstrate how the API can be used programmatically. Code samples are given in Java and PHP. Sample XML output and the XML schema are also available for download below.

Java

In this example we make a request for a page test, and extract the overallScore element from the XML results
String testUrl = API_URL+"?uri="+url+"&key="+MY_KEY;	
 
Document doc = null;
try {
  //Parse XML 
  doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(testUrl);
 
  Element root = doc.getDocumentElement();
 
  //Obtain ready.mobi score
  NodeList nl = root.getElementsByTagName("overallScore");
 
  for(int i=0;i<nl.getLength();i++) {
    Node n = nl.item(i);
    if((n.getNodeType()==Node.ELEMENT_NODE) && (((Element)n).getTagName().equals("overallScore"))) {
      //Get text node child which contains the score
      Node child = n.getChildNodes().item(0);
      do {
        if(child.getNodeType()==Node.TEXT_NODE) return child.getNodeValue();
      } while(child!=null);
    }
  }
 
} catch(Exception e) {
  System.out.println("Error parsing XML document: "+e);
}

PHP

This requests a page test, and parses the score from the XML results:
<?php 
  $api_url  = 'http://api.ready.mobi/?url=http://mtld.mobi&key=MY_KEY';
 
  $doc = new DOMDocument();
  $doc->load($api_url);
 
  $elements = $doc->getElementsByTagName( "testResults" );
  $elm_overall_score = $elements->item(0)->getElementsByTagName("overallScore");
  $score = $elm_overall_score->item(0)->nodeValue;
  print "Score: " . $score;
 
?>
Download the full code listings below.
AttachmentSize
sample_java.zip1.45 KB
sample_php.zip347 bytes
sample_xml_results.zip7.38 KB
schema.zip1.18 KB

Posted by ruadhan - 19 Mar 2009

Posted by pboese 5 years ago

Cheers! That's awesome. But what do you mean by "Should requests be made too frequently"? What is too frequently? How many checks can I run per hour or day? I'd love to check all our portals and those of our customers like http://www.schneehoehe.mobi/ on a frequently base every day.

http://www.gjuce.com/

Posted by MRLacey 5 years ago

I'd like to know what the frequency permission is also (should I get an API key).
Surely a typical use case will involve lots of tests in a short period of time when a site is first developed, then occasional periods of lots of checks being made in a short time when changes are made to a site.

Posted by ruadhan 5 years ago

Right now, we allow 6 page tests per minute using the API, which we think should be enough for most applications. If you go over this you will get an HTTP 403 Forbidden response. But just a reminder that it the service is still in beta, so the limits could be subject to change.

Ruadhan O'Donoghue
Editor, mobiForge

Posted by MRLacey 5 years ago

Yes, that sounds like plenty.

Posted by davoli 5 years ago

Posting markup directly - Great!!!

Posted by inSyt 5 years ago

hey i would like to create a form for my site www.insyt.co.cc where users can enter a url and check it's score. Is this possilble and if yes how?

www.insyt.co.cc