Developers

Public API

Machine-readable access to INGO Advisory's deduplicated Africa intelligence feed and country risk ratings, so the platform can serve as data infrastructure rather than only a website.

Overview

Two read-only endpoints are published under /api/public/v1: a deduplicated intelligence feed and a per-country risk ratings summary. Both return JSON by default; the feed also supports CSV. A full machine-readable description is published as an OpenAPI 3.1 document.

GET /api/public/v1/feed

Returns published, deduplicated intelligence records ordered by most recent event first.

Parameter	Type	Description
country	string (repeatable or CSV)	Filter by country name, e.g. country=Somalia,Kenya
region	string	Substring match against country or location.
category	string	Intelligence category.
minSeverity	low \| moderate \| high \| critical	Severity floor.
layer	integer 1-6	Collection layer (L1 conflict … L6 verification).
since	ISO date-time	Only events at or after this time.
q	string	Free-text search across title and summary.
page	integer, default 1	Page number.
pageSize	integer, default 40, max 100	Records per page.
format	json \| csv, default json	Response format.

Example request

curl "https://www.ingoadvisory.com/api/public/v1/feed?country=Somalia&minSeverity=high&pageSize=20"

Example response

{
  "data": [
    {
      "id": "8f2c...",
      "title": "Security incident reported in Mogadishu",
      "summary": "…",
      "category": "security",
      "severity": "high",
      "country": "Somalia",
      "location": "Mogadishu",
      "lat": 2.0469,
      "lng": 45.3182,
      "event_at": "2024-05-01T09:30:00Z",
      "source": "ACLED",
      "source_url": "https://…",
      "layer": { "code": "L1", "name": "Conflict & armed groups" },
      "verification": { "score": 62, "level": "Probable" }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 134,
    "generated_at": "2024-05-02T08:00:00Z",
    "licence": "Free for non-commercial and humanitarian use with attribution …",
    "attribution": "INGO Advisory, https://www.ingoadvisory.com"
  }
}

CSV

Pass format=csv to receive the same page of records as text/csv, suitable for spreadsheets and BI tools:

curl "https://www.ingoadvisory.com/api/public/v1/feed?format=csv&pageSize=100" -o feed.csv

GET /api/public/v1/countries

Returns each country's current overall risk level together with its per-domain ratings (political, security, economic, and so on) and the date the rating was last reviewed.

Example request

curl "https://www.ingoadvisory.com/api/public/v1/countries"

Example response

{
  "data": [
    {
      "country_code": "SO",
      "country_name": "Somalia",
      "region": "Horn of Africa",
      "overall_risk_level": "high",
      "last_reviewed_at": "2024-04-28T00:00:00Z",
      "domains": [
        { "domain": "security", "level": "high", "score": 78, "updated_at": "2024-04-28T00:00:00Z" }
      ]
    }
  ],
  "meta": {
    "total": 45,
    "generated_at": "2024-05-02T08:00:00Z",
    "licence": "Free for non-commercial and humanitarian use with attribution …",
    "attribution": "INGO Advisory, https://www.ingoadvisory.com"
  }
}

OpenAPI specification

A hand-written OpenAPI 3.1 document describing both endpoints is served at /api/public/v1/openapi.json. Use it to generate typed clients or import it into API tooling.

Fair use

These endpoints are offered as a public service without a formal service level agreement. Please cache responses on your side, keep polling to a sensible interval (the feed changes on the order of minutes, not seconds), and back off if you receive errors. Requests that place undue load on the service may be rate-limited or blocked.

Attribution and licence

Data from these endpoints is free to use for non-commercial and humanitarian purposes provided that any use is attributed to INGO Advisory, https://www.ingoadvisory.com.

Commercial use — including redistribution as part of a paid product or service — requires a separate agreement. Please get in touch to discuss terms.