API v2.x Developers' Guide

The Citizen Space API is designed to allow simple integration with other frameworks.  Currently the API supports searching and viewing of published activities.

Getting Started

The current version of the API provides read-only access to publicly visible data.  This means that no authentication is required as the access level is the same as a public visitor to the site.  To get started, all you need to know is the URL of the Citizen Space site that you want to interact with.  In this guide we will be talking to our demo site, which lives at https://demo.citizenspace.com, but any Citizen Space site can be used.

Methods should be called via HTTPS GET requests, using the following format:

url_of_citizen_space_instance/api/2.4/methodname?arguments

Arguments are given as url-encoded key/value pairs, and any unsupported arguments will be ignored.

You can talk to the API using any server-side or client-side language that supports HTTPS requests.

Basic query (curl/browser)

To return a filtered list of activities, call json_search_results  with any combination of parameters as specified in the API Reference.

For example:

https://demo.citizenspace.com/api/2.4/json_search_results?tx=arlen+hill&st=open

will return a JSON-encoded list of search results where the title or overview contain the phrase "Arlen Hill" (case-insensitive) and the activity is Open (ie its start date has passed and its end date has not yet been reached).

The fields of the returned JSON structure are detailed in the API Reference.

Server-side integration

This is the preferred method of integration with the Citizen Space API. Caching of results is permitted.

Here is an example of querying the API in python:

import requests

URL = 'https://demo.citizenspace.com/api/2.4/json_search_results'
args = {'tx':'arlen hill', 'st':'open'}

result = requests.get(URL, args)
if result.status_code < 400:
  for activity in result.json():
    print(activity['title'])
else:
  # handle error

Client-side integration

Here's an example using javaScript:

var url = 'https://demo.citizenspace.com/api/2.4/json_search_results?tx=arlen+hill&st=open';
var xmlHttp = new XMLHttpRequest();
xmlHttp.onreadystatechange = function() { 
  if (xmlHttp.readyState == 4 && xmlHttp.status == 200) {
    data = JSON.parse(xmlHttp.responseText);
    data.forEach(function(item) {
      console.log(item.title);
    });
  }
}
xmlHttp.open("GET", url, true); // true for asynchronous 
xmlHttp.send(null);

Here is the same example as a JSFiddle.

Getting details of an individual activity

You can use the json_consultation_details  method to get the overview information about a single activity, for example:

https://demo.citizenspace.com/api/2.4/json_consultation_details?dept=real-client-examples&id=smoke-free-homes-quiz

The method arguments and the fields of the returned JSON structure are detailed in the API Reference.