Welcome to The Twol API documentation

    All calls to the API go like this:

    http://twol.haykranen.nl/api/?format=FORMAT&long=true|false&q=query&callback=something

    Allowed formats are:
    * json (default)
    * php (php serialized)

    'long' can be either 'true' or 'false'. When set to false this only gives
    results of 140 characters or shorter (default).

    'callback' can be used to generate a 'padded JSON' (JSONP) result,
    for easy use in Javascript mashups. If you don't enter any value the results will simply enclosed within brackets. The parameter used to be 
    'jsoncallback', but this is deprecated (but will still work).

    'q' is the main query, you can test any query using the console on the main site.
    Note that all queries should be URL encoded, using the url encode method in
    your favourite programming language. For PHP this is urlencode(),
    for Javascript it's encodeURIComponent().

    For example, to request the weather in rome, using JSON as a response format:
    http://twol.haykranen.nl/api/?format=json&q=weather%20rome

    == Examples using different programming languages ==

    Here are some different ways you can use the API. We will query the API
    for the weather in Rome:

    http://twol.haykranen.nl/api/?format=json&q=weather%20rome

    @twol weather rome

    Did you write an API implementation in a language not mentioned on this page?
    Please mail me your code or a link and i'll add it to this page.

    === PHP ===
    For PHP it is recommended to download the free and open source TwolAPIRequest class.
    Using this class you can write the example like this:

    require 'class-twol-api-request.php';
    $r = new TwolAPIRequest('weather rome');
    if($r->hasError()) {
        echo 'There was an error with this request: ' . $r->getMessage();
    } else {
        // Request succesful:
        echo $r->getMessage();
    }

    Download this example

    === Javascript ===
    You can use an extra 'callback' (previous: 'jsoncallback') parameter to get a 'padded JSON' (JSONP)
    response, to get around the infamous cross-domain problems of browsers.

    This example uses the popular jQuery Javascript library for the example,
    to make it a little easier to do AJAX requests.
    
    var url = 'http://localhost/twol/api?format=json&callback=';
    url += '&q=' + encodeURIComponent('weather rome');
    $.getJSON(url, function(data) {
        if (data.result) {                    
            alert(data.result);
        } else if (data.error) {
            alert('Error: ' + data.error);
        } else {
            alert("Unknown error, maybe you don't have an internet connection?");
        }
    });

    Download this example