Public API

Participedia Public API

Participedia expose our data via an API. To get started, please contact us to receive a free API key, which needs to be added to the HTTP header (api_key) to be able to access our API.

API

Participedia exposes a REST API that allows an authorized application perform HTTP GET operations to retrieve a paginated list of cases, methods or organization. The API request parameters are uniform across all three result types, but returned results are not uniform in structure.

Authorization

All requests to the API are required to be authorized using an API key. An unauthorized request or incorrectly authorized request will result in a 401 Unauthorized response code with the response below:

{
    "error": "Invalid Participedia API Key"
}

To authorize a request, set the api_key authorization header to your issued API key value. A NodeJS example request is given below:

const request = require('request');
const options = {
  'method': 'GET',
  'url': 'https://participedia.net/api/v1/cases',
  'headers': {
    'api_key': 'YOUR_API_KEY_HERE'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Making a Request

All API requests are made to the base URL endpoint with the resource name and optional parameters. The API base URL endpoint is https://participedia.net/api/v1 and resource names can be one of /cases, /organizations or /methods. If none of the optional parameters are given, the API returns the latest 50 entries for the given resource. Otherwise, the API returns results that are filtered by the parameters.

Available parameters can be one or more of the options listed in the table below:

Parameter	Type	Default	Notes
skip	number	0	Number of entries to skip before selecting results to return.
limit	number	50	Maximum number of entries to return from the API. Maximum is 200
sortKey	string	post_date	Resource column name by which the returned response is sorted. To sort results in decending order a minus sign (-) is added before the sort key, otherwise, the result is sorted in ascending order. Note: The sort key may vary by resource type
selectedCategory	string		Required parameter, it can be case, organization or method
---- CASE FILTER ----
general_issues	string		Most relevant issue addressed in the case. It can be agriculture, arts, business, etc. *Note: If you want to use two or more items you need to separate it with a comma ,
scope_of_influence	string		Geographical or jurisdictional scope of the case. It can be organization, neighbourhood, city/town, metropolitan, etc
purposes	string		Most relevant purpose of the case. It can be make, make_influence, deliver, etc.
approaches	string
public_spectrum	string		Goal from the IAP2 Spectrum of Public Participation that the case best represents. It can be inform, consult, involv, etc
open_limited	string		Participation open to all or limited to a subset of the population. It can be open, open_to, limited`, etc
recruitment_method	string		Method used to recruit a limited subset of the population. It can be captive, random, stratified, etc
method_types	string		Most relevant method of the case. It can be captive, random, stratified, etc
tools_techniques_types	string		Specific methods, tools and techniques used in the case. It can be manage, collect, facilitate, etc
facetoface_online_or_both	string		Use of online or face to face interaction for the case. It can be facetoface, online and both
organizer_types	string		Type of organizers or managers. It can be academic, activist, community, etc
funder_types	string		Type of funder. It can be academic, activist, community, etc
change_types	string		Most relevant type of change to which the case contributed. It can be changes, changes_civic, changes_public, etc
country	string		Country where the primary case activities occurred.
---- METHOD FILTER ---
method_types	string		Most relevant method of the project or event. It can be collaborative, community, deliberative, etc.
purpose_method	string		Select and rank up to three purposes that this method best serves, with “1” indicating the most relevant. It can be make, make_influence, etc.
public_spectrum	string		Goal from the IAP2 Spectrum of Public Participation that the method best represents. It can be inform, consult, involve, etc.
open_limited	string		Participation open to all or limited to a subset of the population. It can be open,open_to, limited, etc.
recruitment_method	string		Method used to recruit a limited subset of the population. It can be captive, random, stratified, etc.
number_of_participants	string		Select and rank up to three group sizes that this method can accommodate, with “1” indicating the optimal size. It can be individuals, small, medium, etc.
facetoface_online_or_both	string		Use of online or face to face interaction for the project or event. It can be facetoface, online and both.
facilitators	string		Does this method require a facilitator at some point during the process? It can be yes or no.
participants_interactions	string		Select and rank up to three types of interaction that can take place among participants using this method, with “1” indicating the most typical form. It can be acting, ask, discussion, etc.
decision_methods	string		Select up to three types of decision making that are compatible with this method, with “1” indicating the most typical form of decision making. It can be opinion, idea, general, etc.
scope_of_influence	string		Select up to three geographical or jurisdictional boundaries within which this method can be implemented. It can be organization, neighbourhood, city/town, etc.
level_polarization	string		Level of political polarization this method can handle. It can be not, low, moderate, etc.
level_complexity	string		Level of complexity this method can handle. It can be very_low, low, moderate, etc.
--- ORGANIZATION FILTER ---
scope_of_influence	string		Select up to three geographical or jurisdictional boundaries within which this organization is active. It can be organization, neighbourhood, city/town, etc.
sector	string		In what sector does this organization operate? It can be _profit, government, non_profit_non_gov, etc.
general_issues	string		Most relevant issue addressed in the project or event. It can be agriculture, arts, business, etc.
type_method	string		Select and rank up to three types of methods used by this organization, with “1” indicating the most relevant. It can be collaborative, community, deliberative, etc.
type_tool	string		Select and rank up to three types of tools/techniques used by this organization, with “1” indicating the most relevant. It can be manage, collect, facilitate, etc.
country	string		Country where the primary activities occurred.

A request to retrieve the oldest 50 methods, sorted by last updated date will look like below: https://participedia.net/api/v1/methods?skip=0&limit=50&sortKey=-updated_date

Note: Only English language results are currently returned by the API

Request Response

Success Response

Successful requests result in a 200 Ok response code that returns a JSON object with a single key that matches the requested resource' name, and a value that is a JSON array of requested resource values, For example, a request to fetch cases will return a JSON array in the format below:

    {
        "cases": [] // Array of cases
    }

Failure Response

An authorized request that fails will return a 400 Bad Request response code with a JSON object that is in the format below:

    {
        "error": "Error message" // Reason for request failure
    }

Filters

API calls for a list of cases, methods, and organizations that can have specific parameters. We are adding filters as parameters. The list of the filters can be seen in the table of the parameters.

Example: https://participedia.net/api/v1/cases?general_issues=arts&purposes=make&selectedCategory=case