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.
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 |
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]
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.
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. |
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. |
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 |
1 | Low |
---|---|
2 | Medium |
3 | High |