Skip to main content
SA Policy Space

API Documentation

Public read-only API for SA Policy Space data

SA Policy Space exposes a JSON API for researchers, developers, and policy tools. All endpoints are read-only and publicly accessible — no API key required. The canonical, supported surface is the versioned /api/v1/ set below — every response uses the { version, data, meta } envelope. The older unversioned paths are now deprecated and 308-redirect to their /api/v1/ successor.

Constraint filters use canonical database names in responses, but the ideas listing endpoint also normalizes a small set of common aliases in requests to make query construction easier.

Every response is stamped. The meta block on every endpoint below carries data_as_of — the date the underlying idea data was last touched — and data_version, a stable identifier of the data state. Figures here are recomputed from live rows, so a value can move between two calls; record the version alongside anything you publish and the state you read stays citable. Neither field is derived from file timestamps. See the changelog for what has moved and why.

Both fields are additive: existing meta keys such as count, total, limit and offset are unchanged. Endpoints that previously returned no meta at all now return one containing just the stamp.

Data returned by this API is licensed CC BY 4.0 — attribute to “SA Policy Space / Laurence Wilse-Samson”.

OpenAPI 3.0 specification (JSON)

No authentication required
JSON responses
Rate limiting planned for future versions

Base URL

https://sa-policy-space.vercel.app

Versioned Endpoints (v1)

These endpoints follow semver-style versioning. Breaking changes will increment the version prefix.

List policy ideas with optional filtering and sorting. Search covers title, description, theme, source committee, and responsible department.

Parameters

search
query · stringFull-text search across title, description, theme, committee, and department
constraint
query · stringCanonical constraints include energy, transport_logistics, skills_education, regulatory_burden, crime_safety, labour_market, land_housing, digital_infrastructure, government_capacity, and corruption_governance. Common aliases such as logistics, skills, regulation, crime, labor_market, land, digital, and corruption are also accepted.
status
query · stringFilter by status: proposed | debated | drafted | stalled | implemented | partially_implemented | under_review | abandoned
package
query · integerFilter by reform package ID (1–5)
timeHorizon
query · stringFilter by time horizon: quick_win | medium_term | long_term
sort
query · stringSort order: impact (default) | feasibility | recent

Example Request

curl "https://sa-policy-space.vercel.app/api/v1/ideas?constraint=energy&status=implemented"

Example Response

{
  "version": "1",
  "data": [
    {
      "id": 42,
      "title": "Electricity Regulation Amendment Act — Competitive Electricity Market",
      "binding_constraint": "energy",
      "current_status": "implemented",
      "growth_impact_rating": 5,
      "feasibility_rating": 4,
      "reform_package": 1,
      "time_horizon": "medium_term",
      "source_committee": "Mineral Resources and Energy",
      "slug": "electricity-regulation-amendment-act"
    }
  ],
  "meta": {
    "total": 171,
    "count": 123,
    "limit": 200,
    "offset": 0,
    "data_as_of": "2026-08-20",
    "data_version": "2026-08-21.717caff8"
  }
}

Deprecated (unversioned) Endpoints

These legacy paths now issue a 308 permanent redirect to their /api/v1/ successor (query string preserved), with Deprecation, Sunset, and Link headers. fetch() and curl -L follow them automatically. Scheduled for removal after 2026-12-31 — migrate to /api/v1/ before then.

GET/api/ideas→ 308 /api/v1/ideas
GET/api/ideas/:id→ 308 /api/v1/ideas/:id
GET/api/packages→ 308 /api/v1/packages
GET/api/packages/:id→ 308 /api/v1/packages/:id
GET/api/stats→ 308 /api/v1/stats
GET/api/themes→ 308 /api/v1/themes
GET/api/dependency-graph→ 308 /api/v1/dependency-graph

Rate Limits & API Keys

Currently: No rate limits. The API is open and free for research use.

Planned: API key authentication and per-key rate limits will be introduced in a future version to support higher-traffic use cases. Keys will be issued free of charge for academic and policy research.

Data & Attribution

Policy idea data is synthesised from South African parliamentary committee proceedings sourced via the Parliamentary Monitoring Group (PMG). Ideas represent original editorial synthesis — not PMG verbatim text. If you use this data in research or publications, please cite SA Policy Space and PMG as the original source of meeting records.

Browse IdeasAbout the Project