Transparantie in de rechtspraak

Before you get started

  • Our REST API allows you to programmatically search through the judges in our database.
  • There is no authentication required. It's free to use.
  • The examples in this documentation are written in curl or Python using the requests package.
  • If you need help, or if you'd like to show us what you made with our API, open up an issue!

Quickstart


The base URL of the API is https://openrechtspraak.nl/api/v1/.

Everywhere in this documentation, the requests package is used to prepare and execute HTTP requests. To install the requests package, run pip install requests in your cli. Subsequently, import the requests package as shown below. This line will not reappear in other code snippets to enhance readability.

import requests

We're now ready to perform our first request. To retrieve a list of people from the API, we can use the person endpoint.

r = requests.get("http://openrechtspraak.nl/api/v1/person")
response = r.json()

print(len(response.get("data")))
print(response.get("count"))

General concepts


Offset pagination

You might have noticed that the response from the quickstart only returned a list of 20 people. The API only returns a limited number of people per request, which ensures you'll get a quick response. This is called a page.

Offset pagination allows you to retrieve a subsequent list of records, in other words: it allows you to retrieve the next page. Offset pagination works with two query parameters: offset and limit.

offset determines the number of records that should be skipped. limit determines the number of records per page. The maximum limit for our API is 100. If our API includes 1.000 people, that means you'll need to perform at least 10 requests.

Here is an example that retrieves the first 5 pages of people from our API:

limit = 5
people = []

for page in range(0, 5):
    r = requests.get("http://localhost:5000/api/v1/person", params={
        'offset': limit * page,
        'limit': limit
    })
    response = r.json()
    people.extend(response.get("data"))

    print(f"Retrieved records for page {page}")

print(f"Done! Retrieved {len(people)} people")

Routes


LIST person

Path
/api/v1/person

Query parameters

q
String based search. Use % for a wildcard.
former_judges
Boolean (true/false, default: false) that determines whether former judges should be included in the resultset.
limit
Integer (default: 20, max: 100) that determines the size of the resultset.
offset
Integer (default: 0) that determines the number of records that should be skipped.

Example url

http://openrechtspraak.nl/api/v1/person?limit=2&offset=2&q=van

Response 200

{
  "count": 4075,
  "data": [
    {
      "professional_details": [
        {
          "function": "Rechter-Plaatsvervanger",
          "id": "e303527c-5ebb-43e1-aae0-bbaf87449d5a",
          "organisation": "Rechtbank Amsterdam"
        }
      ],
      "first_name": null,
      "gender": "male",
      "id": "19e099ff-c05e-46b9-afa2-4d9e55ae7c28",
      "initials": "B.G.L.",
      "last_name": "Aa",
      "rechtspraak_id": "OdESTwJMbvW70UdZPqTFX1dqz78u__71",
      "titles": "dhr. mr.",
      "toon_naam": "dhr. mr. B.G.L. van der Aa",
      "toon_naam_kort": "B.G.L. van der Aa"
    },
    ...
  ]
}

Examples


Retrieving all people with 'aa' in their name

import requests

limit = 100
page = 0
people = []

while True:
    r = requests.get("http://localhost:5000/api/v1/person", params={
        'offset': limit * page,
        'limit': limit,
        'q': 'aa'
    })
    r.raise_for_status()
    response = r.json()

    data = response.get("data")

    if len(data) == 0:
        break

    people.extend(data)

    print(f"Retrieved records for page {page}")
    page += 1

print(f"Done! Retrieved {len(people)} people")

Retrieving a list of people and writing them to a json file

import json
import requests

r = requests.get("http://localhost:5000/api/v1/person")
r.raise_for_status()
response = r.json()
data = response.get("data")

with open('export.json', 'w') as file:
    json.dump(data, file)