Skip to main content

Python: FireServiceRota / BrandweerRooster

Python 3 API wrapper for FireServiceRota and BrandweerRooster.

About

This package provides access to emergency incident data from FireServiceRota and BrandweerRooster — services used by firefighters.

Features:

  • Real-time incident notifications via WebSocket
  • User availability (duty schedule)
  • Incident response status (acknowledge / reject)
  • Pager management: list pagers, send messages, poll delivery status

A subscription and login account are required. See fireservicerota.co.uk or brandweerrooster.nl for details.

Installation

pip install pyfireservicerota

Authentication

Authentication uses OAuth2 tokens. On first use, exchange your credentials for a token_info dict and store it. After that you only need the tokens — use refresh_tokens() to keep them valid without re-entering your password.

First-time login

from pyfireservicerota import FireServiceRota, InvalidAuthError

api = FireServiceRota(
    base_url="www.brandweerrooster.nl",
    username="your@email.address",
    password="yourpassword",
)

try:
    token_info = api.request_tokens()
except InvalidAuthError:
    print("Invalid credentials")
    token_info = None

Subsequent use (stored tokens)

from pyfireservicerota import FireServiceRota

api = FireServiceRota(
    base_url="www.brandweerrooster.nl",
    token_info=token_info,  # dict loaded from storage
)

Refreshing tokens

Any API call can raise ExpiredTokenError or InvalidTokenError when the access token needs refreshing:

from pyfireservicerota import ExpiredTokenError, InvalidTokenError, InvalidAuthError

try:
    result = api.get_availability("Europe/Amsterdam")
except (ExpiredTokenError, InvalidTokenError):
    try:
        token_info = api.refresh_tokens()
    except InvalidAuthError:
        print("Refresh token invalid, re-login required")

Usage

Availability

availability = api.get_availability("Europe/Amsterdam")
print(availability)
# {"available": True, "type": "recurring", ...} or {"available": False}

Incidents

incident_id = 123456

# Get your response status for an incident
response = api.get_incident_response(incident_id)

# Acknowledge (True) or reject (False)
api.set_incident_response(incident_id, True)

Real-time incident notifications (WebSocket)

import time
from pyfireservicerota import FireServiceRotaIncidents

WSS_URL = "wss://www.brandweerrooster.nl/cable?access_token={}"
last_refresh = 0.0

def on_incident(data):
    print(f"Incident received: {data}")

def on_connect_failed():
    # Called after every failed attempt, so refresh at most once a minute
    # and leave the other retries to the listener.
    global last_refresh
    if time.monotonic() - last_refresh < 60:
        return
    last_refresh = time.monotonic()
    token_info = api.refresh_tokens()
    listener.start(url=WSS_URL.format(token_info["access_token"]))

listener = FireServiceRotaIncidents(
    on_incident=on_incident, on_connect_failed=on_connect_failed
)
listener.start(url=WSS_URL.format(token_info["access_token"]))

while True:
    time.sleep(1)

The listener reconnects by itself when the connection drops or goes silent. The access token is part of the URL, so reconnecting fails once it has expired. The optional on_connect_failed callback is called after a failed connection attempt; use it to refresh the tokens and call start with the new URL.

Pagers

# List pagers linked to your account
pagers = api.get_pagers()
# [{"id": 7719, "user_id": 12345, "serial_number": "C202351.01045", "type": "Swissphone s.QUAD C35",
#   "battery_level": 79, "state": "powered_on", "signal_strength": -91, ...}]

# Send using the pager's own registered address (confirmation=True)
result = api.send_pager_message(6789, "Test alarm message", confirmation=True)
if result:
    print(f"Sent: id={result['id']} state={result['acknowledgment_state']} address={result['address']}")

# Send to a specific capcode address
result = api.send_pager_message(6789, "Test alarm message", address="1234567")

# Send to multiple capcodes
result = api.send_pager_message(6789, "Test alarm message", addresses=["1234567", "7654321"])

# With a delivery-status webhook
result = api.send_pager_message(
    6789,
    "Test alarm message",
    confirmation=True,
    webhook_url="https://your.server/pager-callback",
)

# Poll delivery status
if result:
    status = api.get_pager_message_status(6789, result["id"])
    if status:
        print(status["acknowledgment_state"])  # e.g. "automatic", "manual", "none"

Example script

example.py connects to www.brandweerrooster.nl and runs through the full API surface:

  1. Request OAuth2 tokens
  2. Fetch the most recent incident
  3. Get user availability
  4. Get and set incident response status (uses the most recent incident)
  5. List pagers, send a test message, poll delivery status
  6. Connect to the WebSocket and listen for live incident notifications

Run with environment variables (non-interactive):

FSR_USERNAME=your@email.nl FSR_PASSWORD=secret python example.py

Or interactively (prompts for credentials):

python example.py

Exceptions

Exception When raised
InvalidAuthError Wrong credentials or expired refresh token
ExpiredTokenError Access token expired or revoked — call refresh_tokens()
InvalidTokenError Access token invalid — call refresh_tokens()

Community

Questions, ideas or just want to chat? Join The Junkyard on Discord:

Join The Junkyard on Discord

Metadata

Release files for pyfireservicerota 0.0.50

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyfireservicerota 0.0.50
File Size Uploaded Provenance Actions
pyfireservicerota-0.0.50.tar.gz 19.9 kB Without provenance Details for pyfireservicerota-0.0.50.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyfireservicerota 0.0.50
File Interpreter ABI Platform Actions
pyfireservicerota-0.0.50-py3-none-any.whl Python 3 none any Details for pyfireservicerota-0.0.50-py3-none-any.whl

Total release size: 31.2 kB

Release files / pyfireservicerota-0.0.50.tar.gz

Download URL pyfireservicerota-0.0.50.tar.gz
Size 19.9 kB
Tags Source
SHA-256 checksum
How to use checksums
62030ec89f3c5070db4dae953557e5332f94e117a4aefef3951c119af8b343e8
BLAKE2b-256 checksum
How to use checksums
e2a26509e2e46d457edc0f3b6fc635c248abbacda3dfcc4a69e24b49f6d0761a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Release files / pyfireservicerota-0.0.50-py3-none-any.whl

Download URL pyfireservicerota-0.0.50-py3-none-any.whl
Size 11.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8001d6d4b6e09b3dde113acf6fc619020682fb56b2c67ed9ccbd5f46b6d1c55d
BLAKE2b-256 checksum
How to use checksums
2ad4859d21706bba404f063cde4235f41b9500de082232189b12aab407110eff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for pyfireservicerota 0.0.50

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.50 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page