Pabuviz Database API Documentation

Welcome to the Pabuviz API documentation. This API gives you direct access to all data which is used by pabuviz.org.

Pabuviz is a project that came to life at the Institute for Logic, Language and Computation of the University of Amsterdam in the Computational Social Choice Group led by Ulle Endriss.

Markus Utke has been the main developer for the project, helped (marginally) by Simon Rey.

Please get in touch with either Markus or Simon if you have any questions or thoughts you would like to share!

Overview

All requests should be made to the following base URL:

https://db.pabuviz.org/api

The type of all parameters corresponds to the expected type when parsing the parameter as JSON in python.

The parameter filters can be used in several calls to filter elections by election properties. The election properties can be requested through the endpoint /election_properties. Each election property has an inner_type and depending on that different filters can be used:

int, float or date: {"min": ..., "max": ...}
bool: true or false
str: {"contains": ...} or {"equals": ...}

An example filter could look like this:

{
    "name": {"contains": "Amsterdam"},
    "num_projects": {"min": 30},
    "has_categories": true
}

Endpoints

Get Ballot Type List

URL: /ballot_types
Method: GET
Description: Returns the list of ballot types.

Parameters

Optional:

filter_existing (bool, default: True): If True, only ballot types with an election in the database are returned.

Sample Request

GET https://db.pabuviz.org/api/ballot_types?filter_existing=true

Sample Response

{
    "data": [
        {
            "name": "approval",
            "description": "voters simply select a set of projects (the ones they approve), potentially with additional constraints"
        },
        {
            "name": "ordinal",
            "description": "voters rank in order of preferences some or all of the projects"
        },
        {
            "name": "cumulative",
            "description": "voters distribute a given number of points between the projects"
        }
    ]
}

Get Election List

URL: /elections
Method: GET
Description: Retrieves a list of all elections that match the given filters in the database.

Parameters

Optional:

filters (dict): Filters to filter the elections by.

Sample Request

GET https://db.pabuviz.org/api/elections/?filters={%22num_projects%22%3A{%22min%22%3A50},%22ballot_type%22%3A%22cumulative%22}

Sample Response

{
    "data": [
        {
            "name": "Czestochowa, 2020, 2019-09",
            "description": "Municipal PB in Częstochowa",
            "country": "Poland",
            "unit": "Czestochowa",
            "subunit": "",
            "instance": "2020",
            "budget": 2367122.0,
            "num_projects": 90,
            "num_votes": 16978,
            "ballot_type": "cumulative",
            "rule": "greedy_cost",
            "date_begin": "2019-09-06",
            "date_end": "2019-09-25",
            "has_categories": false,
            "has_targets": false,
            "has_neighborhoods": false,
            "has_voting_methods": false
        }
    ],
    "metadata": {
        ...
    }
}

Get Election Details

URL: /election_details
Method: GET
Description: Retrieves a list of elections of the given ballot type and includes specified election properties.

Parameters

Required:

property_short_names (list[string]): List of election property short names to include in the response.
ballot_type (string): The ballot type of the elections (one of "approval", "ordinal", "cumulative").
filters (dict): Filters for elections.

Sample Request

GET https://db.pabuviz.org/api/election_details/?property_short_names=[%22med_ballot_cost%22,%22avg_proj_cost%22]&ballot_type=%22ordinal%22

Sample Response

{
    "data": {
        "Wieliczka, Green Budget, 2023, 2023-04": {
            "avg_proj_cost": 49178.328125,
            "med_ballot_cost": 88969.0,
        },
        "Poznań, 10 - Świerczewo, Wilda, Zielony Dębiec, 10 - Świerczewo, Wilda, Zielony Dębiec, 2023, 2022-10": {
            "avg_proj_cost": 573875.0,
            "med_ballot_cost": 716000.0,
        },
        ...
    },
    "metadata": [
        ...
    ]
}

Get Project List

URL: /projects
Method: GET
Description: Retrieves a list of all projects for a given election.

Parameters

Required:

election_name (string): Name of the election.

Sample Request

GET https://db.pabuviz.org/api/projects/?election_name=%22Amsterdam%2C+Nieuw-West%2C+647%2C+2022-01%22

Sample Response

{
    "data": [
        {
            "project_id": "44253",
            "name": "Vergroening parkeerplaatsen Zuiderakerweg",
            "cost": 5000.0,
            "description": "",
            "rules_selected_by": [
                "greedy_card",
                "greedy_cost",
            ],
        },
        ...
    ],
    "metadata": {
        ...
    }
}

Get Rule List

URL: /rules
Method: GET
Description: Retrieves a nested list of all rule families, including their associated rules.

Sample Request

GET https://db.pabuviz.org/api/rules

Sample Response

{
    "data": [
        {
            "name": "approximate satisfaction maximiser",
            "abbreviation": "greedy",
            "description": "greedy approximations of the satisfaction maximiser",
            "elements": [
                {
                    "abbreviation": "greedy_cost",
                    "name": "greedy (cost)",
                    "description": "greedily selects projects based on the cost to cost ratio, i.e., the approval score (number of approvers)",
                    "order_priority": 9,
                    "rule_family": "greedy",
                    "applies_to": [
                        "approval"
                    ]
                },
                ...
            ],
            "sub_families": [],
            "applies_to": [
                "approval",
                "ordinal",
                "cumulative",
                "cardinal"
            ]
        },
        {
            "name": "satisfaction maximiser",
            "abbreviation": "max_sat",
            "description": "exact satisfaction maximisers",
            "elements": [
                {
                    "abbreviation": "max_card",
                    "name": "cardinality satisfaction maximiser",
                    "description": "selects a feasible set of projects with the maximum total cardinality satisfaction (number of approved and selected projects)",
                    "order_priority": 11,
                    "rule_family": "max_sat",
                    "applies_to": [
                        "approval"
                    ]
                },
                ...
            ],
            "sub_families": [],
            "applies_to": [
                "approval",
                "ordinal",
                "cumulative",
                "cardinal"
            ]
        },
        ...
    ]
}

Get Election Property List

URL: /election_properties
Method: GET
Description: Retrieves a list of election properties that can be used as filters.

Parameters

Optional:

property_short_names (list[string], default: None): List of short names of properties to request.
ballot_type (string, default: None): Name of the ballot type ("approval", "ordinal", "cumulative").

Sample Request

GET https://db.pabuviz.org/api/election_properties/?&ballot_type=%22approval%22

Sample Response

{
    "data": [
        {
            "name": "name",
            "short_name": "name",
            "description": "",
            "inner_type": "str"
        },
        {
            "name": "median ballot length",
            "short_name": "med_ballot_len",
            "description": "median number of projects appearing in a ballot",
            "inner_type": "int"
        },
        ...
    ]
}

Get Rule Result Property List

URL: /rule_properties
Method: GET
Description: Retrieves a list of rule result properties. These are metrics on the result of a rule for an election.

Parameters

Optional:

property_short_names (list[string], default: None): List of short names of properties to request. If None, all properties will be returned.

Sample Request

GET https://db.pabuviz.org/api/rule_properties

Sample Response

{
    "data": [
        {
            "short_name": "avg_card_sat",
            "name": "average cardinality satisfaction",
            "description": "average over all voters of the number of approved projects selected by the rule",
            "inner_type": "float",
            "range": "0-",
            "order_priority": 1,
            "applies_to": [
                "approval"
            ]
        },
        ...
    ]
}

Get Rule Result Average Properties

URL: /avg_rule_property
Method: GET
Description: Returns for each given rule and rule result property, the average value of that property for the result of that rule. Only considers elections that have all given rules and rule result properties computed.

Parameters

Required:

rule_abbr (list[string]): List of abbreviations of the rules.
property_short_names (list[string]): List of short names of the election properties.

Optional:

election_filters (dict, default: {}): Additional filters for the elections considered.

Sample Request

GET https://db.pabuviz.org/api/avg_rule_property/?rule_abbr_list=[%22greedy_card%22%2C%22greedy_cost%22]&property_short_names=[%22avg_nrmcard_sat%22%2C%22inverted_cost_gini%22]&election_filters={%22num_projects%22%3A{%22min%22%3A80}}

Sample Response

{
    "data": {
        "greedy_card": {
            "avg_nrmcard_sat": 0.07931805878402662,
            "inverted_cost_gini": 0.5701038639358232
        },
        "greedy_cost": {
            "avg_nrmcard_sat": 0.051316958915611055,
            "inverted_cost_gini": 0.5202858356890813
        }
    },
    "meta_data": {
        "num_elections": 48
    }
}

Get Satisfaction Histogram

URL: /satisfaction_histogram
Method: GET
Description: Returns for each given rule, the satisfaction histogram for the result of that rule. The bins are [0.0, 0.0], (0.0, 0.05], (0.05, 0.10], ..., (0.95, 1.0].

Parameters

Required:

rule_abbr (list[string]): List of abbreviations of the rules.

Optional:

election_filters (dict, default: {}): Additional filters for the elections considered.

Sample Request

GET https://db.pabuviz.org/api/rule_voter_satisfaction_histogram/?rule_abbr_list=[%22greedy_card%22%2C%22greedy_cost%22]&property_short_names=[%22avg_nrmcard_sat%22%2C%22inverted_cost_gini%22]&election_filters={%22num_projects%22%3A{%22min%22%3A80}}

Sample Response

{
    "data": {
        "greedy_card": {
            "hist_data": [
                0.16720532773043595,
                0.14741755600267872,
                ...,
                0.0,
                0.0
            ],
            "avg": 0.12950753612063
        },
        ...
    }
    "meta_data": {
        "num_elections": 48
    }
}

Get Category Proportions

URL: /get_category_proportions
Method: GET
Description: Returns category proportions for a given election and a list of rules.

Parameters

Required:

election_name (string): Name of the election.
rule_abbreviation_list (list[string]): List of rule abbreviations.

Sample Request

GET https://db.pabuviz.org/api/category_proportions/?election_name=%22Amsterdam%2C+Nieuw-West%2C+647%2C+2022-01%22&rule_abbreviation_list=[%22greedy_card%22%2C%22greedy_cost%22]

Sample Response

{
    "data": {
        "category_names": [
            "Cultuur",
            ...,
            "Sociaal"
        ],
        "vote_cost_shares": [
            0.05554095582607385,
            ...,
            0.03719900519353738
        ],
        "result_cost_shares": {
            "greedy_card": [
                0.19905619637123778,
                ...,
                0.08355290745342003
            ],
            "greedy_cost": [
                0.0,
                ...,
                0.08293264750829327
            ]
        }
    }
}