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
markupparameter - 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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?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.
