Skip to end of metadata
Go to start of metadata

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

&by=sinceid&id=10

maxid

Maximum report id that should be returned

&by=maxid&id=500

incidentid

Retrieve a single report using its id

&by=incidentid&id=50

locname

Get reports tagged with a specific location name

&by=locname&name=Nairobi

locid

Get reports tagged with a location with the specified id

&by=locid&id=12

cat name

Get reports that belong to a specified category name

&by=catname&name=Health

catid

Get reports that belong to a category with a id

&by=catid&id=12

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

Cats crossing the road

incident_description

Description of the report

The cats were dressed in bow ties and the top cat was playing a tambourine

incident_date

Date when the event being reported took place. The date format is mm/dd/yyyy

01/01/2010

incident_hour

Hour component of the time when the event took place. It must be in the 12 hour format

8

incident_minute

Minute component of the time when the event took place.

53

incident_ampm

Did the event take place in the AM or PM

am

incident_category

The category id (or list of category ids) under which the report should be filed

1,10

latitude

Latitude of the report's location

-1.00384764

longitude

Longitude of the report's location

36.48587550

location_name

Name of the location associated with the report

Meow Island

Optional Parameters

Parameter

Description

Example

person_first

First name of the person submitting the report

John

person_last

Last name of the person submitting the report

Doe

person_email

Email address of the person submitting the report

johndoe@example.com

incident_photo

Photo(s) to accompany the report

None

incident_video

A video link (from YouTube, Metacafe, Vimeo etc) related to the report

http://www.youtube.com/watch?v=08pVpBq706k

incident_news

News links related to the report

http://news.com/that-cat-was-so-badass

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

&by=catid&id=5

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

&by=locid&id=12

countryid

Get a location using the id of the country it belongs to (only applies where a deployment spans more than one country)

&by=countryid&id=12

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

&by=all

reportid

Gets all the comments for a specific report. The report id must be specified.

&by=reportid&id=5

spam

Gets all the comments marked as spam

&by=spam

pending

Gets all the comments awaiting approval (The admin must approve comments before they can be publicly viewable)

&by=pending

approved

Gets all the approved comments

&by=approved

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

&by=countryid&id=1

coutryiso

Get a country using its ISO code

&by=countryiso&iso=KE

countryname

Get a country using its name

&by=countryname&name=Kenya

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

metaGet 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