API Documentation

Introduction

The API for LobbyFacts is made to allow easy access to up-to-date, structured information about registered interests, persons and other organisations.

It provides both entity-centric access which can be used to find and retrieve data about individual data items as well as a reporting interface which exposes pre-defined views of the data, including aggregated overviews per country etc.

Conventions

A few simple conventions apply throughout the API:

  • All data is accessible as JSON, some data is also available as CSV.
  • JSONP is accessible by adding a callback= argument to each request
  • Once the site is in prototype operation, all data will be updated every day. Requests have cache headers, so some data may not update unless you cache-bust.
  • The API aims to provide URIs for further data in many places. This includes ready-made API links for pagination and entity URIs which can be used to retrieve the full data for any shallow object returned by the API.

Entities

The API exposes a number of entities. For each domain entity, there are two operations: index and view.

The view action will return a deep representation of the specified entity, which often contains shallow representations of associated objects.

For index pages, a shallow representation of the data is returned, containing no associated entities and a limited set of attributes. Users can set an Accept header to text/csv or add .csv to the URL to retrieve a CSV-encoded form of the data.

The index operation supports a number of query parameters:

  • limit (default: 50, maximum 500) limits the number of entries returned in a single page.
  • offset (default: 0) specifies the number of records to skip before returning a set of entries.
  • filter can be specified multiple times. The value of the argument has the format field:value, i.e. the specified value applied as a filter to the given field.
  • Some entities, such as representatives, persons and organisations also support the q parameter, which will perform a full-text search of the data, looking for the specified terms.

Entity

Entities represent unique actors represented in the database. They mainly exist to deduplicate and link between different types of records, such as a representative, a person or some other domain object which refer to the same physical thing.

Representative

Representatives are the companies, trade associations or lobbying firms which are registered in the lobby register. Most other information is in some way linked to them. They have a 1:1 relationship to entity.

Person

Individuals appear either as legal contact or head of a representative, or through an accreditation, which permits them to enter the European Parliament. Persons have a 1:1 link to entity.

Category

Categories reflect the type of a particular represenative. They have two levels, and categories on the second level link up to the more general group.

Organisations

Organisations are not well specified, but they can represent the clients or members of a representative. They have a 1:1 relationship to entity

Country

Each represenative has a contact country, which is the place from where its lobbying operation is run (thus not necessarily the location of its headquarters).

Financial Data

A represenative has to make a financial statement detailing its revenues and expenses on lobbying activities once a year. Different fields on this are set for companies, NGO and law firms.

Accreditation

A represenative can have multiple persons associated with it that are authorized to enter the European Parliament as lobbyists.

Some other domain objects exist, but they work mainly as many to many join tables and can be discovered by looking at the JSON output of those objects documented here.