API Version 1.0
Welcome to the API for accessing refined fruit market data. This central hub provides you with all the necessary information and links to integrate our data into your applications.
The data provided via this API is the same data used to generate the charts and insights available on the Fruit Data Kings platform.
We offer both Wholesale API endpoints (China, Middle East, Europe) and Retail API endpoints with multi-location data and USD conversion.
This page serves as the central documentation for the Fruit Data Kings API. Below you will find details on authentication, available endpoints by region, product-specific paths, supported parameters (like ?detail=full for comprehensive data), and example response formats in JSON.
Please review the "Available Endpoints by Region" and "Example Responses" sections for specific details on how to construct your requests and interpret the data returned.
Access to the API requires a unique API Key. Your API Key will be provided to you by the Fruit Data Kings team. This key authenticates your requests and grants access to the specific data segments (regions and products) you are authorized for.
To authenticate your API calls, include your API Key in the Authorization header of your HTTP request, prefixed with Api-Key. See the example below:
Authorization: Api-Key YOUR_API_KEY_HEREReplace YOUR_API_KEY_HERE with the actual API Key you have been assigned.
Here's how you would make a GET request to an example endpoint (e.g., for Apple data in China) using cURL:
curl -X GET "https://fruitdatakings.com/api/china/apple/" \
-H "Authorization: Api-Key YOUR_API_KEY_HERE"Remember to replace "https://fruitdatakings.com/api/china/apple/" with the actual endpoint URL you wish to access and YOUR_API_KEY_HERE with your assigned key.
If your key is invalid, missing, or does not have permission for the requested resource, you will receive an error response (typically a 401 Unauthorized or 403 Forbidden status code).
Our API is structured by region. Below are the available products for each region based on current data availability. Each endpoint supports an optional ?detail=full query parameter for more comprehensive data.
Our Retail API provides multi-location retail data with automatic USD conversion. Data is available from multiple global markets, each in their local currency with USD equivalents calculated using weekly exchange rates.
The Retail API supports two URL patterns:
/api/retail/<product>/ - Returns data for all locations/api/retail/<location>/<product>/ - Returns data for a specific locationAdd ?detail=full for individual record-level data instead of weekly aggregations.
/api/china/apple/)Provides aggregated data, typically weekly averages, suitable for direct chart plotting.
{
"product": "Apple",
"region": "China",
"data_type": "simple",
"data": [
{
"variety": "Fuji",
"week_ending": "2023-10-28",
"average_price_rmb": 8.5,
"low_price_rmb": 8.0,
"high_price_rmb": 9.0,
"average_price_usd": 1.18,
"data_count": 5
},
{
"variety": "Gala",
"week_ending": "2023-10-28",
"average_price_rmb": 7.2,
"low_price_rmb": 7.0,
"high_price_rmb": 7.5,
"average_price_usd": 1.00,
"data_count": 4
}
// ... more varieties/weeks
]
}/api/china/apple/?detail=full)Provides the underlying refined data points used to calculate the simple aggregations. Includes individual records.
{
"product": "Apple",
"region": "China",
"data_type": "detailed",
"data": [
{
"date": "2023-10-23",
"variety": "Fuji",
"price_rmb": 8.2,
"volume_kg": 1500,
"quality": "Premium",
// ... other detailed fields
},
{
"date": "2023-10-24",
"variety": "Fuji",
"price_rmb": 8.6,
"volume_kg": 1650,
"quality": "Premium",
// ... other detailed fields
},
{
"date": "2023-10-23",
"variety": "Gala",
"price_rmb": 7.1,
"volume_kg": 2200,
"quality": "Standard",
// ... other detailed fields
}
// ... many more data points
]
}/api/retail/germany/apple/)Provides aggregated weekly data with prices in local currency and USD equivalent.
{
"product": "Apple",
"slug": "apple",
"region": "retail",
"data_type": "retail",
"detail_level": "simple",
"location": "Germany",
"currency": "EUR",
"currency_symbol": "€",
"available_locations": ["China", "Dubai", "Germany", "Kuala Lumpur", "Mumbai"],
"varieties": [
{
"variety": "Pink Lady",
"origin": "Chile",
"locations": ["Germany"],
"currencies": {"Germany": "EUR"},
"data": [
{
"year": 2024,
"week": 31,
"location": "Germany",
"min_price": 2.99,
"max_price": 3.99,
"average_price": 3.49,
"average_price_usd": 3.77,
"data_count": 5
}
// ... more weeks
]
}
// ... more variety/origin combinations
]
}/api/retail/apple/)Returns data for all available locations when no location is specified.
{
"product": "Apple",
"slug": "apple",
"region": "retail",
"data_type": "retail",
"detail_level": "simple",
"available_locations": ["China", "Dubai", "Germany", "Kuala Lumpur", "Mumbai"],
"varieties": [
{
"variety": "Fuji",
"origin": "China",
"locations": ["China", "Dubai"],
"currencies": {"China": "CNY", "Dubai": "AED"},
"data": [
{
"year": 2024,
"week": 32,
"location": "China",
"min_price": 15.50,
"max_price": 18.90,
"average_price": 17.20,
"average_price_usd": 2.41,
"data_count": 12
},
{
"year": 2024,
"week": 32,
"location": "Dubai",
"min_price": 8.50,
"max_price": 12.00,
"average_price": 10.25,
"average_price_usd": 2.79,
"data_count": 8
}
// ... more data points
]
}
// ... more variety/origin combinations
]
}/api/retail/germany/apple/?detail=full)Provides individual records with all available fields.
{
"product": "Apple",
"slug": "apple",
"region": "retail",
"data_type": "retail",
"detail_level": "full",
"location": "Germany",
"currency": "EUR",
"currency_symbol": "€",
"available_locations": ["China", "Dubai", "Germany", "Kuala Lumpur", "Mumbai"],
"varieties": [
{
"variety": "Pink Lady",
"origin": "Chile",
"locations": ["Germany"],
"record_count": 15,
"data": [
{
"year": 2024,
"week": 31,
"location": "Germany",
"retailer": "EDEKA",
"price": 3.49,
"weight": 500,
"pack": "Carton Pack",
"pieces": "4",
"bio": "Bio",
"price_usd": 3.77,
"currency": "EUR"
},
{
"year": 2024,
"week": 31,
"location": "Germany",
"retailer": "Lidl",
"price": 2.99,
"weight": 1000,
"pack": "Loose",
"pieces": null,
"bio": "Regular",
"price_usd": 3.23,
"currency": "EUR"
}
// ... more records
]
}
// ... more variety/origin combinations
]
}Access to the Fruit Data Kings API is provided on a subscription basis at a rate of 300 EUR per month.
If you have an existing active subscription to other Fruit Data Kings services, the API access fee may be reduced by the cost of your current subscription. Please contact our sales team for a personalized quote.
To ensure optimal performance and fair usage for all our clients, API requests are subject to rate limiting. While specific limits can vary based on your subscription tier and usage patterns, a general guideline for standard access is approximately 3,000 requests per 24-hour period per API key.
These limits are in place to prevent unintentional or abusive request volumes that could impact service stability. If you anticipate requiring a higher request volume, or for precise details on the rate limits applicable to your API key, please consult your service agreement or contact our support team.
We encourage caching data on your end where appropriate to optimize performance and stay within reasonable usage parameters.
The data provided via the Fruit Data Kings API is intended solely for your internal business decision-making processes. The data may not be resold, repackaged for resale, redistributed, or otherwise used for commercial external distribution or sub-licensing without express written permission from Fruit Data Kings.
Unauthorized reproduction or distribution of this data is strictly prohibited and may result in termination of API access and other legal remedies.