Table of Contents
Introduction
This is a documentation for the Ushahidi Application Programming Interface(API). It serves as a reference for developers building tools to interact with the Ushahidi engine.
The Ushahidi API try to conform to Representational State Transfer (REST) design principles. As it is now, it supports XML and the JSON data exchange formats. In a few cases, it supports KML. We are working hard to support the other formats too.
HTTP Requests
The Ushahidi API uses the GET method for retrieving data from the engine. To submit, modify or delete data, the POST method is used.
Status messages and their Codes
Note that Error messages are returned in the two data formats. XML and the JSON.
What shows depends on the value you pass to the resp parameter.
| Code | Status Message |
|---|---|
| 0 | No Error: Everything went successful. |
| 001 | Missing Parameter: When a required parameter is not supplied. |
| 002 | Invalid Parameter: when an incorrect parameter is supplied. |
| 003 | Form Post Failed: when all the required parameters for the post method is not supplied and not in the right data type or invalid. |
| 005 | Access denied. Either your credentials are not valid or your request has been refused. |
| 006 | Access denied. Your request has been understood, but denied due to access limits like time. |
| 999 | Not Found: when a wrong task is provided as a parameter. |
GET Methods
The various methods accessed via the HTTP GET method are:
| API KEYS | apikeys | Retrieves the various map api keys, google, yahoo and microsoft maps. |
|---|---|---|
| URL | http://<somedomain.com>/api?task=apikeys | |
| Formats | XML, JSON | |
| Parameters | by - Required. The map service api key. google or yahoo or microsoft. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used |
|
| Example | http://<somedomain>/api?task=apikeys&by=google&resp=xml | |
| Returns | an api key | |
| CATEGORIES | categories | Retrieves all categories in ascending order. |
| URL | http://<somedomain.com>/api?task=categories | |
| Formats | XML, JSON | |
| Parameters | resp - the data exchange, either XML or JSON | |
| Example | ||
| Returns | all categories Ushahidi supports. | |
| category | Retrieves category by id. | |
| URL | http://<somedomain>/api?task=categories&by=id | |
| Formats | XML, JSON | |
| Parameters | id - Required. Category id. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used |
|
| Example | http://<somedomain>/api?task=categories&by=id&id=1&resp=xml http://<somedomain>/api?task=categories&by=id&id=1&resp=json |
|
| Returns | a category. | |
| COUNTRIES | countries | Retrieves all the countries Ushahidi supports. |
| URL | http://<somedomain>/api?task=countries | |
| Formats | XML, JSON | |
| Parameters | resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used | |
| Example | http://<somedomain>/api?task=countries&resp=xml http://<somedomain>/api?task=countries&resp=json |
|
| Returns | all countries | |
| country | Retrieves all the countries Ushahidi supports. | |
| URL | http://<somedomain>/api?task=countries | |
| Formats | XML, JSON | |
| Parameters | resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. | |
| Example | http://<somedomain>/api?task=countries&resp=xml http://<somedomain>/api?task=countries&resp=json |
|
| Returns | all countries with their ids, names and capital towns | |
| CountryByid | Retrieves a country by its id. | |
| URL | http://<somedomain>/api?task=country&by=countryid | |
| Formats | XML, JSON | |
| Parameters | id - Required. The country id. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used |
|
| Example | http://<somedomain>/api?task=country&by=countryid&id=1&resp=xml http://<somedomain>/api?task=country&by=countryid&id=1&resp=json |
|
| Returns | a country with its id, name and capital town | |
| CountryByISO | Retrieves a country by its iso. | |
| URL | http://<somedomain>/api?task=country&by=countryiso | |
| Formats | XML, JSON | |
| Parameters | iso - Required. The country's ISO. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used | |
| Example | http://<somedomain>/api?task=country&by=countryiso&iso=ad&resp=xml http://<somedomain>/api?task=country&by=countryiso&iso=ad&resp=json |
|
| Returns | a country with its id, name and capital town | |
| CountryByName | Retrieves a country by its name. | |
| URL | http://<somedomain>/api?task=country&by=countryname | |
| Formats | XML, JSON | |
| Parameters | name - Required. The country's name. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used |
|
| Example | http://<somedomain>/api?task=country&by=countryname&name=andorra&resp=xml http://<somedomain>/api?task=country&by=countryname&name=andorra&resp=json |
|
| Returns | a country with its id, name, and capital town | |
| LOCATIONS | Locations | Retrieves all the locations with the Ushahidi engine. |
| URL | http://<somedomain>/api?task=locations | |
| Formats | XML, JSON | |
| Parameters | resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. | |
| Example | http://<somedomain>/api?task=locations&resp=xml http:<somedomain>/api?task=locations&resp=json |
|
| Returns | all locations. | |
| LocationByid | Retrieves a location by its id. | |
| URL | http://<somedomain>/api?task=location&by=locid | |
| Formats | XML, JSON | |
| Parameters | id - Required. The location id. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=location&by=locid&id=1&resp=xml http:<somedomain>/api?task=location&by=locid&id=1&resp=json |
|
| Returns | a location with that id. | |
| LocationsByCountryid | Retrieves a location by a country id. | |
| URL | http://<somedomain>/api?task=location&by=country | |
| Formats | XML, JSON | |
| Parameters | id - Required. The country's id. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http:<somedomain>/api?task=location&by=country&id=1&resp=xml http:<somedomain>/api?task=location&by=country&id=1&resp=json |
|
| Returns | a location with that country id. | |
| INCIDENTS | Incidents | Retrieves all the incidents submitted to ushahidi. |
| URL | http://<somedomain>/api?task=incidents | |
| Formats | XML, JSON | |
| Parameters | resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. | |
| Example | http://<somedomain>/api?task=incidents&by=all&resp=xml http://<somedomain>/api?task=incidents&by=all&resp=json |
|
| Returns | all incidents. | |
| IncidentsByCategoryId | Retrieves all incidents by a category id. | |
| URL | http://<somedomain>/api?task=incidents&by=catid | |
| Formats | XML, JSON | |
| Parameters | id - Required. The category id. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=incidents&by=catid&id=1&resp=xml http://<somedomain>/api?task=incidents&by=catid&id=1&resp=xml |
|
| Returns | all the incidents that belongs to the category id. | |
| IncidentsByCategoryName | Retrieves all incidents by a category name. | |
| URL | http://<somedomain>/api?task=incidents&by=catname | |
| Formats | XML, JSON | |
| Parameters | name - Required. The category name. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=incidents&by=catname&name=deaths&resp=xml http://<somedomain>/api?task=incidents&by=catname&name=deaths&resp=xml |
|
| Returns | all the incidents that belongs to the category with that name. | |
| IncidentsByLocationid | Retrieves all incidents by a location id. | |
| URL | http://<somedomain>/api?task=incidents&by=locid | |
| Formats | XML, JSON | |
| Parameters | id - Required. The location id. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=incidents&by=locid&&id=1resp=xml http://<somedomain>/api?task=incidents&by=locid&&id=1resp=json |
|
| Returns | all the incidents that belongs to the location with that id. | |
| IncidentsByLocationName | Retrieves all incidents by a location name. | |
| URL | http://<somedomain>/api?task=incidents&by=locname | |
| Formats | XML, JSON | |
| Parameters | name - Required. The location name. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=incidents&by=locname&name=haiti&resp=xml http://<somedomain>/api?task=incidents&by=locname&name=haiti&resp=xml |
|
| Returns | all incidents that belongs to the location with that name | |
| IncidentsBySinceId | Retrieves all incidents since a given incident id. | |
| URL | http://<somedomain>/api?task=incidents&by=sinceid | |
| Formats | XML, JSON | |
| Parameters | id - Required. The incident id you want to start from. resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=incidents&by=sinceid&id=1000&resp=xml http://<somedomain>/api?task=incidents&by=sinceid&id=1000&resp=json |
|
| Returns | all incidents since incident 1000 | |
| incidentcount | Returns the number of incidents that have been approved. | |
| URL | http://<somedomain>/api?task=incidentcount | |
| Formats | XML, JSON | |
| Parameters | NONE | |
| Example | http://<somedomain>/api?task=incidentcount&resp=xml http://<somedomain>/api?task=incidentcount&resp=json |
|
| Returns | The number of approved incidents | |
| geographicmidpoint | Returns an approximate geographic midpoint of all approved incidents. | |
| URL | http://<somedomain>/api?task=geographicmidpoint | |
| Formats | XML, JSON | |
| Parameters | NONE | |
| Example | http://<somedomain>/api?task=geographicmidpoint&resp=xml http://<somedomain>/api?task=geographicmidpoint&resp=json |
|
| Returns | A latitude and longitude of the approximate geographic midpoint. | |
| orderfield | Which field to use to order the results. | |
| URL | http://<somedomain>/api?task=incident&orderfiled=field&sort=1&limit=10 | |
| Formats | XML, JSON | |
| Parameters | orderfield=(incidentid|locationid|incidentdate) incidentid is the default sort How to sort the results. &sort=(0|1). 0 is Ascending, 1 is Descending; 0 is the default limit How many incidents to return &limit=[0-9]. If omitted, 20 is the default. |
|
| Example | http://<somedomain>/api?task=incidents&orderfield=date&sort=0&resp=xml&by=all&limit=5 | |
| Returns | all incidents sorted either ascending or descending and to the set limit | |
| SYSTEM | version | Returns the version of Ushahidi running. |
| URL | http://<somedomain>/api?task=version | |
| Formats | XML, JSON | |
| Parameters | None. | |
| Example | http://<somedomain>/api?task=version |
|
| Returns | Version Number. | |
| KML | 3dkml | NOTE: Not Supported — Retrieves all the approved incidents, along with color, time and altitude as a representation of time for a 3D display of incidents. |
| URL | http://<somedomain>/api?task=3dkml | |
| Formats | KML | |
| Parameters | None. | |
| Example | http://<somedomain>/api?task=3dkml |
|
| Returns | KML of all incidents. | |
POST Methods
The various methods accessed via the HTTP POST method are as follows:
Note Post data needs to be formatted as multipart/form-data because of the image upload. Its very important
| REPORTS | report | Submit an incident/report to an instance of an Ushahidi engine. |
|---|---|---|
| URL | http://<somedomain.com>/api | |
| Formats | XML, JSON | |
| Parameters | task - the task to be performed. Its report in this case. incident_title - Required. The title of the incident/report. incident_description - Required. The description of the incident/report. incident_date - Required. The date of the incident/report. It usually in the format mm/dd/yyyy. incident_hour - Required. The hour of the incident/report. In the 12 hour format. incident_minute - Required. The minute of the incident/report. incident_ampm - Required. Is the incident/report am or pm. It of the form, am or pm. incident_category - Required. The categories the incident/report belongs to. It should be a comma separated value csv latitude - Required. The latitude of the location of the incident report. longitude - Required. The longitude of the location of the incident/report. location_name - Required. The location of the incident/report. person_first - Optional. The first name of the person submitting the incident/report. person_last - Optional. The last name of the person submitting the incident/report. person_email - Optional. The email address of the person submitting the incident/report. incident_photo[] - Optional. Photos to accompany the incident/report. incident_news - Optional. A news source regarding the incident/report. A news feed. incident_video - Optional. A video link regarding the incident/report. Video services like youtube.com, video.google.com, metacafe.com,etc resp - Optional. The data exchange, either XML or JSON. When not specified, JSON is used. |
|
| Example | http://<somedomain>/api?task=report&incident_title=Test&incident_description=Testing+with+the+api.&incident_date=03/18/2009&incident_hour=10&incident_minute=10&incident_ampm=pm&incident_category=2,4,5,7&latitude=-1.28730007&longitude=36.82145118200820&location_name=accra&person_first=Henry+Addo&person_last=Addo&person_email=henry@ushahidi.com&resp=xml | |
| tagnews | Add a news source to an exciting incident/report. | |
| URL | http://<somedomain.com>/api | |
| Format | XML, JSON | |
| Parameters | id - Required. The id of the incident to add the news. url - Required. The URL of the news feed. task - Required. The task to be performed. Its tagnews in this case. |
|
| tagvideo | Add a video to an exciting incident/report. | |
| URL | http://<somedomain>/api | |
| Format | XML, JSON | |
| Parameters | id - Required. The id of the incident to add the video. url - Required. The URL of the video. task - Required. The task to be performed. Its tagvideo in this case. |
|
| tagphoto | Add a photo to an exciting incident/report. | |
| URL | http://<somedomain>/api | |
| Format | XML, JSON | |
| Parameters | id - Required. The id of the incident to add the video. photo - Required. The path to the photo. task - Required. The task to be performed. Its tagphoto in this case. |