API v1

OpenWatch API

Programmatic access to Nigeria's security incident database. Real-time data, trend analysis, and daily intelligence briefs.

Base URL

https://api.openwatch.ng

Plans

FreeCommunity

20 requests / day

✓Incidents list + detail
✓Trend data (daily / weekly / monthly)
✓Daily intelligence briefs
✓Filter by type, state, date, confidence
✓CORS enabled

No API key required. Rate limited by IP.

Popular

ProDeveloper

$20 / month

✓500 requests / day
✓Everything in Free
✓API key authentication
✓Higher rate limits
✓Priority response times

EnterpriseCustom

Custom pricing

✓Everything in Pro, unlimited requests
✓Raw embedding vectors
✓Webhooks (real-time push on new incidents)
✓Bulk historical export (CSV / JSON)
✓Custom alert filters (region / type / severity)
✓SLA + priority support

Contact dev@trdspc.com

Authentication

The free tier requires no authentication. Simply make GET requests to any endpoint.

Enterprise customers authenticate via API key in the Authorization header:

curl -H "Authorization: Bearer ow_live_YOUR_KEY" \
  https://api.openwatch.ng/incidents

Rate Limiting

Free tier: 20 requests/day per IP. Pro tier: 500 requests/day per API key. Enterprise: unlimited. All limits reset at midnight UTC.

Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per day
X-RateLimit-Remaining	Requests remaining today
Retry-After	Seconds until reset (only on 429)

When you exceed the limit, the API returns 429 Too Many Requests.

Endpoints

GET/incidents

Returns a paginated list of verified security incidents. Results exclude retracted incidents.

Parameters

Name	Type	Description
type	string	Incident type code (see reference below)
state	string	Nigerian state name (case-insensitive)
status	string	breaking, developing, confirmed, or archived
min_confidence	number	Minimum confidence score (0–1)
date_from	string	Start date (YYYY-MM-DD)
date_to	string	End date (YYYY-MM-DD)
sort	string	date (default), confidence, or sources
order	string	desc (default) or asc
page	number	Page number (default 1)
per_page	number	Results per page, max 100 (default 25)

Example

curl "https://api.openwatch.ng/incidents?state=Lagos&type=KDN&per_page=5"

Response

{
  "data": [
    {
      "id": "89e83872-3db8-...",
      "incident_type": "KDN",
      "state": "Lagos",
      "lga": "Ikeja",
      "summary": "Three individuals were kidnapped...",
      "severity": "high",
      "confidence_score": 0.92,
      "status": "confirmed",
      "incident_date": "2026-03-15",
      "source_count": 3,
      "latitude": 6.601,
      "longitude": 3.351,
      "first_reported_at": "2026-03-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 5,
    "total": 42,
    "total_pages": 9
  }
}

GET/incidents/{id}

Returns a single incident with full details and linked source articles.

Parameters

Name	Type	Description
id	uuid	Incident UUID (path parameter)

Example

curl "https://api.openwatch.ng/incidents/89e83872-3db8-4bb0-91c5-0bc5fbc732a1"

Response

{
  "id": "89e83872-3db8-...",
  "incident_type": "KDN",
  "summary": "Three individuals were kidnapped...",
  "confidence_score": 0.92,
  "status": "confirmed",
  ...
  "sources": [
    {
      "added_at": "2026-03-15T10:30:00Z",
      "raw_posts": {
        "text": "Breaking: Gunmen abduct three...",
        "url": "https://example.com/article",
        "author": "Daily Post",
        "published_at": "2026-03-15T09:15:00Z",
        "sources": {
          "name": "Daily Post",
          "type": "news",
          "tier": 1
        }
      }
    }
  ]
}

GET/trends

Returns incident counts aggregated by time period and type. Useful for charts and dashboards.

Parameters

Name	Type	Description
type	string	Filter by incident type code
state	string	Filter by Nigerian state
period	string	daily (default), weekly, or monthly
date_from	string	Start date (YYYY-MM-DD)
date_to	string	End date (YYYY-MM-DD)

Example

curl "https://api.openwatch.ng/trends?period=daily&state=Borno&date_from=2026-03-01"

Response

{
  "data": {
    "period": "daily",
    "series": [
      {
        "date": "2026-03-01",
        "total": 12,
        "by_type": { "TER": 5, "KDN": 3, "BOM": 2, "ARB": 2 }
      },
      {
        "date": "2026-03-02",
        "total": 8,
        "by_type": { "TER": 4, "KDN": 2, "CMV": 2 }
      }
    ]
  }
}

GET/brief

Returns an AI-generated daily intelligence summary. Omit the date parameter to get the most recent brief.

Parameters

Name	Type	Description
date	string	Specific date (YYYY-MM-DD), or omit for latest

Example

curl "https://api.openwatch.ng/brief?date=2026-03-18"

Response

{
  "brief": {
    "brief_date": "2026-03-18",
    "headline": "Borno suffers multiple attacks...",
    "summary": "Today's security incidents in Nigeria...",
    "hotspots": ["Borno", "Kaduna", "Oyo"],
    "threat_level": "critical",
    "incident_count": 20,
    "fatality_count": 434,
    "top_types": [
      { "type": "TER", "count": 10 },
      { "type": "KDN", "count": 4 }
    ],
    "key_developments": ["..."],
    "generated_at": "2026-03-18T17:16:36Z"
  }
}

Incident Types

Code	Type
KDN	Kidnapping
ARB	Armed Robbery
TER	Terrorism
BOM	Bombing
CMV	Communal Violence
PRT	Protest
SCM	Scam / Fraud
ASN	Assassination
CTR	Cattle Rustling
PIR	Piracy
MSP	Missing Person
OTH	Other

Statuses

breakingdevelopingconfirmedarchivedretracted

Errors

Status	Meaning
200	Success
401	Invalid API key
404	Resource not found
405	Method not allowed (only GET supported)
429	Rate limit exceeded
500	Internal server error

Error Response

{ "error": "Rate limit exceeded", "limit": 20, "resets": "midnight UTC" }