About a year ago, I wrote a post introducing Citizen Space’s API. APIs (or Application Programming Interfaces), make software developers happy because they provide stable, documented ways for different pieces of software to communicate with each other.

In the case of Citizen Space’s API, we’ve focussed on providing access to the public-facing consultation listings. With some programming knowledge, the API allows you to embed a consultation search form on your own website, send a query to Citizen Space, display the results of the search, and drill down to display individual consultation records.

Version 1 of the API did this in a very straightforward way: requests to the API returned simple, un-styled snippets of HTML, which could then be included in the page markup and styled as required.

However, this simple approach doesn’t provide a huge amount of flexibility in what is displayed. For example, if you call the search_results API method and give it a set of search criteria, it returns an HTML list of consultations that matched the query, including a short snippet of the overview text and the consultation’s start or end date. That’s great if that’s what you want to display on your website, but if you only wanted to display the consultations’ titles, you would have to write code to do a lot of fiddling with the output from the API method, to remove or hide the details you didn’t want. And if you wanted to display more data than was included in the HTML snippet, you’d be in trouble!

Version 2.3 of the API, released this month, provides some new and improved ways to get hold of Citizen Space’s consultation records. The json_search_results method takes search queries in the same format as the original search_results method, but instead of returning HTML, it returns the search results structured in JSON (JavaScript Object Notation) format. JSON-formatted results are not quite as straightforward to include in your site – you have to extract the data and generate the HTML yourself – but it is much easier to select the exact data you want to display for each record, and decide exactly how it will be structured.

We also provide a method called json_consultation_details. This returns a JSON structure containing all the info you’d need to reconstruct an individual consultation’s overview page on your own website, with markup, layout and styling to fit in with the rest of your site.

For all the gory details, you can read the API documentation.

Integration with external sites is something we really want to prioritise in Citizen Space development. If you are looking to integrate more closely with Citizen Space and would like to see a specific piece of functionality added to our API, please drop us a line at support@delib.net. We try to ‘jump the queue’ with API feature requests and if they’re simple, we can often squeeze them into our next monthly release. Right now we’re focussing on access to the public-facing consultation data, but in future we want to introduce an authenticated API to allow, for example, the export of responses, or the programmatic creation of new consultation records.