API version 2.3

Version 2.3 is a minor update to Version 2.2, adding an additional parameter to the extended attributes.

Methods

json_search_results
Accepts any of the following search parameters:
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 ID, must be one of the audiences configured on the site
in
Interest ID, must be one of the interests configured on the site
de
Department the consultation sites within. Value must be the same as the ID of a department within the site
ar
Area ID, must be one of the areas configured on the site
dk
Date search type, must be one of `op` (open date) and `cl` (close date)
fd
Date to search from. Must be used in conjunction with `dk` (dd/mm/yyyy)
td
Date to search until. Must be used in conjunction with `dk` (dd/mm/yyyy)
ct
Consultation type. Must be one of `QuickConsult` (Online Survey), `File` (Email/Postal Consultation), `Document` (Offline Consultation), or `Link` (Link)
fields
Determines what groups of metadata fields about the consultations will be returned. Permissible values are 'basic', 'extended' and 'all'. Omitting this parameter is equivalent to 'basic'.
callback
Used to enable jsonp requests

If no arguments are supplied, all published consultations are returned.
Any unsupported arguments will be ignored.
Returns a JSON structure containing details of each consultation found:
id
The ID of the consultation
title
The title of the consultation
url
The URL of the consultation
status
State: one of `open`, `forthcoming` or `closed`
overview
Overview of the consultation
startdate
The date the consultation opens / opened on
enddate
The date the consultation closes / closed on
department
The name of the department that the consultation belongs to (extended and above)
dept
The ID of the department that the consultation belongs to (extended and above)
type
The type of consultation (extended and above)
type_string
Human readable type (extended and above)
participation_url
The direct URL to the participation method (survey etc), skipping the overview page (extended and above)
progress
The current state of the consultation (extended and above)
visibility
Either 'public' or 'private' depending on if the consultation has been hidden from end users (extended and above)
why
The contents of the 'why are we consulting?' field (all only)
what_happens_next
The contents of the 'what happens next?' field (all only)
feedbackdate
The date that consultation feedback is/was expected (all only)
resultsdate
The date that consultation results are/were expected (all only)
contact_name
The full name entered in the consultation's contact details (all only)
contact_jobtitle
The job title entered in the consultation's contact details (all only)
contact_team
The team name entered in the consultation's contact details (all only)
contact_phone
The phone number entered in the consultation's contact details (all only)
contact_email
The email address entered in the consultation's contact details (all only)
related_links
A list of related links.(all only)
Related links have the following attributes:
url
The absolute url to link to
title
The human-readable title of the link. Used for display.
related_consultations
A list of related consultations.(all only)
Related consultations have the following attributes:
url
The absolute url to link to
title
The human-readable title of the consultation. Used for display.
supporting_documents
A list of supporting documents.(all only)
Supporting documents have the following attributes:
url
The absolute url to link to
title
The human-readable title of the document, or filename if title was not specified. Used for display.
size
The size of the document including units (eg kB, MB). Used for display.
audiences
A list of audiences this consultation applies to (all only)
Audiences have the following attributes:
id
The ID of the audience. Used for searching.
name
The human-readable name of the audience. Used for display.
areas
A list of ids for areas this consultation applies to NB: This field is omitted unless area support is installed (all only)
Areas have the following attributes:
id
The ID of the area. Used for searching.
name
The human-readable name of the area. Used for display.
interests
A list of ids for interests this consultation applies to (all only)
Interests have the following attribute
id
The ID of the interest. Used for searching.
name
The human-readable name of the interest. Used for display.
json_consultation_details
Accepts the following parameters:
dept (required)
The ID of the department (eg 'parks-and-recreation')
id (required)
The ID of the consultation (eg 'spring-planting-in-kings-gardens')
fields
Determines what groups of metadata fields about the consultations will be returned. Permissible values are 'basic', 'extended' and 'all'. Omitting this parameter is equivalent to 'basic'.

Returns a JSON structure containing the same fields as json_search_results. If dept or id are not specified or do not exist, a 404 status code is returned.

Calling via server side code

If you are calling the API methods through server side code, you do not have to worry about the same origin policy: methods may be called via standard HTTP GET requests.

Calling via AJAX / JQuery

To make calls to the API through client side code, you need to use JSONP. This is due to the same origin policy. We use the same callback name as the JQuery default.

            $.getJSON(
                "https://demo.citizenspace.com/api/2.3/methodname?callback=?",
                {
                    'argument': 'value',
                    'argument2': 'value2'
                },
                function(data, textStatus, jqXHR) {
                    // Handle returned data
                }
            );