Kulea API Documentation

This API provides access to sugar trading data including landed costs, parities, and wholesale prices. The API is designed for businesses and applications that need to track and analyze sugar market data in real-time.

API Overview

The API is organized around REST principles. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.kulea.com

All endpoints are only accessible via HTTPS.

Authentication

All endpoints require an API key for authentication. Include the API key in the request headers:

Header: apikey
Value: YOUR_API_KEY

Contact support@kulea.com to obtain an API key.

Rate Limiting

All endpoints are rate-limited to 100 requests per 15-minute window per IP address.

API Structure

The Sugar Trading Data API is organized into three main data categories, each providing both latest and historical data endpoints:

1Wholesale Prices

Real-time and historical wholesale sugar prices across different cities, countries, and regions.

Latest:GET /api/v1/sugar/latest/prices

Historical:GET /api/v1/sugar/historical/prices

2Landed Costs

Cost analysis for sugar imports including transportation, customs, and other associated costs.

Latest:GET /api/v1/sugar/latest/landed-costs

Historical:GET /api/v1/sugar/historical/landed-costs

3Parities

Trading parity calculations showing the difference between wholesale prices and landed costs.

Latest:GET /api/v1/sugar/latest/parities

Historical:GET /api/v1/sugar/historical/parities

Key Features

• Latest endpoints provide current market data
• Historical endpoints offer time-series analysis with date filtering
• Consistent filtering across all endpoints (cityIds, countryId, regionId)
• Standardized responses with clear data structures

Sugar Wholesale Prices

Sugar Wholesale Prices (Latest)

Returns the most recent wholesale prices for sugar across different cities.

GET/api/v1/sugar/latest/prices

Parameters

Parameter	Type	Description	Required	Default
cityIds	array	Array of city IDs in square brackets (e.g., [1,2,15]) to filter results	No	null
countryId	number	Filter by country ID	No	null
regionId	number	Filter by region ID	No	null

Responses

200 - Successful response

{
  "status": "success",
  "nCities": 5,
  "data": [
    {
      "price": "1030",
      "date": "2025-06-29",
      "city": "Ouagadougou",
      "country": "Burkina Faso",
      "flag": "🇧🇫",
      "countryId": 21,
      "regionId": 1,
      "region": "Africa",
      "commodity": "Refined",
      "unit": "$/MT"
    },
    {
      "price": "1020",
      "date": "2025-06-29",
      "city": "Abidjan",
      "country": "Côte D'Ivoire",
      "flag": "🇨🇮",
      "countryId": 44,
      "regionId": 1,
      "region": "Africa",
      "commodity": "White (LQW / Ref.)",
      "unit": "$/MT"
    },
    {
      "price": "615",
      "date": "2025-06-29",
      "city": "Djibouti City",
      "country": "Djibouti",
      "flag": "🇩🇯",
      "countryId": 58,
      "regionId": 1,
      "region": "Africa",
      "commodity": "LQW",
      "unit": "$/MT"
    },
    {
      "price": "730",
      "date": "2025-06-29",
      "city": "Bukavu",
      "country": "DRC",
      "flag": "🇨🇩",
      "countryId": 40,
      "regionId": 1,
      "region": "Africa",
      "commodity": "VHP",
      "unit": "$/MT"
    },
    {
      "price": "940",
      "date": "2025-06-29",
      "city": "Mbabane",
      "country": "Eswatini",
      "flag": "🇸🇿",
      "countryId": 214,
      "regionId": 1,
      "region": "Africa",
      "commodity": "Refined",
      "unit": "$/MT"
    }
  ]
}

Sugar Wholesale Prices (Historical)

Returns historical wholesale prices for sugar with optional filtering.

GET/api/v1/sugar/historical/prices

Parameters

Parameter	Type	Description	Required	Default
cityIds	array	Array of city IDs in square brackets (e.g., [1,2,15]) to filter results	No	null
countryId	number	Filter by country ID	No	null
regionId	number	Filter by region ID	No	null
startDate	string	Start date in YYYY-MM-DD format	No	null
endDate	string	End date in YYYY-MM-DD format	No	null

Responses

200 - Successful response

{
  "status": "success",
  "nCities": 3,
  "data": [
    {
      "cityName": "Abidjan",
      "cityId": 49,
      "country": "Côte D'Ivoire",
      "countryEmoji": "🇨🇮",
      "region": "Africa",
      "priceData": [
        {
          "price": 1020,
          "date": "2025-06-29",
          "dateString": "29th Jun 2025",
          "commodity": "White (LQW / Ref.)",
          "unit": "$/MT"
        },
        {
          "price": 1020,
          "date": "2025-06-28",
          "dateString": "28th Jun 2025",
          "commodity": "White (LQW / Ref.)",
          "unit": "$/MT"
        },
        {
          "price": 1020,
          "date": "2025-06-27",
          "dateString": "27th Jun 2025",
          "commodity": "White (LQW / Ref.)",
          "unit": "$/MT"
        },
        {
          "price": 1020,
          "date": "2025-06-26",
          "dateString": "26th Jun 2025",
          "commodity": "White (LQW / Ref.)",
          "unit": "$/MT"
        }
      ]
    },
    {
      "cityName": "Nairobi",
      "cityId": 1,
      "country": "Kenya",
      "countryEmoji": "🇰🇪",
      "region": "Africa",
      "priceData": [
        {
          "price": 850,
          "date": "2025-06-29",
          "dateString": "29th Jun 2025",
          "commodity": "Refined",
          "unit": "$/MT"
        },
        {
          "price": 845,
          "date": "2025-06-28",
          "dateString": "28th Jun 2025",
          "commodity": "Refined",
          "unit": "$/MT"
        },
        {
          "price": 840,
          "date": "2025-06-27",
          "dateString": "27th Jun 2025",
          "commodity": "Refined",
          "unit": "$/MT"
        }
      ]
    },
    {
      "cityName": "Lagos",
      "cityId": 15,
      "country": "Nigeria",
      "countryEmoji": "🇳🇬",
      "region": "Africa",
      "priceData": [
        {
          "price": 920,
          "date": "2025-06-29",
          "dateString": "29th Jun 2025",
          "commodity": "VHP",
          "unit": "$/MT"
        },
        {
          "price": 925,
          "date": "2025-06-28",
          "dateString": "28th Jun 2025",
          "commodity": "VHP",
          "unit": "$/MT"
        },
        {
          "price": 930,
          "date": "2025-06-27",
          "dateString": "27th Jun 2025",
          "commodity": "VHP",
          "unit": "$/MT"
        }
      ]
    }
  ]
}

Sugar Landed Costs

Sugar Landed Costs (Latest)

Returns the most recent landed costs for sugar across different cities, origins, and shipment modes.

GET/api/v1/sugar/latest/landed-costs

Parameters

Parameter	Type	Description	Required	Default
cityIds	array	Array of city IDs in square brackets (e.g., [1,2,15]) to filter results	No	null
countryId	number	Filter by country ID	No	null
regionId	number	Filter by region ID	No	null

Responses

200 - Successful response

{
  "status": "success",
  "data": [
    {
      "cityName": "Mombasa",
      "cityId": 2,
      "countryName": "Kenya",
      "countryEmoji": "🇰🇪",
      "regionName": "East Africa",
      "costs": [
        {
          "origin": "Brazil",
          "commodity": "Raw Sugar",
          "shipmentMode": "Ocean",
          "prices": [
            {
              "value": 780.25,
              "date": "2024-03-20T00:00:00.000Z",
              "dateString": "2024-03-20",
              "unit": "$/MT"
            }
          ]
        }
      ]
    }
  ]
}

Sugar Landed Costs (Historical)

Returns historical landed costs for sugar with optional filtering.

GET/api/v1/sugar/historical/landed-costs

Parameters

Parameter	Type	Description	Required	Default
cityIds	array	Array of city IDs in square brackets (e.g., [1,2,15]) to filter results	No	null
countryId	number	Filter by country ID	No	null
regionId	number	Filter by region ID	No	null
startDate	string	Start date in YYYY-MM-DD format	No	null
endDate	string	End date in YYYY-MM-DD format	No	null

Responses

200 - Successful response

{
  "status": "success",
  "data": [
    {
      "cityName": "Mombasa",
      "cityId": 2,
      "countryName": "Kenya",
      "countryEmoji": "🇰🇪",
      "regionName": "East Africa",
      "costs": [
        {
          "origin": "Brazil",
          "commodity": "Raw Sugar",
          "shipmentMode": "Ocean",
          "prices": [
            {
              "value": 780.25,
              "date": "2024-03-20T00:00:00.000Z",
              "dateString": "2024-03-20",
              "unit": "$/MT"
            },
            {
              "value": 775.5,
              "date": "2024-03-19T00:00:00.000Z",
              "dateString": "2024-03-19",
              "unit": "$/MT"
            }
          ]
        }
      ]
    }
  ]
}

Sugar Parities

Sugar Parities (Latest)

Returns the most recent sugar parities across different cities, origins, and shipment modes.

GET/api/v1/sugar/latest/parities

Parameters

Parameter	Type	Description	Required	Default
cityIds	array	Array of city IDs in square brackets (e.g., [1,2,15]) to filter results	No	null
countryId	number	Filter by country ID	No	null
regionId	number	Filter by region ID	No	null

Responses

200 - Successful response

{
  "status": "success",
  "data": [
    {
      "cityName": "Nairobi",
      "cityId": 1,
      "countryName": "Kenya",
      "countryEmoji": "🇰🇪",
      "regionName": "East Africa",
      "parities": [
        {
          "origin": "Brazil",
          "commodity": "Raw Sugar",
          "shipmentMode": "Ocean",
          "wholesalePrice": 850.5,
          "landedCost": 780.25,
          "parity": 70.25,
          "date": "2024-03-20T00:00:00.000Z",
          "dateString": "2024-03-20",
          "unit": "$/MT"
        }
      ]
    }
  ]
}

Sugar Parities (Historical)

Returns historical sugar parities with optional filtering.

GET/api/v1/sugar/historical/parities

Parameters

Parameter	Type	Description	Required	Default
cityIds	array	Array of city IDs in square brackets (e.g., [1,2,15]) to filter results	No	null
countryId	number	Filter by country ID	No	null
regionId	number	Filter by region ID	No	null
startDate	string	Start date in YYYY-MM-DD format	No	null
endDate	string	End date in YYYY-MM-DD format	No	null

Responses

200 - Successful response

{
  "status": "success",
  "nCities": 3,
  "data": [
    {
      "cityName": "Ashgabat",
      "cityId": 23,
      "countryName": "Turkmenistan",
      "countryEmoji": "🇹🇲",
      "regionName": "CIS",
      "costs": [
        {
          "origin": "ExW Ufa",
          "commodity": "LQW",
          "shipmentMode": "Road / Rail",
          "parities": [
            {
              "value": "-165.00",
              "status": "closed",
              "landedCost": "865.00",
              "price": "700",
              "date": "2025-06-30",
              "dateString": "30th Jun 2025"
            },
            {
              "value": "-165.00",
              "status": "closed",
              "landedCost": "865.00",
              "price": "700",
              "date": "2025-06-29",
              "dateString": "29th Jun 2025"
            },
            {
              "value": "-165.00",
              "status": "closed",
              "landedCost": "865.00",
              "price": "700",
              "date": "2025-06-28",
              "dateString": "28th Jun 2025"
            },
            {
              "value": "-165.00",
              "status": "closed",
              "landedCost": "865.00",
              "price": "700",
              "date": "2025-06-27",
              "dateString": "27th Jun 2025"
            }
          ]
        }
      ]
    },
    {
      "cityName": "Nairobi",
      "cityId": 1,
      "countryName": "Kenya",
      "countryEmoji": "🇰🇪",
      "regionName": "Africa",
      "costs": [
        {
          "origin": "Brazil",
          "commodity": "Raw Sugar",
          "shipmentMode": "Ocean",
          "parities": [
            {
              "value": "70.25",
              "status": "open",
              "landedCost": "780.25",
              "price": "850",
              "date": "2025-06-30",
              "dateString": "30th Jun 2025"
            },
            {
              "value": "70.25",
              "status": "open",
              "landedCost": "775.50",
              "price": "845",
              "date": "2025-06-29",
              "dateString": "29th Jun 2025"
            },
            {
              "value": "70.25",
              "status": "open",
              "landedCost": "770.75",
              "price": "840",
              "date": "2025-06-28",
              "dateString": "28th Jun 2025"
            }
          ]
        }
      ]
    },
    {
      "cityName": "Lagos",
      "cityId": 15,
      "countryName": "Nigeria",
      "countryEmoji": "🇳🇬",
      "regionName": "Africa",
      "costs": [
        {
          "origin": "Thailand",
          "commodity": "VHP",
          "shipmentMode": "Ocean",
          "parities": [
            {
              "value": "45.50",
              "status": "open",
              "landedCost": "874.50",
              "price": "920",
              "date": "2025-06-30",
              "dateString": "30th Jun 2025"
            },
            {
              "value": "45.50",
              "status": "open",
              "landedCost": "879.50",
              "price": "925",
              "date": "2025-06-29",
              "dateString": "29th Jun 2025"
            },
            {
              "value": "45.50",
              "status": "open",
              "landedCost": "884.50",
              "price": "930",
              "date": "2025-06-28",
              "dateString": "28th Jun 2025"
            }
          ]
        }
      ]
    }
  ]
}

Response Format

All endpoints return responses in the following format:

{
  "status": "success",
  "data": [
    {}
  ]
}

Error Responses

The API uses standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid parameters
401 Unauthorized: Invalid or missing API key
403 Forbidden: API key doesn't have access to the requested endpoint
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Error responses follow this format:

{
  "status": "error",
  "message": "Error message details"
}

Query Examples

This section provides practical examples of how to use query parameters with the API endpoints. These examples can be applied to any endpoint that supports the respective parameters.

Filtering by Cities

Filter results to specific cities using their IDs:

GET /api/v1/sugar/latest/prices?cityIds=[1,2,15]

# Example response structure
{
  "status": "success",
  "nCities": 3,
  "data": [
    {
      "price": "850",
      "date": "2025-06-29",
      "city": "Nairobi",
      "country": "Kenya",
      "flag": "🇰🇪",
      "countryId": 1,
      "regionId": 1,
      "region": "Africa",
      "commodity": "Refined",
      "unit": "$/MT"
    }
    // ... more cities
  ]
}

Filtering by Region

Get all data for a specific region:

GET /api/v1/sugar/latest/prices?regionId=1

# Returns all cities in Africa (regionId=1)
{
  "status": "success",
  "nCities": 25,
  "data": [
    {
      "price": "1030",
      "date": "2025-06-29",
      "city": "Ouagadougou",
      "country": "Burkina Faso",
      "flag": "🇧🇫",
      "countryId": 21,
      "regionId": 1,
      "region": "Africa",
      "commodity": "Refined",
      "unit": "$/MT"
    }
    // ... more African cities
  ]
}

Filtering by Country

Get data for a specific country:

GET /api/v1/sugar/latest/prices?countryId=116

# Returns all cities in Kenya (countryId=116)
{
  "status": "success",
  "nCities": 2,
  "data": [
    {
      "price": "850",
      "date": "2025-06-29",
      "city": "Nairobi",
      "country": "Kenya",
      "flag": "🇰🇪",
      "countryId": 1,
      "regionId": 1,
      "region": "Africa",
      "commodity": "Refined",
      "unit": "$/MT"
    },
    {
      "price": "820",
      "date": "2025-06-29",
      "city": "Mombasa",
      "country": "Kenya",
      "flag": "🇰🇪",
      "countryId": 1,
      "regionId": 1,
      "region": "Africa",
      "commodity": "Raw Sugar",
      "unit": "$/MT"
    }
  ]
}

Historical Data with Date Range

Get historical data for a specific date range:

GET /api/v1/sugar/historical/prices?startDate=2025-06-01&endDate=2025-06-30

# Returns historical data for June 2025
{
  "status": "success",
  "nCities": 51,
  "data": [
    {
      "cityName": "Abidjan",
      "cityId": 49,
      "country": "Côte D'Ivoire",
      "countryEmoji": "🇨🇮",
      "region": "Africa",
      "priceData": [
        {
          "price": 1020,
          "date": "2025-06-29",
          "dateString": "29th Jun 2025",
          "commodity": "White (LQW / Ref.)",
          "unit": "$/MT"
        }
        // ... more historical data points
      ]
    }
    // ... more cities
  ]
}

Combining Multiple Parameters

Use multiple parameters together for precise filtering:

GET /api/v1/sugar/historical/prices?regionId=1&countryId=116&cityIds=[1,2]&startDate=2025-06-01&endDate=2025-06-15

# Returns historical data for:
# - Region: Africa (regionId=1)
# - Country: Kenya (countryId=116) 
# - Cities: Nairobi and Mombasa (cityIds=[1,2])
# - Date range: June 1-15, 2025

{
  "status": "success",
  "nCities": 2,
  "data": [
    {
      "cityName": "Nairobi",
      "cityId": 1,
      "country": "Kenya",
      "countryEmoji": "🇰🇪",
      "region": "Africa",
      "priceData": [
        {
          "price": 850,
          "date": "2025-06-15",
          "dateString": "15th Jun 2025",
          "commodity": "Refined",
          "unit": "$/MT"
        }
        // ... more data points
      ]
    },
    {
      "cityName": "Mombasa",
      "cityId": 2,
      "country": "Kenya",
      "countryEmoji": "🇰🇪",
      "region": "Africa",
      "priceData": [
        {
          "price": 820,
          "date": "2025-06-15",
          "dateString": "15th Jun 2025",
          "commodity": "Raw Sugar",
          "unit": "$/MT"
        }
        // ... more data points
      ]
    }
  ]
}

Parameter Usage Notes

• cityIds: Array of city IDs in square brackets (e.g., "[1,2,15]")
• countryId: Single country ID (e.g., "1")
• regionId: Single region ID (e.g., "1")
• startDate: Date in YYYY-MM-DD format (e.g., "2025-06-01")
• endDate: Date in YYYY-MM-DD format (e.g., "2025-06-30")
• All parameters are optional and can be combined
• Date parameters only apply to historical endpoints

Best Practices

• Use specific city IDs for precise data retrieval
• Combine region and country filters for broader analysis
• Limit date ranges for historical data to improve performance
• Check the Valid IDs Reference section for available IDs
• Consider using multiple smaller requests instead of one large request

Valid IDs Reference

This section provides reference tables for all valid region IDs, country IDs, and city IDs that can be used as parameters in the API endpoints.

Regions

Region ID	Region Name	Description
1	Africa	African countries and territories
2	Europe	European countries and territories
3	CIS	Commonwealth of Independent States

Countries

Country ID	Country Name	Flag	Region ID
7	Armenia	🇦🇲	3
16	Azerbaijan	🇦🇿	3
21	Burkina Faso	🇧🇫	1
36	Belarus	🇧🇾	3
40	DRC	🇨🇩	1
44	Côte D'Ivoire	🇨🇮	1
58	Djibouti	🇩🇯	1
69	Ethiopia	🇪🇹	1
80	Georgia	🇬🇪	3
83	Ghana	🇬🇭	1
116	Kenya	🇰🇪	1
117	Kyrgyzstan	🇰🇬	3
126	Kazakhstan	🇰🇿	3
140	Moldova	🇲🇩	3
165	Nigeria	🇳🇬	1
192	Russia	🇷🇺	3
193	Rwanda	🇷🇼	1
197	Sudan	🇸🇩	1
206	Senegal	🇸🇳	1
207	Somalia	🇸🇴	1
209	South Sudan	🇸🇸	1
214	Eswatini	🇸🇿	1
218	Togo	🇹🇬	1
220	Tajikistan	🇹🇯	3
223	Turkmenistan	🇹🇲	3
230	Tanzania	🇹🇿	1
231	Ukraine	🇺🇦	3
232	Uganda	🇺🇬	1
236	Uzbekistan	🇺🇿	3
249	South Africa	🇿🇦	1

Cities

City ID	City Name	Country ID	Region ID
1	Nairobi	116	1
2	Mombasa	116	1
3	Kigali	193	1
4	Durban	249	1
5	Johannesburg	249	1
6	Cape Town	249	1
7	Djibouti City	58	1
8	Mogadishu	207	1
9	Kampala	232	1
10	Dar Es Salaam	230	1
11	Krasnodar	192	3
12	Ufa	192	3
13	Novosibirsk	192	3
14	Altai Region	192	3
15	Minsk	36	3
16	Yerevan	7	3
17	Astana	126	3
18	Tashkent	236	3
19	Bishkek	117	3
20	Tbilisi	80	3
21	Dushanbe	220	3
22	Baku	16	3
23	Ashgabat	223	3
24	Chişinău	140	3
25	Kyiv	231	3
26	Voronezh	192	3
40	Bukavu	40	1
41	Juba	209	1
42	Dire Dawa	69	1
43	Abuja	165	1
44	Adamawa	165	1
45	Kano	165	1
46	Kwara	165	1
47	Lagos	165	1
48	Addis Ababa	69	1
49	Abidjan	44	1
50	Lomé	218	1
51	Mbabane	214	1
52	Dakar	206	1
53	Port Sudan	197	1
54	Northern	197	1
55	Gedaref	197	1
56	White Nile	197	1
57	Gezira	197	1
58	Khartoum	197	1
59	Darfur	197	1
60	Kordofan	197	1
61	Blue Nile	197	1
62	River Nile	197	1
63	Naheer Alneel	197	1
64	Sennar	197	1
65	Kassala	197	1
66	Accra	83	1
67	Ouagadougou	21	1