Home PublishersDeveloper Documentation

API Reference

Getting Started

The Tenders-SA API is a public JSON-based REST API that provides the raw data driving our interactive widgets. It is designed for developers who want to build custom data visualisations, internal reporting tools, or integrated procurement feeds for their industry-specific communities.

Base URL

https://www.tenders-sa.orgProduction

Authentication

The widget APIs are currently **public** and do not require API keys or OAuth authentication. This is to encourage open data syndication across the SA procurement ecosystem.

GET

/api/widgets/sector-trends

Retrieves aggregated tender value and volume data grouped by industrial sector.

Request Parameters

Param	Type	Description
category	string	Filter by specific category slug.
province	string	Filter by province slug (e.g., gauteng).
limit	number	Number of sectors to return (default: 8).

Code Example

fetch('https://www.tenders-sa.org/api/widgets/sector-trends?limit=5')
  .then(response => response.json())
  .then(data => console.log(data));

Sample Response

{
  "data": [
    {
      "sector": "Construction & Infrastructure",
      "tenderCount": 145,
      "totalValue": 2450000000,
      "trend": "up"
    },
    {
      "sector": "ICT & Technology",
      "tenderCount": 89,
      "totalValue": 850000000,
      "trend": "up"
    }
  ],
  "meta": {
    "generatedAt": "2025-03-05T10:00:00Z"
  }
}

GET

/api/widgets/top-companies

Returns a leaderboard of companies with the highest total award values.

Request Parameters

Param	Type	Description
province	string	Filter by province slug.
category	string	Filter by category slug.
limit	number	Number of companies (default: 5, max: 10).
year	number	Filter by award year.

Code Example

fetch('https://www.tenders-sa.org/api/widgets/top-companies?province=gauteng&limit=5')
  .then(response => response.json())
  .then(data => console.log(data));

Sample Response

{
  "data": [
    {
      "rank": 1,
      "supplierName": "Build-IT Solutions",
      "totalValue": 500000000,
      "contractCount": 12,
      "province": "Gauteng"
    }
  ],
  "meta": {
    "province": "gauteng",
    "category": "all",
    "generatedAt": "2025-03-05T10:00:00Z"
  }
}

GET

/api/widgets/winners-feed

A live feed of the most recent tender awards across all sectors.

Request Parameters

No parameters available for this endpoint.

Code Example

fetch('https://www.tenders-sa.org/api/widgets/winners-feed')
  .then(response => response.json())
  .then(data => console.log(data));

Sample Response

{
  "data": [
    {
      "id": "award_123",
      "supplierName": "Siyaya Consulting",
      "amount": 1200000,
      "date": "2025-03-04T15:30:00Z",
      "orgName": "Dept of Health",
      "province": "Limpopo"
    }
  ],
  "generatedAt": "2025-03-05T10:00:00Z"
}

Rate Limiting

To ensure high availability and fair usage for all publishers, we enforce standard rate limits on public API endpoints. If you exceed these limits, our servers will return a 429 Too Many Requests response.

Default Limit

Requests / Minute

Response Headers

X-RateLimit-Limit

The maximum number of requests allowed per minute.

X-RateLimit-Remaining

The number of requests remaining in the current window.

Error Codes

Code	Message	Description & Resolution
400	Bad Request	The request contains invalid parameters or is missing required information. Resolution: Check that all query parameters match the types and constraints listed in the documentation.
404	Not Found	The requested resource or endpoint does not exist. Resolution: Verify the endpoint path is correct.
429	Too Many Requests	You have exceeded the rate limit for this endpoint. Resolution: Wait for the cooling period or reduce the frequency of your requests.
500	Internal Server Error	An unexpected error occurred on our servers. Resolution: Wait a few minutes and try again. If the issue persists, contact developer support.

Changelog

v1.0.02025-03-05

•Initial release of public widget APIs.
•Support for Sector Trends, Top Companies, and Winners Feed.
•Added province and category filtering to relevant endpoints.

Packages & SDKs

We are developing official wrappers for popular frameworks to make integration even faster. Follow our GitHub to be notified when they are released.

@tenderssa/widget-reactComing Soon

@tenderssa/widget-vueComing Soon

No-Code Hub

Want to connect tender data to your CRM, Google Sheets, or Slack without writing code? Our upcoming Zapier and Make apps will let you automate everything.