Parline API
The Parline API gives read-only programmatic access to the full range of data held within the Parline dataset. This page provides user-friendly documentation for using the API. The API follows the OpenAPI specification (OAS) and the data response conforms to the JSON:API specification. The OAI-generated documentation is available at https://api.data.ipu.org/v1/documentation. Information about recent updates and new releases of the API is published here.
Introduction
Welcome to the documentation for Parline API. This guide provides information and examples on how to the access and use the API.
The API provides access to the historical dataset of parliamentary data, based on five main entities:
- Country
- Parliament
- Chamber
- Specialized body and
- Election
There are also two secondary entities:
- People, containing information about individuals, and
- Political party, containing information about political organisations.
There is an end point for each entity.
Each main entity has a unique identifier (Id);
| Entity | Id | Example |
| Country | country_code | ES |
| Parliament | parliament_code | ES |
| Chamber | chamber_code | ES-LC01 |
| Election | election_code | ES-UC02-E20181211 |
| Specialized body | specialized_body_code | ES-LC-SB01 |
API end points
Main entities
| Entity | URL | |
| Country | https://api.data.ipu.org/v1/countries | |
| Parliament | https://api.data.ipu.org/v1/parliaments | |
| Chamber | https://api.data.ipu.org/v1/chambers | |
| Election | https://api.data.ipu.org/v1/elections | |
| Specialized bodies | https://api.data.ipu.org/v1/specialized_bodies |
Each main entity may also be referenced by Id, for example:
returns the Chamber data for Spain (country code ES).
Secondary entities
| Entity | URL | |
| People | https://api.data.ipu.org/v1/people | |
| Political party | https://api.data.ipu.org/v1/political_parties |
Secondary entities do not have an endpoint for single records. Instead, an exact match filter on the unique identifier may be used, e.g.:
Metadata
| Request | URL | |
| Get all groups | api.data.ipu.org/v1/metadata/groups/ | |
| Get all fields meta | api.data.ipu.org/v1/metadata/fields/ | |
| Get all taxonomies | api.data.ipu.org/v1/metadata/taxonomies/ | |
Pagination
The number of rows and offset may be controlled using the page parameters
- page[size] specifies the number of rows returned. The default is 10.
- page[number] specifies the page number returned. The default is 1.
If the page number multiplied by the number of rows requested, an error is returned.
Filtering
All entity end-point results may be filtered, uisng a filter expression:
field_id:operator:value
Operators
Comparison operators:
- eq – equal, exact match
- neq – not equal
- lt – less than
- lte – less than or equal
- gt – greater than
- gte – greater than or equal
- in – for matching against a list of values
- nin – for matching values outside a list (not in)
The default operator is eq.
Note that not all operators will make sense on all field types. For example the less than filter will only make sense on numeric fields).
Combining operators
AND
By default, operators are ANDed together. Several fields may be queried by padding multiple filter[] query parameters, e.g. filters[]=region.term:eq:europe&filter[]=population_in_thousands:gt:5000
OR
This functionality is not yet available. However the “IN” matching may be used for single fields.
Null values
The filter value may be set to Null, applicable for eq and ne matching. i.e.
- field_id:eq:null and
- field_id:ne:null
Case sensitivity
All filters are case-insensitive unless otherwise specified.
Case sensitivity is applied across the (filter – tbc) query parameters using
- match[case]=true
For example:
will return an empty result set, as the Region key is set to ‘Europe’.
Allowed values are true and false
Diacritics and accents
Accents (diacritics) are ignored by default.
Exact matching on accents is applied using
- match[accents]=true
Allowed values are true and false
Date range filters
A date range is specified using the to and from query parameters:
Combining date filters
When a to and from range is given, the API will return all entities which have data points that match the other filters at any point in the time range.
Default dates
If no time range (to and from dates) is given, then entities and data field values will be filtered based on their current data.
Examples
/v1/countries?filters[]=region.term:eq:europe&filter[]=population_in_thousands:gt:5000/v1/countries?filter[region]=eq:europe&filter[population_in_thousands]=gt:5000&from='2020-01-01'
This will return all the European countries that had a population of more than 500,00 at any point since 1 Jan 2020.
Sorting results
Usage
- sort={property1, property2, …}
Comma separated list of fields to sort by.
To sort in descending order, place a minus sign before the field
Example
1/ Sort groups by group_name:
Responses
The API responses follow the JSON:API
Error handling