Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
265 lines (187 sloc) 15.4 KB

Visegrad+ parliament API

Visegrad+ parliament API is a RESTful API providing parliament data from Visegrad and Balkan countries. The data are served in a machine readable format convenient to use in applications or research. The API is public.

The API allows also to modify or delete the data to authenticated users (see USAGE).

Example

To get a list of all Slovak parliament committees make a HTTP request to:

http://api.parldata.eu/sk/nrsr/organizations?where={"classification":"committee"}

and you get the data as a JSON document.

Usage

A general pattern of API URLs is

http://api.parldata.eu/<country-code>/<parliament-code>/<data-collection>?<parameters>

to find all items satisfying given criteria or

http://api.parldata.eu/<country-code>/<parliament-code>/<data-collection>/<id>?<parameters>

to get a particular item by its id value.

Available parliaments

Country Country code Parliament (chamber) Parliament code
Albania al Kuvendi kuvendi
Armenia am խորհրդարան parliament
Belarus by Палата Прадстаўнікоў house
Савет Рэспублікі sovrep
Czech republic cz Poslanecká sněmovna psp
Senát senat
Georgia ge საქართველოს პარლამენტი parliament
Hungary hu Országgyűlés orszaggyules
Kosovo kv Kuvendit kuvendi
Moldova md Parlament parlament
Montenegro me Skupština skupstina
Poland pl Sejm sejm
Senat senat
Serbia rs Народна скупштина skupstina
Slovakia sk Národná rada nrsr
Ukraine ua Верховна Рада rada

Available data collections

Collection name Description
people Members of parliament and other related people.
organizations Groups in parliament (e.g. committees) and other organizations.
memberships Memberships of the people in organizations.
posts Posts in organizations that can be holded by people.
motions A motion is "a formal step to introduce a matter for consideration by a group."
vote-events A vote event is an event at which people's votes are recorded.
votes A vote is one voter's vote in a vote event.
areas Constituencies and other geographic areas whose geometry may change over time.
speeches Parts of a debate transcripts - speeches, scenes, narratives or other.
events Event (e.g. sessions, sittings, elections, etc.). Slightly differs from Popolo.
logs Information about updates of the data by scrapers. (Not a part of Popolo.)

The collections conform to Popolo specification, links on collection names refer to their specification. The respective schema can be found in section 4. Serialization in JSON Schema tab.

There is one restriction with respect to Popolo. A vote can be cast only by a person, not by organization.

Also, inclusion of event into API predated its specification in Popolo, therefore event properties slightly differs from those specified in Popolo.

Parameters

Parameters are used to query a collection and to adjust how the result is returned. They are specified in the URL query component as ?param1=value1&param2=value2&... All parameters are optional.

where

Parameter where specifies a condition which items to return. Examples:

Notes. Returned items are those where all given conditions are met. $gte means greater-or-equal-than, $ne is non-equal operator. The last two examples query the list of person's identifiers for a given pair and they are both equivalent.

The where parameter uses MongoDB syntax, see MongoDB operators for full reference.

Important note. When querying for subdocuments, do not use MongoDB exact match on subdocument syntax – it depends on the order of fields in the subdocument which is undefined. Use dot notation on particular fields instead or $elemMatch operator in case of an array of subdocuments as is used in the last two examples.

projection

The projection parameter allows to return the given fields only or to exclude specified fields from the result. All fields are returned if the projection is not used. Examples:

Projection allows to reduce transferred data to the fields you really need. Fields id, created_at, updated_at are included in the result regardless of the projection. Mixed inclusive-exclusive projection is not allowed.

sort

Ordering of the result. Example (descending by names):

embed

Parameter embed allows to embed items referenced by the selected ones into the result instead of their id-s. See Embedded JSON documents in Popolo specification. Nested embedded relations are separated by dot. Examples:

The former includes all members of the organization into the result as well its parent organization, the latter includes all organizations the person is a member of. It is much more convenient than querying members one by one by organization_id.

Maximum level of nested embedding is 3 levels and an item cannot be embedded into itself recursively. Fields of embedded items cannot be used in the where parameter.

page, max_results

The returned data are paginated to prevent excessive responses. The number of pages of the result can be found in the _links field. You can request a particular page of the result using page parameter and set number of results per page by max_results parameter. The default for max_results is 25, maximum allowed value is 50.

Other notes

Each API response provides meta-information besides the data. The resulting data are stored in field _items. Field _links contains links to other pages of the result.

All times are stored in UTC time. The Client module provides helper functions to convert time between UTC and local timezone.

The default format of the response is JSON as specified in Popolo. You can request XML by sending Accept: application/xml in request header, nevertheless Popolo does not define serialization of the data to XML.

Historical changes in the data are tracked by the API. Former values of the properties are stored in the changes property.

Client module

Instead of sending HTTP requests yourself you can use a client module for Python. Example of usage:

import vpapi
vpapi.parliament('sk/nrsr')

o = vpapi.get('organizations', '54d2a5f9273a394ad5dba348')
p = vpapi.get('people', page=2)
vm = vpapi.getfirst('people',
    where={'name': 'Vladimír Mečiar'},
    embed=['memberships.organization'])

vpapi.timezone('Europe/Bratislava')
last_modified = vpapi.utc_to_local(vm['updated_at'])

To use the client module vpapi, make sure you have requests and pytz packages installed in Python, then download the vpapi module here.