Need help? Looking for tips and tricks?

This knowledge base contains loads of useful advice and answers to common questions.

If you're still stuck you can always submit a support request and we'll get back to you ASAP.

API v1.0 Developers' Guide

Support -

Overview

Version 1.0 provides a simple HTML based API, designed to allow simple integration with other frameworks.  Currently the API supports searching and viewing of published consultations.

Methods should be called via HTTP GET requests, using the following format:
url_of_citizen_space_instance/api/1.0/methodname?arguments

Arguments are given as url encoded key/value pairs.  Any unsupported arguments will be ignored.

The following guide gives some code examples for getting started with the API using PHP.  However, you can talk to the API using any server-side or client-side language that supports HTTP requests.

Getting Started

The current version of the API only performs read operations on 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 consultation hub that you want to interact with.  In this guide we will be talking to our demo site, which lives at https://www.citizenspace.com/demo, but any Citizen Space site can be used.

Basic GET request

// All API requests are sent to a specific Citizen Space instance and API version.
$URL_ROOT = 'https://www.citizenspace.com/demo/api/1.0/';

// Take a method name and an optional set of url encoded arguments,
// generate the request and return the string result
function citizenspace_api_get($method, $args='') {
  global $URL_ROOT;
  $ch = curl_init($URL_ROOT . $method . '?' . $args);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, True);
  return curl_exec($ch);
}

In the function above, the curl_init line sets up the request to access the API with the specified method name and arguments.  The subsequent line tells curl that when the request is executed, the return value should be the response payload (ie the actual HTML to be displayed) rather than the HTTP status code.  The final line executes the request and returns the string response from Citizen Space.

Calling the function as follows should return a list of all currently open consultation records in our demo Citizen Space site.  These results are formatted with simple HTML to which you can apply your own styles.

echo citizenspace_api_get('search_results', 'st=open');

This should return exactly the same data as hitting the following URL in your browser:

https://www.citizenspace.com/demo/api/1.0/search_results?st=open

Note that the function above is only a simple demonstration; in a production site you'd probably want to check the response's status code to make sure the Citizen Space site is accessible and responding to API calls.

Embedding a consultation finder in your site

The Citizen Space API provides methods you can use to build a Citizen Space consultation finder in your own site.  The following code uses the citizenspace_api_get method we defined above to request a set of search fields from our demo site, we wrap them in a standard HTML form with a submit button.  If you hit the button, you won't see any search results yet, but the form is still being submitted.

<?php $query = http_build_query($_POST); ?>
<h1>Find consultations</h1>
<form action="<?php echo $_SERVER['REQUEST_URI']; ?>" method="post">
<?php echo citizenspace_api_get('advanced_search_fields', $query); ?>
<input type="submit" value="Search"/></form>

Although not strictly ideal for a search form, we're using a POST rather than a GET request for this form, so that the values submitted don't interfere with anything else that might already happen to be on the query string for your page (depends on your website's other requirements and what framework you're using).

Note that we're using the built-in PHP function http_build_query, which turns the submitted $_POST array of field names and values into a nice query string suitable for appending to the end of a url.  We then pass this to the advanced_search_fields API call, which uses the values to repopulate the form fields after the first time you submit the form.  Try it out.  If you submit the form, you'll see that anything you've typed stays typed, and anything you've selected stays selected.

If you just want a simple keyword/postcode search form rather than a huge list of filters, replace advanced_search_fields with search_fields in the code above.

In most cases, you probably want your form to show some results when the user submits it (although of course you could use this form to submit to another script of your own devising - for example to let people sign up for notifications of future consultations that match their search criteria).  But anyway, displaying results that match the submitted query is as easy as the following:

<h2>The following consultations match your query:</h2>
<?php echo citizenspace_api_get('search_results', $query); ?>

By default the page displays all published consultations until you submit the form.  You could of course add some conditional code so that no results are displayed until the form has been submitted.  You could also inspect the return value of the search_results call to display something friendly like 'no results were found' if the list of results is empty.

Embedding individual consultations in your site

On Citizen Space, the overview page for a consultation is made up of two areas:

  • The main body of the page contains the description of the consultation, details of how to participate (including a link if appropriate), links to any supporting documents, and buttons to share the consultation on social networks.
  • The sidebar contains the current state of the consultation, contact details of the consultation officer, open and close dates and other information such as target audiences, areas etc.

The API provides methods to  request the two parts of the page separately, so that you can incorporate them into your own site layout more easily.  Both methods take the absolute URL of the consultation you wish to view, and return the main body and the sidebar of the consultation respectively:

<div class="body">
<?php echo citizenspace_api_get('consult_body', 'path=https://www.citizenspace.com/demo/delib/demodownloadableconsultation'); ?>
</div>
<div class="sidebar">
<?php echo citizenspace_api_get('consult_sidebar', 'path=https://www.citizenspace.com/demo/delib/demodownloadableconsultation'); ?>
</div>

You can surround the two components with your own HTML markup and CSS to make them fit the layout of the rest of your site.

Checking the Citizen Space version

The following line will print out the current version of Citizen Space that your instance is running:

<?php echo citizenspace_api_get('citizen_space_version'); ?>

We use this a lot for our internal management and quality assurance.  It's probably not that useful for anyone else, but it's there if you need it.