TradeCaravan exposes three read-only tools — SA import duty and landed cost, HS tariff classification, and daily port congestion — over a REST API and over MCP, the standard that lets an AI assistant call a live tool instead of guessing. Included with Pro+ and Featured listings.
Two ways in, one set of numbers
REST API
For your own software — a quoting tool, a spreadsheet job, an internal dashboard. You make the call and handle the JSON.
MCP server
MCP (Model Context Protocol) is the open standard that lets an AI assistant call a tool rather than recall a number. Add the connector once and the assistant looks up today's rate instead of guessing at one from its training data.
Both run the same engine the website runs, so an answer you get through the API is the answer the
calculator page gives. Every response carries a source_url pointing at the human-readable
page, which is what makes an assistant's answer checkable.
Getting access
- Hold Pro+ or a Featured directory listing. Either one is enough — you don't need both.
- Go to My Account → API & MCP and create a key.
- You get two credentials at once: an API key for REST, and an MCP connector URL for assistants. Copy both — they're shown once.
Create a key See what's included
Limits are 120 calls a minute and 10,000 a day per key, with up to 5 active keys. Everything here is read-only — there is no endpoint that writes, charges or sends anything.
Connecting an AI assistant
Any assistant that speaks MCP over HTTP can use this. In most of them the setting sits under
Connectors or MCP servers: choose to add a custom one, paste your MCP
connector URL, and save. No approval or application is needed at our end — the connector is something you
add to your own account. Command-line and desktop clients generally take the same URL as an
http (streamable HTTP) transport; check your assistant's own documentation for the exact
wording, since each vendor names the screen slightly differently.
Your connector URL contains a secret, so treat it like a password: don't put it in a shared document, a screenshot or a support ticket. If it leaks, revoke the key in your dashboard and create another — that rotates the URL without touching your REST integrations.
Things to ask once it's connected:
- “What will it cost to land R400,000 of solar panels from China, including duty and VAT?”
- “What's the HS code for cotton t-shirts, and what duty does South Africa charge on them?”
- “Is Durban congested this week? Should I expect delays on a container arriving Friday?”
The REST API
Base URL https://tradecaravan.co.za/api/v1. Send your key as a bearer token:
curl -H "Authorization: Bearer tc_key_..." \
"https://tradecaravan.co.za/api/v1/hs_code_lookup?query=solar+panels"
curl -H "Authorization: Bearer tc_key_..." \
-H "Content-Type: application/json" \
-d '{"fob":400000,"freight":25000,"duty_rate":0,"fx_rate":1}' \
"https://tradecaravan.co.za/api/v1/duty_calculator"
Arguments may go in a JSON body or the query string. Success is
{"ok":true,"tool":"…","data":{…}}; failure is {"ok":false,"code":"…","error":"…"},
where code is stable and safe to branch on. GET /api/v1 returns the machine-readable
catalogue and needs no key.
The tools
duty_calculator South African import duty & landed cost
Calculate what an import will actually cost to land in South Africa: customs duty, the 10% ATV uplift, 15% VAT, port charges and clearing. Call this whenever someone asks what it costs to import something into South Africa, what duty or VAT they will pay on a shipment, or how a change in FOB value or exchange rate affects landed cost. Uses the SARS transaction-value method (duty is charged on the FOB customs value; international freight and insurance are not dutiable). Returns an estimate, not a customs declaration.
| Argument | Type | Meaning |
|---|---|---|
| fob * | number | FOB value of the goods, in the currency given by fx_rate. Required. |
| freight | number | International freight cost, same currency as fob. Default 0. |
| insurance | number | Marine insurance cost, same currency as fob. Default 0. |
| duty_rate | number | Ad-valorem duty rate as a percentage, e.g. 20 for 20%. Look it up with hs_code_lookup first if unknown. Default 0. |
| fx_rate | number | ZAR per unit of the value currency, e.g. 18.5 for USD. Use 1 if the values are already in rand. Default 1. |
| clearing | number | Clearing agent fee in ZAR. Defaults to R3,500, a typical SA agent fee. |
| origin | string | Set to "sacu" for goods originating in the SACU/BLNS region, which are exempt from the 10% ATV uplift. Anything else is treated as non-SACU. |
hs_code_lookup HS tariff code lookup
Search the WCO HS 2022 tariff nomenclature (6,840 headings and subheadings) by product description or by code, and get the South African duty rate where we have researched one. Call this to classify goods for import or export, to find the tariff heading for a product, or to get the duty rate before running duty_calculator. Results marked "curated": false are classification only — the code is real but no SA rate has been verified for it, so do not state a duty rate for those.
| Argument | Type | Meaning |
|---|---|---|
| query * | string | Product description ("solar panels", "cotton t-shirts") or a tariff code ("8517", "6109.10"). Minimum 2 characters. |
| limit | integer | Maximum results, 1-25. Default 10. |
port_status South African port congestion status
Get today's published congestion status for all eight Transnet commercial ports (Durban, Cape Town, Ngqura, Gqeberha, Richards Bay, Saldanha, East London, Mossel Bay): congestion level, vessels at anchorage, average waiting days, berth status, truck turnaround and wind, plus any active advisories. Call this when someone asks about delays, backlogs or waiting times at a South African port, or whether to expect a shipment to be held up. Always report the updated_at timestamp — this board is published each weekday morning, not live-streamed.
| Argument | Type | Meaning |
|---|---|---|
| port | string | Optional port to narrow the answer. Accepts the slug ("durban", "cape-town", "richards-bay"), the code ("DBN") or the name ("Durban"). Omit for all eight. |
* Required argument.
Accuracy and limits
Duty figures are planning estimates computed with the SARS transaction-value method, not
customs declarations — confirm the tariff heading and rate with SARS or a licensed clearing agent before you
declare. HS results marked curated: false are classification only: the code is a real line in the
HS 2022 nomenclature, but no South African rate has been verified for it, so no rate is returned and none
should be quoted. Port status is published each weekday morning from carrier and terminal
advisories rather than streamed live, so always report the updated_at date alongside the figures.
Stability
Tool names and response fields are additive: new fields may appear, existing ones will not be renamed or
removed inside v1. A breaking change would ship as v2 alongside it. If you need a
tool we don't expose yet, or a higher rate limit,
tell us what you're building — the surface grows on request rather than in advance.
Common questions
Does TradeCaravan have an API?
Yes. Three read-only tools — South African import duty and landed cost, HS tariff classification, and daily port congestion — are available over a REST API at /api/v1, and over MCP for AI assistants. They run the same calculation engine as the website, so an API answer matches the calculator page.
What is MCP, and how is it different from the REST API?
MCP (Model Context Protocol) is an open standard that lets an AI assistant call a tool instead of answering from memory. Use the REST API when your own software makes the call — a quoting tool, a spreadsheet job, an internal dashboard. Use the MCP server when you want an assistant to look the figure up itself. Both return the same numbers.
How much does API access cost?
There is no separate API fee. Access is included with a Pro+ subscription (R499 a month) or with a Featured directory listing. Either one on its own is enough — you do not need both.
Do I need to apply or be approved for access?
No. Once you hold Pro+ or a Featured listing you create the key yourself in your dashboard and it works immediately. Connecting the MCP server to an AI assistant needs no approval from us or from the assistant's vendor — a custom connector is something you add to your own account.
Can the API change data, place orders or send anything?
No. Every endpoint is read-only. There is no route that writes to your account, charges a card or sends an email, so a key that leaks cannot be used to spend money or contact anyone — revoke it in your dashboard and it stops working immediately.
Are the duty figures accurate enough to declare to customs?
They are planning estimates computed with the SARS transaction-value method, not customs declarations. Confirm the tariff heading and rate with SARS or a licensed clearing agent before you declare. Every response carries a source_url pointing at the human-readable page so any figure can be checked.