pikud-haoref-alerts

Pikud HaOref アラート API

このスキルでは、Pikud HaOref（イスラエルの国内防衛司令部）のアラートシステムを利用するために必要な情報を、公式の生エンドポイントからコミュニティ製ラッパーライブラリ、デプロイ戦略まで幅広く解説します。

詳しいリファレンス資料については、references/ ディレクトリをご覧ください。

• references/community-libraries.md — Node.js、Python、C#、Docker のラッパーライブラリ
• references/mcp-and-homeassistant.md — AI 連携用の MCP サーバー、Home Assistant のセットアップ
• references/common-patterns.md — ポーリングループ、通知ボット、ダッシュボード、マップ、過去データのアーカイブ、複数拠点の監視、スマートホーム、アクセシビリティ
• references/alternative-data-sources.md — Tzofar（tzevaadom.co.il）API、oref から Tzofar へのカテゴリ対応表、コミュニティのアーカイブプロジェクト

重要な制約：地域によるブロック

公式の oref.org.il API は、イスラエル国外の IP アドレスをブロックする場合があります。予期しない 403 エラーの最も一般的な原因です。このブロックは CDN/Akamai によるものとみられ、イスラエル国外の IP すべてに一貫して適用されるとは限りません。プロキシの構築を始める前に、まずエンドポイントを試してください。Tzofar（tzevaadom.co.il）のエンドポイントは地域によるブロックがなく、どの IP からでも利用できます。

ブロックされた場合の回避策： GCP の me-west1（テルアビブ）VM にデプロイしてください。注：e2-micro は me-west1 では無料利用枠の対象外です（無料利用枠は一部の米国リージョンに限定されています）が、イスラエルの IP を利用できる最も安価な選択肢です。

gcloud compute instances create pikud-haoref \
  --zone=me-west1-a \
  --machine-type=e2-micro \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --tags=http-server

gcloud compute firewall-rules create allow-pikud-haoref \
  --allow=tcp:8000-8002 --target-tags=http-server

---

公式エンドポイント

Pikud HaOref は正式な API ドキュメントを公開していません。以下のエンドポイントは公式ウェブサイトとモバイルアプリからリバースエンジニアリングされたもので、長年にわたり安定して動作しています。JSON を返します（UTF-8 BOM が付くことがあり、その場合は取り除く必要があります）。

リアルタイムアラート

GET https://www.oref.org.il/warningMessages/alert/alerts.json

現在有効なアラートを返します。アラートが有効でない場合は空のレスポンスを返します。ポーリングが必要です。通常、リアルタイム性を保つには 1～2 秒間隔でポーリングします。

重要：これはスナップショットであり、状態確認ではありません。 アラートはサイレンが鳴っている間だけ（通常は数秒から 1 分間）、このエンドポイントに表示されます。レスポンスが空でも「すべて解除」を意味するわけではなく、現在サイレンが鳴っていないことを示すだけです。状況が引き続き有効かどうかを判断するには、履歴エンドポイントも確認し、カテゴリ 13 の「イベント終了」メッセージに該当するものがないことを確かめる必要があります（下記の状況が引き続き有効かどうかの判断を参照）。

アラートが有効な場合のレスポンス：

{
  "id": "134168709720000000",
  "cat": "1",
  "title": "ירי רקטות וטילים",
  "data": ["תל אביב - מרכז העיר", "רמת גן - מערב"],
  "desc": "היכנסו למרחב המוגן ושהו בו 10 דקות"
}

フィールド：

• id — アラートの一意な識別子（数値文字列）。重複排除に使用できます。
• cat — カテゴリ番号（下記のアラートカテゴリを参照）。
• title — ヘブライ語で表記された、アラートの種類を示す人間が読めるテキスト。
• data — 影響を受ける場所の名前（ヘブライ語）の配列。
• desc — ヘブライ語で記載された防護指示。

アラートがない場合のレスポンス： 空の本文（BOM のみの場合もあります）。

推奨ヘッダー： このエンドポイントは特別なヘッダーがなくても動作しますが、ブラウザーに似たヘッダーを送信すると、ブロックされる可能性を低減できます。

Referer: https://www.oref.org.il/
X-Requested-With: XMLHttpRequest

警報履歴（JSON ファイル — 高負荷時は信頼性が低下）

GET https://www.oref.org.il/warningMessages/alert/History/AlertsHistory.json

直近の警報を返します。ページネーションはなく、レコード数は最大 3,000 件に制限されています。活動が少ない期間であれば数週間分を含む場合がありますが、激しい紛争の最中には 1 日で 3,000 件を超えることがあります（例：事前警報 1,147 件＋ミサイル警報 483 件＋航空機 22 件＋終了通知 1,348 件＝ちょうど 3,000 件）。ポーリングの合間に見逃した可能性のある警報を確認するのに便利ですが、緊張が高まる時期の過去データ分析には信頼できません。

高負荷時の劣化： 大量のデータが発生する期間（紛争が進行中など）には、AlertsHistory.json が HTTP 200 を返しながら本文が空（約 2 バイト）になることがあります。一方、GetAlarmsHistory.aspx は完全なデータ（600KB 以上）を返し続けます。履歴データの主な取得元には GetAlarmsHistory.aspx を使用し、AlertsHistory.json はフォールバックとして扱ってください。

重要： /alert/ セグメントを含まないパス（例：/warningMessages/History/AlertsHistory.json）は 403 を返します。パスの大文字・小文字は区別されません。/WarningMessages/ と /warningMessages/ のどちらも機能しますが、/alert/ セグメントは必須です。

レスポンス形式：

[
  {
    "alertDate": "2024-10-15 14:32:00",
    "title": "ירי רקטות וטילים",
    "data": "אשדוד - א,ב,ד,ה",
    "category": 1
  }
]

ここでの data は文字列（リアルタイムのエンドポイントのような配列ではありません）であり、category は数値（文字列ではありません）であることに注意してください。

警報履歴（推奨）

GET https://alerts-history.oref.org.il/Shared/Ajax/GetAlarmsHistory.aspx?lang=he&mode=1

専用サブドメイン上の ASP.NET エンドポイントで、matrix_id、rid、category_desc フィールドを含む、より詳細な履歴データを返します。フォールバックとして、または追加のメタデータが必要な場合に便利です。lang=he（ヘブライ語）と lang=en（英語）に対応しています。

同じく 3,000 件の上限が適用されます。 mode パラメーターは 1～3 の値を受け付けます（4～5 を指定すると空のレスポンスが返ります）が、どのモードでも直近の 3,000 件が返されます。日付範囲を指定するクエリパラメーターには対応していません。これはページネーションの仕組みではありません。

履歴エンドポイント間の日付形式の違い：

• AlertsHistory.json："alertDate": "2026-03-06 19:33:53"（秒を含む、スペース区切り）
• GetAlarmsHistory.aspx："alertDate": "2026-03-06T19:35:00"（ISO 8601 の T 区切り。秒は常に :00）

警報カテゴリ

GET https://www.oref.org.il/alerts/alertCategories.json

id、category（文字列のスラッグ）、matrix_id、priority、queue フィールドを含むオブジェクトとして、カテゴリのメタデータを返します。注：レスポンスには、カテゴリ番号とヘブライ語名の対応関係が直接含まれていません。以下の表は、このエンドポイントだけに基づくものではなく、ライブの警報データを観察して作成したものです。既知のカテゴリは次のとおりです。

カテゴリ	種類	ヘブライ語
1	ミサイル／ロケット	ירי רקטות וטילים
2	敵対航空機の侵入	חדירת כלי טיס עוין
3	地震	רעידת אדמה
4	津波	צונאמי
5	放射線事象	אירוע רדיולוגי
6	危険物	חומרים מסוכנים
7	テロリストの侵入	חדירת מחבלים
13	事象の終了	האירוע הסתיים
14	事前警報／警報到達予告	בדקות הקרובות צפויות להתקבל התרעות באזורך

カテゴリ 101～107 は、カテゴリ 1～7 に対応する訓練用のカテゴリです。

カテゴリ 13：事象の終了

Pikud HaOref が特定の地域への脅威は去ったと判断すると、タイトルが「האירוע הסתיים」（事象は終了しました）または「ניתן לצאת מהמרחב המוגן」（防護区域から出てもかまいません）のカテゴリ 13 の警報を送信します。これは、特定の警報事象が終了したことを示す正式なシグナルです。履歴エンドポイントには、地域ごとに表示されます。

カテゴリ 14：事前警報（警報到達予告）

「בדקות הקרובות צפויות להתקבל התרעות באזורך」（今後数分以内に、お住まいの地域で警報が発令される見込みです）というタイトルのカテゴリ 14 の警報は、特定の地域で今後数分以内に警報が発令される見込みであることを知らせます。これは一斉攻撃が迫っていることを示す早期警報であり、標準的な避難時間のカウントダウンに加えて、準備時間を確保するのに役立ちます。事前警報の後、約 20 分以内に実際の警報（カテゴリ 1～7）に移行しない場合は、期限切れと見なすことができます。

事前警報と実際の警報の照合

よくある分析タスクとして、どの事前警報（cat 14）が実際の警報（cat 1–7）にエスカレートしたかを判断することがあります。課題は、カテゴリ間で場所の文字列が常に一致するとは限らず、1件の事前警報に続いて複数の警報が発生する場合もあることです。

from datetime import timedelta

def match_prealerts_to_alerts(history, source="oref_history", window_minutes=20):
    """Match cat 14 pre-alerts to subsequent cat 1-7 alerts by location overlap.

    Uses normalize_alert_time() for proper datetime comparison.
    Returns list of (prealert, [matching_alerts]) tuples.
    """
    prealerts = [e for e in history if e.get("category") == 14]
    alerts = [e for e in history if e.get("category") in (1, 2, 3, 4, 5, 6, 7)]
    window = timedelta(minutes=window_minutes)
    matches = []

    for pa in prealerts:
        pa_time = normalize_alert_time(pa["alertDate"], source)
        pa_locations = pa.get("data", "")
        matched = []
        for a in alerts:
            a_time = normalize_alert_time(a["alertDate"], source)
            if a_time <= pa_time or a_time > pa_time + window:
                continue
            a_locations = a.get("data", "")
            # Token overlap: handles partial location name matches
            pa_words = set(pa_locations.replace(",", " ").split())
            a_words = set(a_locations.replace(",", " ").split())
            if pa_words & a_words:
                matched.append(a)
        matches.append((pa, matched))

    return matches

注記： cat 14 と cat 1 の場所の文字列は、常に完全に一致するとは限りません。cat 14 ではゾーン名や地域名が使われることが多い一方、cat 1 では具体的な都市名が使われます。完全一致よりも、部分文字列やトークンの重複による照合のほうが効果的です。20分の時間枠は、事前警報から警報へのエスカレーションにかかる標準的な時間を反映しています。確認されたパターンに応じて調整してください。

状況がまだ継続中かどうかを判断する

alerts.json が空であることだけを根拠にしないでください。 リアルタイムエンドポイントは狭い範囲のスナップショットであり、警報は数秒以内に消えます。適切な方法は、次の2つを組み合わせて確認することです。

1. その時点のスナップショットとして alerts.json を確認する（今、サイレンが鳴っていますか？）
2. その場所について、最近の cat 1–7 の警報があるか 履歴エンドポイントを確認する
3. その場所で警報の後に cat 13 の「イベント終了」が届いているか確認する
4. cat 13 がまだ届いていない場合 → 状況は継続中です

def is_situation_active(location_hebrew, history):
    """Check if a location still has an active alert (no cat 13 received yet)."""
    last_alert_time = None
    last_concluded_time = None

    for entry in history:
        if location_hebrew not in entry.get("data", ""):
            continue
        cat = entry.get("category", 0)
        alert_time = entry.get("alertDate", "")
        if cat in (1, 2, 3, 4, 5, 6, 7):
            if last_alert_time is None or alert_time > last_alert_time:
                last_alert_time = alert_time
        elif cat == 13:
            if last_concluded_time is None or alert_time > last_concluded_time:
                last_concluded_time = alert_time

    if last_alert_time is None:
        return False  # no recent alert
    if last_concluded_time is None:
        return True   # alert with no conclusion yet
    return last_alert_time > last_concluded_time  # alert after last conclusion

履歴データの戦略

公式の両履歴エンドポイントには3,000件の上限があるため、対象期間に応じて異なるデータソースが必要です。

必要なデータ	データソース	注記
直近数分	alerts.json（リアルタイム）	1～2秒ごとにポーリング
直近約3,000件（全カテゴリ）	AlertsHistory.json または GetAlarmsHistory.aspx	事前警報と終了通知を含みます。活動状況に応じて数時間から数週間分です
直近50件の警報グループ（事前警報なし）	api.tzevaadom.co.il/alerts-history	地理的ブロックなし
数か月／数年分（事前警報なし）	Tzofar の警報グループ ID をさかのぼって順に取得	地理的ブロックなし。レート制限に注意してください（references/alternative-data-sources.md を参照）
事前警報を含む完全な履歴	独自の継続的なポーリングシステム	遡及取得できるデータソースはありません — 必要な期間が始まる前から稼働させる必要があります

事前警報の履歴データに関する空白（重大な制限）： 事前警報データ（cat 14）やイベント終了メッセージ（cat 13）を遡及取得できるデータソースはありません。Tzofar ではこれらは完全に除外されています。公式の oref 履歴エンドポイントには含まれていますが、3,000件に制限されています。紛争が活発な時期には、この3,000件が数時間分しかカバーしない場合があります。過去の事前警報データが必要な場合は、分析対象期間が始まる前に、必ず独自の継続的なポーリングシステムを設定してください。 後からこのデータを復元する方法はありません。コミュニティのアーカイブ（hasadna、Meir017）にも、各アーカイブのスクレーパーが事前警報を取得していない限り、事前警報は含まれていません。

oref と Tzofar のデータの組み合わせ： 複数日にわたる紛争を分析する場合は、通常、両方のデータソースが必要です。データを揃える際の重要な点は次のとおりです。（1）タイムスタンプを正規化します。oref はイスラエル現地時間の文字列を使用し、Tzofar は Unix タイムスタンプ（UTC）を使用します。（2）脅威の種類を対応づけるには、references/alternative-data-sources.md のカテゴリ対応表を使用します。（3）両方のデータソースが同じ警報を報告しているため、タイムスタンプと都市名を照合して重複を排除します。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo  # stdlib in Python 3.9+

IST = ZoneInfo("Asia/Jerusalem")  # handles DST automatically

def normalize_alert_time(raw, source):
    """Normalize any alert timestamp to a Python datetime in Israel time.

    source: 'oref_history' | 'oref_aspx' | 'tzofar'
    """
    if source == "oref_history":
        # "2026-03-07 19:33:53" (space-separated, Israel local time)
        return datetime.strptime(raw, "%Y-%m-%d %H:%M:%S").replace(tzinfo=IST)
    elif source == "oref_aspx":
        # "2026-03-07T19:35:00" (ISO T-separator, Israel local time)
        return datetime.strptime(raw, "%Y-%m-%dT%H:%M:%S").replace(tzinfo=IST)
    elif source == "tzofar":
        # Unix timestamp (UTC)
        return datetime.fromtimestamp(raw, tz=timezone.utc).astimezone(IST)

oref のカテゴリと Tzofar の脅威の対応づけ： 両方のデータソースを扱う際は、数値 ID が異なる点に注意してください。完全な対応表は references/alternative-data-sources.md を参照してください。

---

生のエンドポイントとライブラリの使い分け

基本的には生のエンドポイントを使用してください。 公式の JSON ファイルはシンプルで安定しており、十分に理解されています。警報のポーリング、履歴の確認、通知サービスの構築など、ほとんどのユースケースでは、HTTP リクエストを直接送信するだけで十分です。

自分で保守する必要のあるデータを提供する場合は、ライブラリを利用してください。 最も一般的な理由は cities.json データベースです。ヘブライ語、英語、ロシア語、アラビア語の名称、GPS 座標、ゾーンの対応関係、避難所までの所要時間を含む約1,500か所のデータがあります。各ライブラリの詳細については references/community-libraries.md を参照してください。

地域別のクエリ

特定の都市や地域で警報が発令されているかを確認するのは、非常によくあるユースケースです。課題は、公式 API から返される地名がヘブライ語である一方、ユーザーは英語やヘブライ語の音訳で尋ねることが多い点です。

都市データベース

pikud-haoref-api Node.js ライブラリには、警報対象となるすべての地域を対応付けた包括的な cities.json ファイルが含まれています（https://github.com/eladnava/pikud-haoref-api から入手できます）。各エントリには次の情報があります。

{
  "id": 511,
  "name": "אבו גוש",
  "name_en": "Abu Ghosh",
  "name_ru": "Абу Гош",
  "name_ar": "أبو غوش",
  "zone": "שפלת יהודה",
  "zone_en": "Judean Lowlands",
  "lat": 31.80686,
  "lng": 35.11038,
  "countdown": 90,
  "value": "אבו גוש"
}

主なフィールド： マッチングには name／name_en、地域別のクエリには zone／zone_en、避難所までの時間（秒）には countdown、近接検索や地図には lat／lng、警報の data 配列とのマッチングには value を使用します。

マッチング戦略

data 配列内の警報対象地域名は、都市名と完全には一致しないことがあります。たとえば、地域名が "תל אביב" ではなく "תל אביב - מרכז העיר" として表示されることがあります。次の 3 つの戦略があります。

1. 部分文字列マッチング — "תל אביב" in "תל אביב - מרכז העיר" → True。シンプルで、多くの場合に有効です。
2. ファジーマッチング — fuzzywuzzy などをしきい値約 60〜70 で使用します。音訳の違いに対応できます。
3. ゾーンベースのマッチング — より広域のクエリには zone／zone_en と照合します。

英語名からヘブライ語名への解決

ユーザーが都市名を英語で尋ねた場合、ヘブライ語の value に解決します。

• cities.json での検索 — name_en を検索します。最も信頼性の高い方法です。
• 英語名のファジー検索 — "Gan Hayim"、"Gan Chaim"、"Gan Hayyim" はすべて → גן חיים。
• 多言語対応 — name_ru と name_ar も利用できます。

近接検索

都市データベースの lat／lng 座標を使用します。

from math import radians, cos, sin, asin, sqrt

def haversine(lat1, lon1, lat2, lon2):
    """Distance in km between two GPS coordinates."""
    lat1, lon1, lat2, lon2 = map(radians, [lat1, lon1, lat2, lon2])
    dlat, dlon = lat2 - lat1, lon2 - lon1
    a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
    return 2 * 6371 * asin(sqrt(a))

def cities_near(lat, lon, radius_km, cities_db):
    return [c for c in cities_db
            if haversine(lat, lon, c["lat"], c["lng"]) <= radius_km]

避難所までの時間

各地域には countdown 値（秒）があります。0 秒（ガザ近郊の境界地域）から 90 秒までの範囲です。地域別の警報を報告する際は、必ずこの値を含めてください。命を守るために重要な情報です。

---

例

例 1：「ロケット警報を知らせる Telegram ボットを作って」

• 地域制限について最初に説明します
• references/common-patterns.md のポーリングループパターンを使用します
• on_new_alert コールバックに Telegram の sendMessage を追加します
• GCP の me-west1 へのデプロイを提案します
• 結果：Telegram チャットに警報を送信する、動作するボット

例 2：「今、アシュケロンで警報は出ていますか？」

• cities.json を読み込みます。アシュケロンには、「Ashkelon - North」（אשקלון - צפון）と「Ashkelon - South」（אשקלון - דרום）のサブエリアがあり、それぞれの避難までの時間は30秒です
• 二重チェック：alerts.json をポーリングし、直近のカテゴリー1～7の警報に対応するカテゴリー13の警報がないか履歴も確認します
• アラートの data フィールドで「אשקלון」を部分一致検索し、すべてのサブエリアを対象にします
• アシュケロンの避難までの時間（30秒）を含めて結果を報告します
• alerts.json が空でも、履歴にカテゴリー13の警報がない直近の警報がある場合は、状況はまだ続いています

例 3：「リアルタイム警報マップのダッシュボードをセットアップして」

• サーバー側：ポーリングループ → SSE または WebSocket で配信します（references/common-patterns.md を参照）
• クライアント側：Leaflet.js と OpenStreetMap を使い、cities.json の座標をもとにマーカーを表示します
• ゾーンと避難までの時間のデータをマーカーに追加します
• ブラウザーから oref.org.il を直接ポーリングしないでください

例 4：「警報を Home Assistant に統合して」

• oref_alert HACS 統合を案内します（references/mcp-and-homeassistant.md を参照）
• HA の自宅の位置情報をもとに自動設定します
• sensor.oref_alert と _time_to_shelter のエンティティを提供します
• よく使われる自動化：照明を点滅させる、ドアを施錠する、メディアを一時停止する、スピーカーでアナウンスする

例 5：「紛争の直近1週間の警報パターンを分析して」

• 最初に確認します：事前警報（カテゴリー14）が必要ですか？ 必要な場合は、独自のポーリングアーカイブが必要です。遡及的に取得できるソースはありません
• 実際の脅威に関する警報のみが対象の場合は、Tzofar の警報グループ ID を新しい順にさかのぼって調べ、保守的な間隔（1～2秒）を空けます
• 最新データ（3,000件以内の場合）には、すべてのカテゴリーを含む GetAlarmsHistory.aspx を使用します
• references/alternative-data-sources.md のカテゴリー対応表を使い、Tzofar と oref のデータを共通のスキーマに正規化します
• 地理的な分析のため、座標については cities.json を、ゾーンのデータについては zone data を使って情報を補完します

---

注意点とトラブルシューティング

1. UTF-8 BOM — 公式エンドポイントは、JSON の前に BOM（\ufeff）を返すことがあります。必ず取り除いてください：text.lstrip('\ufeff')。
2. 空の応答と警報なしの違い — 応答本文が空の場合、アクティブな警報はありません。JSON として解析しないでください。
3. 履歴データの破損 — 履歴エンドポイントは、不正な形式の JSON を返すことがあります。数秒待ってから再試行してください。
4. レート制限 — リアルタイムで確認する場合は、1～2 秒ごとにポーリングしてください。それより頻繁にしても効果はなく、アクセスをブロックされる可能性があります。
5. ヘブライ語のエンコーディング — すべての地名と説明はヘブライ語です。スタック全体で UTF-8 を使用してください。
6. 複数の警報の同時発生 — 大規模な弾幕攻撃の間は、複数の種類の警報が同時に有効になることがあります。単一の警報を前提とせず、配列を処理できるようにしてください。
7. 訓練警報 — カテゴリ 101～107 は訓練用です。特に必要な場合を除き、除外してください。
8. 履歴レコードの上限 3,000 件 — AlertsHistory.json と GetAlarmsHistory.aspx はどちらも、ページネーションや日付範囲による絞り込みがなく、レコード数は 3,000 件に固定されています。2026 年 3 月の紛争中、3,000 件は約 97 分で上限に達しました（事前警報 854 件＋ミサイル 480 件＋航空機 38 件＋終了済み 1,628 件）。GetAlarmsHistory.aspx の mode=1,2,3 パラメーターはページネーションを提供しません。すべてのモードで同じ直近 3,000 件が返されます（mode=4,5 は空を返します）。より長期間の履歴が必要な場合は、Tzofar のアーカイブまたはコミュニティのポーラーを使用してください（references/alternative-data-sources.md を参照）。
9. イスラエルのタイムゾーン — oref のタイムスタンプはすべてイスラエルの現地時刻です（Asia/Jerusalem — DST を自動処理するには zoneinfo.ZoneInfo("Asia/Jerusalem") を使用してください）。Tzofar は Unix タイムスタンプ（UTC）を使用します。ソースを組み合わせたり日ごとにグループ化したりする場合は、まず一貫したタイムゾーンに正規化してください。
10. 403 Forbidden — よくある原因は 2 つあります：（a）ジオブロッキング — イスラエルの IP（GCP me-west1）からデプロイするか、プロキシを使用してください。ただし、イスラエル以外のすべての IP が一貫してブロックされるわけではありません。（b）/alert/ パスセグメントの欠落 — たとえば、/warningMessages/History/AlertsHistory.json は 403 を返しますが、/warningMessages/alert/History/AlertsHistory.json は機能します。パスの大文字と小文字は区別されません。