Farmazone Agricultural Data API Documentation

Comprehensive guide to authenticating, querying, and integrating South African agricultural market data: Live Fresh Produce Trade, Live SAFEX Grain Prices, and Weekly Beef & Carcass Prices.

Authentication

Requests to Farmazone data endpoints require a valid API key. Pass your secret key in the request header or as a query parameter.

Header: X-API-Key: fz_live_your_secret_key_here Query: ?api_key=fz_live_your_secret_key_here

Need an API key? Log in and generate one instantly on your Developer Dashboard.

Free Rate Quota

Free-tier keys are limited to 100 requests per day across all endpoints.

Daily Quota: 100 req/day
Reset Time: Midnight SAST (UTC+2)
Need More Than 100 Req/Day?

If you require custom rate limits or enterprise data feeds, contact us on WhatsApp:

Chat on WhatsApp (0603533486)
HTTP Status Codes
200 OK Successful request
401 Unauthorized Missing or invalid API key
403 Forbidden Deactivated/revoked key
429 Rate Limited Exceeded 100 req/day limit

Database Codes Cheatsheet (Live DB Reference)

Historical trade date range in database: 2026-05-15 to 2026-09-28

# ============================================================================== # FARMAZONE AGRICULTURAL DATA API - COMPLETE DATABASE CODES CHEATSHEET # Historical Produce Date Range: 2026-05-15 to 2026-09-28 # ============================================================================== # 1. FRESH PRODUCE CODES (Query parameter: ?product=) 001 - POTATOES 002 - SWEET POTATOES 004 - ONIONS 010 - CARROTS 016 - CABBAGE 021 - LETTUCE 022 - SPINACH 025 - GREEN BEANS 029 - CUCUMBERS 031 - GEM SQUASHES 034 - BUTTERNUT SQUASHES 042 - TOMATOES 044 - PEPPERS 055 - WATERMELONS 058 - APPLES 067 - GRAPES 072 - ORANGES 079 - AVOCADOS 082 - BANANAS 091 - STRAWBERRIES # 2. MUNICIPAL MARKET CODES (URL path: /fresh-produce/markets//lines) BLO - Bloemfontein Market CAP - Cape Town Market DUR - Durban Market EAS - East London Market GRM - George Market JHB - Johannesburg Market JOH - Johannesburg Market KIM - Kimberley Market KLE - Klerksdorp Market NEL - Mbombela Market PIE - Pietermaritzburg Market POR - Port Elizabeth Market PRE - Tshwane Market SPR - Springs Market VER - Vereeniging Market WEL - Welkom Market WIT - Witbank Market # 3. SAFEX GRAIN COMMODITY CODES (Query parameter: ?commodity=) SOYA - Sunflower Seed SOYB - SOYB SUNS - SUNS WEAT - WEAT WHEA - Wheat WMAZ - White Maize YMAZ - Yellow Maize # 4. SAFEX CONTRACT MONTH CODES (Query parameter: ?contract_month=) OCT26 DEC26 MAR27 MAY27 JUL27 SEP27 DEC27 MAR28 JUL28 # 5. CARCASS SPECIES CODES (Query parameter: ?species=) beef - Beef mutton - Mutton # 6. CARCASS GRADE CODES (Query parameter: ?grade=) a2_3 - A2/3 b2_3 - B2/3 c2_3 - C2/3 weaner_calf - Weaner calf feeder_lamb - Feeder lamb

Core Endpoints Reference

GET /api/v1/safex/contracts Live Grain Prices

Fetch paginated SAFEX grain contract prices, daily spot/future values, open interest, and trading volumes.

Query Parameters:
  • commodity (string, optional): Commodity code filter, e.g. WMAZ (White Maize), YMAZ (Yellow Maize), SOYA (Soybeans), SUNS (Sunflower).
  • contract_month (string, optional): Filter by contract expiry month, e.g. DEC26.
  • page (int, optional): Page number (default: 1).
  • page_size (int, optional): Number of results per page (default: 100, max: 500).
Example Request URLs:
1. GET https://farmazone.co.za/api/v1/safex/contracts?commodity=WMAZ 2. GET https://farmazone.co.za/api/v1/safex/contracts?commodity=YMAZ&contract_month=DEC26 3. GET https://farmazone.co.za/api/v1/safex/contracts?commodity=SOYA
Sample Response JSON:
{ "count": 48, "next": "https://farmazone.co.za/api/v1/safex/contracts?page=2", "previous": null, "results": [ { "commodity_type": "White Maize", "contract_month": "DEC26", "spot_price": "5120.00", "future_price": "5200.00", "daily_percentage_change": 2.40, "open_interest": "890.00", "trading_volume": "321.00", "last_updated_timestamp": "2026-09-15T18:00:00Z" } ] }
GET /api/v1/carcass/prices Weekly Beef Prices

Fetch weekly RPO carcass benchmark prices per kg across species (beef, mutton) and grades (A2/3, B2/3, C2/3, Weaner Calf, Feeder Lamb).

Query Parameters:
  • species (string, optional): Filter by species (e.g. beef, mutton).
  • grade (string, optional): Filter by grade (e.g. a2_3, b2_3, c2_3, weaner_calf, feeder_lamb).
  • page (int, optional): Page number (default: 1).
Example Request URLs:
1. GET https://farmazone.co.za/api/v1/carcass/prices?species=beef 2. GET https://farmazone.co.za/api/v1/carcass/prices?species=beef&grade=a2_3 3. GET https://farmazone.co.za/api/v1/carcass/prices?species=mutton&grade=feeder_lamb
Sample Response JSON:
{ "count": 12, "results": [ { "species": "beef", "grade": "a2_3", "price_r_per_kg": "62.50", "report_date": "2026-09-12", "week_ended": "2026-09-11", "note": "" } ] }
GUIDE

Fresh Produce Trade: Daily Market Averages & Exact Line Data Points

Query historical and live municipal market data by specifying any trading day (date=YYYY-MM-DD), municipal market (JOH, PRE, DUR, BFN, CPT), and produce code (001 = Potatoes, 002 = Onions, 003 = Tomatoes, 016 = Cabbage).

Step 1: Daily Market Averages & Turnover (Any Date)

Retrieve average price activity, total daily turnover, and active market status for all municipal markets on a given date.

Example Request URLs:
1. GET https://farmazone.co.za/api/v1/fresh-produce/markets 2. GET https://farmazone.co.za/api/v1/fresh-produce/markets?date=2026-09-15 3. GET https://farmazone.co.za/api/v1/fresh-produce/snapshot?date=2026-09-15
Sample Response JSON:
{ "count": 5, "results": [ { "code": "JOH", "name": "Johannesburg Produce Market", "turnover": "14250800.00", "line_count": 842, "trading_lines_count": 650, "is_market_active": true }, { "code": "PRE", "name": "Pretoria Produce Market", "turnover": "5820400.00", "line_count": 412, "trading_lines_count": 310, "is_market_active": true } ] }

Step 2: Exact Trading Line Data Points (Market × Date × Produce)

Drill down to inspect every single data point for a specific trading line: High Price, Low Price, Average Unit Price, Average Kg Price, Quantity Sold, Line Turnover, Quality Grade, and 30-Day Historic Trend Points.

Example Request URLs:
1. GET https://farmazone.co.za/api/v1/fresh-produce/markets/JOH/lines?date=2026-09-15&product=001 2. GET https://farmazone.co.za/api/v1/fresh-produce/markets/PRE/lines?date=2026-09-15&product=002 3. GET https://farmazone.co.za/api/v1/fresh-produce/markets/DUR/lines?date=2026-09-15&product=016
Sample Response JSON:
{ "count": 14, "results": [ { "id": 94821, "product_code": "001", "product_name": "POTATOES", "market_code": "JOH", "market_name": "Johannesburg Market", "stat_date": "2026-09-15", "variety": "BP1", "class_name": "1", "size": "L", "container": "POCKET", "mass_kg": "10.00", "qty_sold": "1500.00", "ave_price_unit": "47.50", "ave_price_kg": "4.75", "current_price": "52.00", "price_change_today": "2.50", "total_value_sold": "71250.00", "total_turnover": "71250.00", "trading_lines_count": 1500, "quality_grade": "Class 1", "unit_of_measure": "10 kg pocket", "price_trend_30d": [ {"date": "2026-09-14", "ave_price_unit": 45.00}, {"date": "2026-09-13", "ave_price_unit": 44.50}, {"date": "2026-09-12", "ave_price_unit": 46.00} ] } ] }