Developer API

Integrate real-time global risk signals and escalation forecasts into your applications.

Quick Start

JSON Feed

curl https://worldnoc.com/api/public/signals

RSS Feed

https://worldnoc.com/feed/global

Public Endpoints (No Auth Required)

These endpoints are free to use with rate limiting. Perfect for prototypes, bots, and integrations.

GET/api/public/signals

Returns the latest global risk signals with escalation data.

Query Parameters

Parameter	Type	Description
limit	integer	Max 100, default 50
since	ISO timestamp	Filter signals after this time
country	string	ISO country code (e.g., US, UA)
region	string	Region filter (e.g., europe, asia)
category	string	Event category (military, cyber, protest...)

Example Response

{
  "signals": [
    {
      "id": "ukraine-conflict",
      "timestamp": "2025-12-09T05:30:00Z",
      "country": "UA",
      "region": "Eastern Ukraine",
      "category": "conflict",
      "headline": "Artillery exchanges intensify near Kharkiv",
      "severity": "high",
      "escalation_probability": 0.72,
      "escalation_state": "Escalating",
      "momentum_24h": 14,
      "source_count": 47
    }
  ],
  "count": 1,
  "total_available": 156,
  "next_since": "2025-12-09T05:30:00Z"
}

GET/api/public/snapshot

Returns aggregated global risk overview with hotspots.

Example Response

{
  "generated_at": "2025-12-09T05:35:00Z",
  "global_risk_index": 73,
  "total_signals": 156,
  "high_severity_count": 23,
  "escalating_count": 18,
  "cooling_count": 7,
  "hotspots": [
    {
      "region_id": "country:ua",
      "name": "Ukraine",
      "current_risk": 82,
      "escalation_probability": 0.74,
      "momentum": 12,
      "signal_count": 34
    }
  ],
  "category_breakdown": {
    "conflict": 45,
    "cyber_attack": 23,
    "civil_unrest": 18
  }
}

GET/api/countries

Returns countries with significant activity in the last N days.

Query Parameters

Parameter	Type	Description
days	integer	Lookback period (1-30, default 1)
sig	string	Min significance: low, medium, high

GET/api/country/:code

Returns detailed signals and advisories for a specific country.

Includes: Active signals, State Dept travel advisory level, OFAC sanctions status.

RSS/feed/global

RSS 2.0 feed of the last 100 signals. Perfect for feed readers, Discord bots, and email bridges.

Custom fields include: worldnoc:severity, worldnoc:escalation_probability, worldnoc:escalation_state, worldnoc:momentum_24h

Signal Data Model

interface Signal {
  id: string;                    // Unique signal identifier
  timestamp: string;             // ISO 8601 timestamp
  country?: string;              // ISO 3166-1 alpha-2 code
  region: string;                // Geographic region/location
  category: string;              // Event category
  headline: string;              // Short description
  severity: "low" | "medium" | "high" | "critical";

  // Escalation Forecasting
  escalation_probability?: number;  // 0.0 - 1.0
  escalation_state?: "Cooling" | "Unstable" | "Escalating" | "Flashpoint";
  momentum_24h?: number;            // -50 to +50 (percentage point change)

  source_count: number;          // Number of sources reporting
}

Escalation States

Cooling

Probability < 25% and momentum declining. Situation stabilizing.

Unstable

Moderate probability, unclear trajectory. Requires monitoring.

Escalating

Probability > 40% with rising momentum. Situation worsening.

Flashpoint

Probability > 75% with strong momentum. Imminent escalation likely.

Paid API v1 (API Key Required)

Authenticated endpoints with higher rate limits, alerts, and advanced features.

Interactive API Reference (Swagger UI)

Authentication

X-API-Key: YOUR_API_KEY

GET/api/v1/signals

Paginated signals with full filtering

GET/api/v1/risk-index

Global and country-level risk indices

GET/api/v1/escalation

Country escalation grid with stability index

CRUD/api/v1/alerts

Create, manage, and delete alert rules (Team+)

# Example: Get signals

curl -H "X-API-Key: YOUR_KEY" https://worldnoc.com/api/v1/signals?limit=10

API Tiers & Rate Limits

Tier	Rate Limit	Alerts	Streaming	Historical
Public	60/min (IP)	-	-	-
Developer	60/min	-	-	7 days
Team	300/min	5 rules	Yes	30 days
Pro	1,000/min	25 rules	Yes	90 days
Enterprise	Custom	Unlimited	Yes	Full archive

Need More?

Enterprise API access includes higher limits, webhooks, custom alerts, and priority support.

Request Enterprise Access