Oref

Oref – Python interface to Israel’s Home Front Command (Pikud HaOref) emergrncy alert network.

Installation

pip install oref

Python 3.11 + required.

Quick‑start

import oref
from oref.types import Alert

# Load baseline (English) metadata
oref.init()

# Optional – preload extra languages
oref.init(extra_languages=["he", "ar", "ru"])

# One‑off check (all areas)
alert = oref.check_alert()
if alert:
    print(alert)

# Continuous listener (filter to specific areas if desired)

def on_alert(a: Alert):
    print("\n>>> INCOMING:", a)

oref.listen(on_alert, areas=["Jerusalem", 158])

API Synopsis

Initialise

Alerts

Alert functions can be invoked from both oref and oref.alerts.

Data Helpers

Data helpers can be invoked from both oref and oref.loader

Data Structures (oref.types)

• Alert – id, category, title, description, locations, unfiltered_locations; filter_locations(relevant)
• Location – id, area_id, name (Placename), region (Placename), shelter_time
• Guideline – code, area_id, zone_name, label (Placename), time_notes, mode, color_code
• Placename – multilingual string container (en / he / ar / ru)
• AlertTranslation – four‑language mapping plus category metadata

Example – Translate & Filter

from oref import check_alert, translate

alert = check_alert()
if alert:
    # Limit to Be’er Sheva & area‑id 165
    alert.filter_locations(["Be'er Sheva", 165])
    # Convert title/description to Russian
    title_ru, desc_ru = translate(alert, "ru")
    print(title_ru, "::", desc_ru)

Configuration

oref.config exposes endpoint constants (ALERTS_URL, LOCATIONS_URL, GUIDELINES_URL, ALERT_TRANSLATIONS_URL). Override them before calling init() to point at mirrors, proxies, or test fixtures.

Logging

The package emits informative messages via the standard logging module. Example:

import logging, oref
logging.basicConfig(level=logging.INFO)
oref.init()

Caveats

• Unofficial – not endorsed by Pikud HaOref.
• Upstream JSON schemas may change without notice.
• Network polling every second like the official website; adjust in fork if lower bandwidth is essential.

Licence

MIT © 2025