Description and examples of how to use the APIs to access data for the 2023 federal elections.

The main problem is that the `real-time’ files can become pretty big and if many people access them too often just to check if they have been updated, the system is likely to slow down considerably. Moreover, in the unlikely event of a server or network failure, we would switch to a fallback solution, so the URLs of the resource must be up to date on your side. We recommend using the principle below to mitigate these risks.

API Endpoints

Environment Endpoint URL Use
Test Tests before election Sunday
Production Lists and candidates before Sunday + results on Sunday starting 12:00 CET

Basic Principle

flowchart LR
    id1 -.- id4[ API];
    id1[OFS] -.- id2[(AWS S3)];
    id3[Consumer] -->|1 get URLs| id4;
    id3[Consumer] -->|2 HEAD request| id2;
    id3[Consumer] -->|3 download resource if new| id2;

Fig. 1 Basic Principle

  1. The consumer gets the URL(s) of the resource(s) from API.
    This ensures that the URLS are up to date. In the unlikely case of a system failure of the AWS S3 bucket, the FSO will switch to a fallback server and update the URLS in the API.
  2. The consumer makes a HEAD request on the resource server.
    This allows the detection of changes without downloading the entire file, by checking the Last-Modified header. Example with curl (Another example using Python is available below.)
$ curl -I 

HTTP/1.1 200 OK
x-amz-id-2: tpS9Gu0RLuMZbRDwvNEa8qKW2NQBPBm8vYKRf5E+4b9PRS9MNmC/YZBgUDagmw1s172evjx3z64=
x-amz-request-id: Z1T8XB7DNKMZTSDX
Date: Mon, 21 Aug 2023 08:45:52 GMT
Last-Modified: Wed, 16 Aug 2023 14:58:29 GMT
ETag: "811dca5203b626b70e83b79191a760ad"
x-amz-server-side-encryption: AES256
x-amz-meta-minimum-api-version: 32
Accept-Ranges: bytes
Content-Type: application/json
Server: AmazonS3
Content-Length: 3231927
  1. The consumer downloads the resource (only if it has been updated).

Example Code (Python)

An example of how to use the API to retrieve the resource URLs and then check if a resource has been updated without downloading it based on the principle above is available on our GitHub:

Feel free to use, modify or redistribute the code.


HEAD Request works only on HTTP servers or end points where the Last-Modified header is returned. This won’t work with services like the FSO DAM that is a Tomcat web app and returns data directly from a DB without Last-Modified. If you see any link looking like, it won’t be applicable.