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 Reference

Support -

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.

Methods

The following methods are available:

name:

advanced_search_fields

returns:

an HTML structure containing the form elements for querying the database of consultations. The fieldnames and possible values returned by this method may vary according to the capabilities of the Citizen Space instance.  The output of this method is intended to be embedded in a form constructed by the caller, which then posts (directly or indirectly) to the search_results method.

arguments (typical):

any of the field names returned by this method can also be accepted as optional string arguments, to pre-populate the form fields.  These arguments can vary according to the capabilities of the Citizen Space instance, but typical arguments include:

tx: Free text search, case-insensitive (eg "Park")

pc: Postcode, accepts partial postcodes (eg "BS8" or "BS8 111")

st: State, must be one of `open`, `forthcoming` or `closed`

au: Audience, must be one of the audiences configured on the site

in: Interests, must be one of the interests configured on the site

example:

http://www.citizenspace.com/demo/api/1.0/advanced_search_fields?tx=test&pc=bs1&st=open

name:

search_fields

returns:

an HTML structure containing a single free-text form field for querying the database of consultations.  The output of this method is intended to be embedded in a form constructed by the caller, which then posts (directly or indirectly) to the search_results method.

arguments:

keyword: (optional) A string used to pre-populate the form field.

example:

http://www.citizenspace.com/demo/api/1.0/search_fields?keyword=test

name:

search_results

returns:

an HTML structure containing simply rendered consultation overviews based on the query parameters.

arguments:

takes any of the parameters returned by the search_fields or advanced_search_fields methods. If no arguments are supplied, all published consultations are returned.

Note that it is not required to call search_fields or advanced_search_fields before calling search_results, but the output of these methods should be inspected to determine the available arguments for each Citizen Space site.

example:

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

name:

consult_body

returns:

an HTML structure containing the main content of a consultation record, including the overview, details on how to participate and buttons for sharing the consultation on social media.

arguments:

path: (required) The absolute URL to the consultation.

example:

http://www.citizenspace.com/demo/api/1.0/consult_body?path=http://www.citizenspace.com/demo/delib/demodownloadableconsultation

name:

consult_sidebar

returns:

an HTML structure containing the sidebar content of a consultation record, including contact details, open and close dates, target audience and interest groups.

arguments:

path: (required) The absolute URL to the consultation.

example:

http://www.citizenspace.com/demo/api/1.0/consult_sidebar?path=http://www.citizenspace.com/demo/delib/demodownloadableconsultation

name:

citizen_space_version

returns:

a string containing the current Citizen Space version.

arguments:

none

example:

http://www.citizenspace.com/demo/api/1.0/citizen_space_version

Powered by Zendesk