API v1 / private beta

Market data, with its context intact.

Read product and market lookups, individual price observations, and daily trends. Start in the sandbox, then request a reviewed production pilot.

Create sandbox application Technical reference as text

Authenticate with an application key

Send exactly one authentication header over HTTPS. Session login manages the console; it does not authenticate API requests.

Authorization: Bearer <api-key>

Keys use tb_test_ or tb_live_, followed by a public key ID, a dot and a secret. Save the full key once at creation. Never place it in a URL or frontend bundle. Rotate or revoke it from the application’s credentials section.

prices:read: Price observations and product/market lookups
trends:read: Daily trends with exact observation context

First request

A small query. A clear response.

Read documentation

Set your key in your local environment. The example uses a placeholder, never a saved credential.

export TANGABID_API_KEY="your_key_here"
curl --fail-with-body \
  -H "Authorization: Bearer $TANGABID_API_KEY" \
  "http://www.tangabid.com/api/v1/market-intelligence/prices/?from=2026-11-01&to=2026-11-13"

Choose observation dates within your permitted range. An empty result means there are no matching observations; dates are never silently substituted.

Available resources

http://www.tangabid.com/api/v1/market-intelligence/

GET-only customer endpoints
Resource	Returns	Scope
`products/`	Paginated product ID and name	`prices:read`
`markets/`	Paginated market ID, name and region	`prices:read`
`prices/`	Individual observations with prices, dates and provenance	`prices:read`
`trends/`	Daily average, minimum, maximum, sample count and latest update	`trends:read`

No customer write, ingestion, forecasting or synchronous full-dataset export endpoint is provided. metadata/ is reserved for internal sync; use the paginated lookups.

Allowlisted filters

Prices require from and to dates, inclusive in Africa/Kigali, in YYYY-MM-DD format. The maximum window is 366 days.

Price query parameters
Parameter	Meaning
`from, to`	Required observation-date bounds
`commodity`	Positive product ID from products/
`market`	Positive market ID from markets/
`district`	Exact case-insensitive match on stored market region; this field may contain a province fallback
`updated_since`	Inclusive record-change timestamp, ISO 8601 with a timezone; prices only
`page_size`	Positive integer, bounded by the key’s plan; defaults to that maximum

Daily trends

Provide from, to, commodity, market, source and every context field: unit, currency, channel, variety, grade. An explicit empty value means unknown. Source IDs are returned with observations. updated_since is not accepted for trends.

A trend window must fit the key’s page limit in days. Request successive date windows; trends have no continuation cursor. Products and markets accept no initial filters or custom sorting.

Follow the returned next link

Products, markets and prices return results and a relative next URL, or null when finished. Follow next on the same origin with the same Authorization header. Supply its cursor alone; do not append new filters. Cursors are signed, tied to the key, and expire after one hour. Prices also return sync_started_at.

A price scan has a bounded starting maximum ID, not a transactional snapshot. Related metadata edits and deletions require periodic reconciliation. See the technical reference for incremental-sync overlap guidance.

Price observation fields

Each observation includes id, observation_date, observed_at, commodity (id/name), market (id/name), district, price, currency, unit, variety, grade, channel, source (id/name) and updated_at.

price is a decimal string, preserving precision; parse it as a decimal. channel is the observation’s price type (farmgate, wholesale or retail), separate from the location type. Unknown observation context is null. Missing observations are absent rows, never synthetic zeros.

Daily trends return day, average, minimum, maximum, samples and latest_update, alongside the exact context. These decimal aggregates are strings too.

Current beta limits

Server-configured limits; subject to change
Plan	Requests/minute	Requests/UTC day	Records/page
Sandbox	10	500	25
Pilot	30	5000	100

Up to 2 concurrent requests per key and 8 across the API. Responses are bounded to 256 KiB.

Sandbox keys always use sandbox limits. Cache hits and admitted validation failures count toward quotas. Daily counters reset at midnight UTC; minute counters reset on UTC minute boundaries. The console shows read-time snapshots, not a capacity guarantee.

Errors & retries

JSON responses include an error message
Status	Next action
`400`	Check filters, date bounds, page size or expired cursors; narrow an oversized response
`401`	Check the key, expiry, revocation, current terms and production approval
`403`	The credential lacks the required scope
`405`	Use GET; unsafe requests may be rejected earlier by CSRF protection
`429`	Wait for the number of seconds in Retry-After before retrying
`503`	Service temporarily unavailable; back off and retry. Limits are never bypassed when quota enforcement is unavailable

Source, freshness & access terms

Tangabid serves normalized observations from its configured sources. Use source attribution and observation dates returned on each row. updated_at describes Tangabid record changes, not upstream source revision times. There is no freshness guarantee or certified quality flag; raw ingestion files remain the audit source.

Institutional access is reviewed case by case. Confirm upstream licensing and commercial redistribution rights before production approval. API keys do not create exclusive rights over data available through public CSV.

Data-use agreement 2026-11-06

Cite TangaBid, the upstream source, extraction date and filters. Preserve units, context and freshness; do not claim completeness or guaranteed accuracy. Keep credentials private and respect quotas. API access grants no additional upstream rights and does not restrict data already available through public CSV. Production approval requires staff review of source rights and use case.

Operator configuration notes

API_KEY_PEPPER is required for key creation and authentication. API_REDIS_URL must point to the dedicated persistent non-evicting quota service. These settings are managed by the operator, not the application owner.

Read deployment and source-data limitations