PoliCAT - Multilingual Petitions

Get data about an action

To retrieve statistical data about an action, you can use this simple, REST-like API. At the moment, it only supports a very limited range of resources.

Data is available both as raw JSON and as JSONP. To use JSONP, give your callback via the callback query string parameter (e.g. ...stuff?callback=mycallback).

URL

To get the number of signings per action, perform GET request to the following URL: https://www.policat.org/api/v2/actions/42/signings (replace the 42 with your action ID).

Parameter

By default, you will get a summary over the entire lifespan of the action.

widgets (optional)
A comma separated list of widget IDs that you want to get data from, e.g. ?widgets=23,420,597 – unknown or invalid IDs will be silently ignored. Set ?widgets=true to return data of all widgets.
from_via_policat / to_via_policat (optional)
UNIX timestamps for restricting the date range of which data is aggregated. You can give both, one or none. Note that bad dates are not automatically corrected (i.e. if you ask for data of 1832, you will not get any data back). For example ?from_via_policat=1308908966&to=widgets_1308909048.
segregate (optional)
If you set this parameter to "countries" the number of signings will be segregated by countries where possible. (You will get an object with countries as keys and number of signings as values)

To add signings collected elsewhere to the counter of an action, request a token from the action admin (admins can generate tokens on the Action-Tab "Counter & API"). Update the action counter on PoliCAT with your data, using the parameters below. You must submit your counts country-by-country, using 2-digit ISO codes.
Note: (1) Submit your total count up to date (no increment). Previous submissions will be overwritten; this allows you to correct erroneous data previously submitted.
(2) The response data will include your submitted data. To add the PoliCAT counts to your own counter, subtract your submitted count from the "signings_total" PoliCAT response, before added it to your own counter.

token (optional, POST)
Your authentication token given by action admin. Use only server-side!
You must do a POST-request instead of a GET request.
signings[ISO] (optional, POST)
Use POST-parameter of the kind signings[FR], signings[DE] to submit the number of signings of your organisation. Authentication with a token is required.

Response

action_id
ID of the action that has been requested.
signings_via_policat
The number of signings per country collected by policat only.
policat_first_signing (optional)
UNIX timestamp of the first signing.
policat_last_signing (optional)
UNIX timestamp of the last signing.
signings_via_api
The number of signings for the entire action collected by other organisations (API) only. (segregateable by countries)
signings_total (optional)
The number of signings for the entire action. (signings_via_policat + signings_via_api, segregateable by countries)
widgets (optional)
The number of signings of each widget requested. (segregateable by countries)
widget_first_signing (optional)
UNIX timestamp of the first signing of each widget requested.
widget_last_signing (optional)
UNIX timestamp of the last signing of each widget requested.
widgets_first_signing (optional)
UNIX timestamp of the first signing of all widget requested.
widgets_last_signing (optional)
UNIX timestamp of the last signing of all widget requested.
manual_counter_tweak
Gobal offset by policat, added in signings_total.

If you can, please cache the data, because aggregating can be expensive.

Example

Using jQuery

$.ajax({
  dataType: 'jsonp',
  url: 'https://www.policat.org/api/v2/actions/42/signings',
  data: {
    widgets: 'true',
    from_via_policat: 1308908966
  },
  cache: true,
  success: function(data) { alert(data); }
});

Using curl

curl --data "token=#YOUR-TOKEN#&signings[FR]=100&signings[DE]=200" https://www.policat.org/api/v2/actions/42/signings?widgets=true&segregate=countries

Response


{
  "action_id": 42,
  "manual_counter_tweak": 0,
  "widgets": {
    "61": {
      "DE": 123
    },
    "62": {
      "DE": 123,
      "FR": 345
    },
    "63": {
      "FR": 432
    }
  },
  "widget_first_signing": {
    "61": 1411647136,
    "62": 1411647136,
    "63": 1411647136
  },
  "widget_last_signing": {
    "61": 1411649732,
    "62": 1412175028,
    "63": 1412175028
  },
  "signings_via_policat": {
    "DE": 246,
    "FR": 777
  },
  "policat_first_signing": 1411647136,
  "policat_last_signing": 1412175028,
  "signings_via_api": {
    "DE": 876,
    "FR": 765
  },
  "signings_total": {
    "DE": 1122,
    "FR": 1542
  }
}