Explore the API

Current API version:
2.0 
Daily query limit:
100


The WikiRumours API allows authorized users to retrieve WikiRumours data asynchronously for use in their own applications. The API is a continual work in progress, so as new versions of the API become available, old versions will be retired (after a suitable transition period). If you notice that your API calls have stopped returning data, please check the returned status messages to ensure that your API URL hasn't become deprecated. Still having problems? Check our FAQs.

In general, sub-incremental versions are forwards-compatible (e.g. v1.2 will accept the same parameters as v1.1), but incremental versions will not (e.g. v2 will require different configuration than v1).

At this time, the WikiRumours API is read-only.

Accessing the WikiRumours API requires a private, unique, user-specific access key. You can obtain a key through your profile / account settings. Please keep this key secure (e.g. do not add it to browser-viewable code).

A query limit is enforced on the WikiRumours API to ensure appropriate access by all users. For special applications, please let us know.



Summary of Changes

  • Sightings query added

Input Parameters

The high-level schema for the WikiRumours API is as follows:

http://api.wikirumours.org/version/key/query-type/output/encoded-filters

URL Segment Format Options
version v{increment}-{sub-increment}
key {32-digit key}
query type {query type} rumours, sightings
output {output} xml; json; csv
(encoded) filters {key}%3D{value}%7C{key}%3D{value} (see filter table below)

Filters are key/value pairs which correspond to output parameters. So for instance, to retrieve all sightings of newly added Kenyan rumours, the filter segment would properly read country_id%3DKE%7Cstatus%3DNU.


Filter Applicable query Format Useful for
public_id rumours; sightings URL-encoded plaintext locating a specific rumour or sighting
keywords rumours; sightings URL-encoded plaintext locating several rumours or sightings for several rumours without having specific structured criteria
country_id rumours; sightings 2-character ISO 3166-2 code
status rumours; sightings See status codes
page rumours; sightings any integer paginating through a large result

Output Parameters

For illustrative purposes, output has been displayed below as XML.

[wikirumours]
  [version]VARCHAR(6)[/status]
  [status]TEXT[/status]
  [page]TINYINT(3)[/page]
  [number_of_results]INT[/number_of_results]
  [number_of_results_on_this_page]INT[/number_of_results_on_this_page]
  [warnings]
    [warning_code]INT(4)[/warning_code]
    [human_readable_warning]VARCHAR(255)[/human_readable_warning]
  [/warnings]
  [errors]
    [error_code]INT(4)[/error_code]
    [human_readable_error]VARCHAR(255)[/human_readable_error]
  [/errors]
  [number_of_queries_today]INT[/number_of_queries_today]
  [data]

    {data structure is dependent on requested query type}

  [/data]
[/wikirumours]

Rumour data is presented with this structure:

    [datapoint]
        [rumour_id]VARCHAR(6)[/rumour_id]
        [rumour]TEXT[/rumour]
        [country_abbreviation]CHAR(2)[/country_abbreviation]
        [country]VARCHAR(255)[/country]
        [region]VARCHAR(255)[/region]
        [latitude]DECIMAL(11,7)[/latitude]
        [longitude]DECIMAL(11,7)[/longitude]
        [occurred_on]DATETIME[/occurred_on]
        [status_abbreviation]CHAR(2)[/status_abbreviation]
        [status]VARCHAR(255)[/status]
        [findings]TEXT[/findings]
        [number_of_sightings]INT[/number_of_sightings]
    [/datapoint]

Sighting data is presented with this structure:

    [datapoint]
        [sighting_id]VARCHAR(6)[/sighting_id]
        [heard_on]DATETIME[/heard_on]
        [country_abbreviation]CHAR(2)[/country_abbreviation]
        [country]VARCHAR(255)[/country]
        [region]VARCHAR(255)[/region]
        [latitude]DECIMAL(11,7)[/latitude]
        [longitude]DECIMAL(11,7)[/longitude]
        [rumour]TEXT[/rumour]
        [occurred_on]DATETIME[/occurred_on]
        [status_abbreviation]CHAR(2)[/status_abbreviation]
        [status]VARCHAR(255)[/status]
        [findings]TEXT[/findings]
    [/datapoint]

Error Handling

Incorrectly configured input parameters will result in an error being returned with the data. If the proper output format parameter cannot be determined, the default output for error messages is XML.


This API version is now retired. Please upgrade to the latest API.

Warning codes

1 Approaching maximum daily queries.
2 No vocabulary was retrieved based on your input parameters.
3 No sightings were retrieved based on your input parameters.
4 This API version has been deprecated and will soon be retired. Please upgrade to the latest API.
5 Inappropriate filter for desired query.

Error codes

1 No valid filters found.
2 Missing API key.
3 Invalid API key.
4 Maximum daily queries already reached; the query limit resets every 24 hours.
5 Unable to determine a valid query type.
6 This API version is now retired. Please upgrade to the latest API.

Status codes

1 New / uninvestigated
2 Under investigation
3 Probably true
4 Probably false
5 Confirmed true
6 Confirmed false
7 Impossible to verify
8 Impossible to verify but probably true
9 Impossible to verify but probably false

Priority codes

1 Low
2 Medium
3 High