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).
Contents
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.
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.
| 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 |
| 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 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¶m2=value2&... All parameters are optional.
Parameter where specifies a condition which items to return. Examples:
- /sk/nrsr/people?where={"name": "Vladimír Mečiar"}
- /sk/nrsr/organizations?where={"founding_date": {"$gte": "2012-03-13"}}
- /sk/nrsr/people?where={"gender": "female", "national_identity": {"$ne": "slovenská"}}
- /sk/nrsr/organizations?where={"$or": [{"dissolution_date": {"$gte": "2014-03-13"}}, {"dissolution_date": {"$exists": false}}, {"dissolution_date": {"$in": [null, ""]}}]}
- /sk/nrsr/people?where={"given_name": {"$in": ["Peter", "Pavol"]}}
- /sk/nrsr/motions?where={"text": {"$regex": "európsk", "$options": "i"}}
- /sk/nrsr/motions?where={"sources.url":{"$regex":"ID=3081$"}}
- /sk/nrsr/people?where={"identifiers.identifier": "140", "identifiers.scheme": "nrsr.sk"}
- /sk/nrsr/people?where={"identifiers": {"$elemMatch": {"identifier": "140", "scheme": "nrsr.sk"}}}
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.
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:
- /sk/nrsr/people?projection={"name": 1, "classification": 1}
- /cz/psp/posts?projection={"contact_details": 0}
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.
Ordering of the result. Example (descending by names):
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:
- /sk/nrsr/organizations/54d2a5f9273a394ad5dba348?embed=["parent", "memberships.person"]
- /sk/nrsr/people/54d2a69b273a394ad5dbad26?embed=["memberships.organization"]
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.
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.
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.
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.