The "Public API" is termed as such because it does not require any authentication to access and/or use. This part of the API is restricted to (public domain) information retrieval and report submission. The sections that follow outline the various tasks that may be performed using this part of the API.

Reports

Reports are retrieved by sending a HTTP GET request to the base URL with incidents as the task parameter. Only approved reports are fetched.

Request Example

http://<deployment_url>/api?task=incidents

Optional Request Parameters

Returned Values

The reports request returns JSON with top-level fields payload, error.  

• The error field contains message, code;  a reports list with no errors should contain message="No Error" and code=0. 
• The payload field contains the reports list, and has top-level fields domain, incidents.  Domain contains the URL of the ushahidi instance; incidents contains the list of reports.  So if your API result goes into variable "result", your incidents list will be in result['payload']['incidents']
• The top-level fields returned for each incident are media, incident, customfields, comments, categories.
• The fields in incident are:

Submitting a Report

A report is submitted by sending a HTTP POST request to the base URL with report as the task parameter. Additionally, the following parameters must also be specified

Request Example

http://<deployment_url>/?task=report

Required Parameters

Optional Parameters

Categories

Categories are retrieved by sending a HTTP GET request to the base URL with categories as the task parameter. Only visible categories are fetched.

Request Example

http://<deployment_url>/api?task=categories

Optional Request Parameters

Locations

Locations are retrieved by sending a HTTP GET request to the base URL with locations as the task parameter

Request Example

http://<deployment_url>/api?task=locations

Optional Request Parameters

Comments

Comments are retrieved by sending a HTTP GET request to the base URL with comments as the task parameter. In addition to the task parameter, the request URL must also specify the by parameter. The table below lists and describes the possible values for this parameter

Request Parameters

Countries

Countries are retrieved by sending a HTTP GET request to the base URL with countries as the task parameter.

Request Example

http://<deployment_url>/api?task=countries

Optional Request Parameters

Custom Forms

Custom forms are retrieved by sending a HTTP GET request to the base URL with customforms as the task parameter

Request Example

http://<deployment_url>/api?task=customforms

Optional Request Parameters

versionMiscellaneous

Returns the version of Ushahidi running along with some key settings.

Request Example

http://<deployment_url>/api?task=version

Feature descriptions

The version api task returns an array of features supported by the deployment. Possible features returned are:

• admin_reports_v2 : Improvements to the Admin reports task.
  Support sort, limit and orderfield params. Support GET requests for read-only tasks. Support by=all param.
• jsonp : Supports JSONP API response type ( usage: &resp=jsonp&callback=mycallback )
• api_key : Supports the API key task. This is only ever marked as false, as it was removed in Ushahidi 2.6