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
Optional Request Parameters
Parameter | Description | Example |
|---|---|---|
sinceid | Least report id that should be returned |
|
maxid | Maximum report id that should be returned |
|
incidentid | Retrieve a single report using its id |
|
locname | Get reports tagged with a specific location name |
|
locid | Get reports tagged with a location with the specified id |
|
cat name | Get reports that belong to a specified category name |
|
catid | Get reports that belong to a category with a id |
|
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:
Parameter | Description | Example |
|---|---|---|
| incidentid | ||
| incidenttitle | ||
| incidentdescription | ||
| incidentdate | ||
| incidentactive | Flag for report approved | 1=approved, 0=unapproved |
| incidentverified | Flag for report verified | 1=verified, 0-unverified |
| incidentmode | Method of report submission | 1=web, 2=sms, 3=email, 4=twitter |
| locationid | ||
| locationname | ||
| locationlatitude | ||
| locationlongitude |
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
Required Parameters
Parameter | Description | Example |
|---|---|---|
incident_title | Title of the report |
|
incident_description | Description of the report |
|
incident_date | Date when the event being reported took place. The date format is mm/dd/yyyy |
|
incident_hour | Hour component of the time when the event took place. It must be in the 12 hour format |
|
incident_minute | Minute component of the time when the event took place. |
|
incident_ampm | Did the event take place in the AM or PM |
|
incident_category | The category id (or list of category ids) under which the report should be filed |
|
latitude | Latitude of the report's location |
|
longitude | Longitude of the report's location |
|
location_name | Name of the location associated with the report |
|
Optional Parameters
Parameter | Description | Example |
|---|---|---|
person_first | First name of the person submitting the report |
|
person_last | Last name of the person submitting the report |
|
person_email | Email address of the person submitting the report |
|
incident_photo | Photo(s) to accompany the report | None |
incident_video | A video link (from YouTube, Metacafe, Vimeo etc) related to the report | |
incident_news | News links related to the report |
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
Optional Request Parameters
Parameter | Description | Example |
|---|---|---|
catid | Get the category with the specified id |
|
Locations
Locations are retrieved by sending a HTTP GET request to the base URL with locations as the task parameter
Request Example
Optional Request Parameters
Parameter | Description | Example |
|---|---|---|
locid | Get a location using its id |
|
countryid | Get a location using the id of the country it belongs to (only applies where a deployment spans more than one country) |
|
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
Parameter | Description | Example |
|---|---|---|
all | Gets all the comments |
|
reportid | Gets all the comments for a specific report. The report id must be specified. |
|
spam | Gets all the comments marked as spam |
|
pending | Gets all the comments awaiting approval (The admin must approve comments before they can be publicly viewable) |
|
approved | Gets all the approved comments |
|
Countries
Countries are retrieved by sending a HTTP GET request to the base URL with countries as the task parameter.
Request Example
Optional Request Parameters
Parameter | Description | Example |
|---|---|---|
countryid | Get a single country using its id |
|
coutryiso | Get a country using its ISO code |
|
countryname | Get a country using its name |
|
Custom Forms
Custom forms are retrieved by sending a HTTP GET request to the base URL with customforms as the task parameter
Request Example
Optional Request Parameters
Parameter | Description | Example |
|---|---|---|
all | Get all custom form ids | &by=all |
fields | Get custom form fields and values by incident id | &by=fields&id=0 |
| meta | Get custom form definition by their form id retrieved with by=all | &by=meta&formid=0 |
versionMiscellaneous
Returns the version of Ushahidi running along with some key settings.
Request Example
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