Introduction
This documentation describes how to work with IndexBox Platform (hereinafter, the “platform”) API. The API offers a comprehensive gateway to platform’s extensive database of market research, industry insights, and global trade data. Tailored for analysts, marketers, and business leaders, the API provides seamless access to data across a multitude of sectors, enabling informed decision-making and strategic planning.
This manual is crafted for developers tasked with integrating market insights into business applications, platforms, or internal systems. It is also an invaluable resource for data analysts seeking to enrich their analytical models with robust market data, and for marketing professionals aiming to leverage detailed industry trends and forecasts.
Through this guide, a user will learn how to authenticate requests, navigate data offerings, perform queries to retrieve specific datasets, and understand the structure of the API responses. Our goal is to empower the client to unlock the full potential of the platfrom, transforming its data into actionable intelligence that drives business growth and innovation.
The API is an integral part of the IndexBox Platform. Any element of the Platform, the API, as well as any part of this document, is the property of IndexBox and is protected by copyright law.
Legal Notice
Copyright © IndexBox. All rights reserved.
This document, along with all its contents, is the property of IndexBox, and is protected by copyright and international treaties. Unauthorized reproduction or distribution of this document, or any portion of it, may result in severe civil and criminal penalties and will be prosecuted to the maximum extent possible under the law.
Your use of the IndexBox Platform and the API indicates your acceptance of this Legal Notice. If you do not agree to these terms, do not use the API.
License Agreement
By accessing or using the API, you agree to comply with the terms of this License Agreement. This Agreement grants you a non-exclusive, non-transferable, limited right to access, use, and integrate the API into your applications or websites, subject to the conditions outlined herein.
Restrictions
Unauthorized Access: You may not attempt to gain unauthorized access to any portion or feature of the API, or any other systems or networks connected to the API, by hacking, password "mining," or any other illegitimate means.
Data modification: You may not attempt to delete, modify or use any API function to get access and modify the data other than the read-only operations allowed according to this guide.
Copyright Infringement: You may not use, copy, reproduce, republish, upload, post, transmit, distribute, or modify the content of the API in any way, except as provided herein, without the prior written consent of IndexBox.
Data Use: The data provided through the API is for your personal or internal business use only. You may not sell, license, or otherwise distribute the data to third parties without obtaining a separate agreement with IndexBox.
Intellectual Property
The data, information, and materials provided through the API are and shall remain the exclusive property of IndexBox. Nothing in this document, API guide and elsewhere shall be construed as transferring any rights, title, or interests to you or any third party.
Disclaimer of Warranties
The API service and the data on the platform is provided "as is" and "as available," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. IndexBox does not warrant that the API will be uninterrupted, timely, secure, or error-free.
Limitation of Liability
In no event shall IndexBox, its officers, directors, employees, or agents be liable for any direct, indirect, incidental, special, punitive, or consequential damages whatsoever resulting from the use of or inability to use the API, even if IndexBox has been advised of the possibility of such damages.
Amendments
IndexBox reserves the right, at its sole discretion, to modify or replace any part of this Legal Notice by posting the updated notice on its website. It is your responsibility to check this Legal Notice periodically for changes.
Governing Law
This Legal Notice shall be governed by and construed in accordance with the laws of the Grand Duchy of Luxembourg, without giving effect to any principles of conflicts of law.
For all other matters not specified in this document, the API is provided under the regulation of the IndexBox Platfrom Terms of Service available at the platform’s website: https://app.indexbox.io/terms-and-policies#tof
Glossary
Here is the list of key terms, definitions and abbreviations used in this document and at the IndexBox Platform:
Country - a distinct part of the world, recognized as a political entity within a specific territory. The list of countries is compiled based on the official UN classificatory of countries and regions or taken as reported by the official statistics of particular countries. The mention or omission of a country in the list of countries or within a specific region, or wherever in the IndexBox's materials, cannot be interpreted as either an IndexBox's statement in support of any party regarding the issue of any disputed territory, or as an IndexBox statement on the recognition or non-recognition of any sovereignty over any territory; nor does it contain any opinion whatsoever regarding the legal status of any country, territory, city or area, or of its authorities, or concerning the delimitations of its frontiers or boundaries.
Region – for the purpose of this document and data structurization at the platform, a region means a group of countries according to their geographic proximity, based on the UN geoscheme.
Trade partners – for a particular country, its trade partners constitute import supplying countries or export destination countries.
Factor – a data item, describing a specific market indicator (i.e, production volume, consumption value, etc.)
Primary factor – a factor that is essential for the market analysis and initially derived from primary sources
Secondary factor – a factor that was calculated from other factors. E.g, yield (secondary factor) = production volume divided by harvested area.
Authentication
Access to the API is provided only within the account registered on the platform. Authentication is used during any request, using a key that must be added each time the API is accessed. If the key is invalid, the request will return no data and an appropriate error statement. The key must be passed in the api_key request parameter.
The API key can be generated in your personal account. It identifies your account and must be kept secret. All actions associated with a key that belongs to a particular user, will be considered by IndexBox as responsibly made by the user. In all cases where you suspect the key security has been compromised, you must notify IndexBox and delete or re-issue the key. You can create or delete API keys in your personal account at any time.
All account API keys are subject to restrictions on the number of requests per day or month. When the current quota for an account is reached, all subsequent calls to our service will return the corresponding error.
IndexBox reserves the right to temporarily suspend or permanently terminate the user's account and any associated or single API keys at its sole discretion, should there be a violation of the restrictions set forth in the Legal Notice or upon detection of any suspicious activity by the user. "Suspicious activity" is defined as any action or inaction that exceeds the scope of normal data retrieval activities as outlined in this document and, in the opinion of IndexBox, could potentially damage the interests of IndexBox.
Data retrieval
This service is designed to automatically obtain data from the IndexBox Platform using a simple JSON API. To obtain
data, it is necessary to conduct a series of queries during which you determine the required product, region and
data parameters. Below is a list of the main calls:
- The "List of regions" returns a list of all regions and countries
available on the
platform, along with their codes.
- The "Product search" returns a list of all products available on the
platform with names,
IDs, and their corresponding HS-codes.
- The "Get data" returns all available information for a product/region pair
within a
specified date range, factored if applicable.
List of countries and regions
Use the action parameter with the value get_regions to get a list of all regions and related countries with their codes available on the platform. The code is required to get data for a specific country or region in the get_data action.
The response to a request is a JSON string, delivering an array. Structure of the response to a request for a list of regions:
HTTP request example:
/api_v2/?action=get_regions&api_key=YOUR_API_KEY
Response example:
[
{
"name": "Africa",
"code": "002",
"countries": [
{
"name": "Algeria",
"code": "12"
},
{
"name": "Angola",
"code": "24"
},
{
"name": "Benin",
"code": "204"
},
{
"name": "...",
"code": "..."
}
]
},
{
"name": "...",
"code": "...",
"countries": [
{
"name": "...",
"code": "..."
}
]
}
]
Product search
Use the action parameter with the value get_products to get a list of products available on the platform with their IDs, related names and corresponding HS codes. To get all products related to a particular HS-code, you need to specify the HS code in the request.
The response to a request is a JSON string. The response always delivers an array. Structure of the response to a request to search for the ID of a product by its HS code:
The id_prod from the response is required to get data for a specific product in the get_data action.
HTTP request example:
/api_v2/?action=get_products&hs_code=0803&api_key=YOUR_API_KEY
Response example:
[
{
"id_prod": "0803",
"name": "Bananas and Plantains",
"hs": "080300,080310,080390"
},
{
"id_prod": "080310",
"name": "Plantains",
"hs": "080310"
},
{
"id_prod": "080390",
"name": "Bananas",
"hs": "080390"
}
]
Get data
Use the action parameter with the value get_data to get data from the platform.
The id_prod field indicates the product ID that was obtained from the “Product search” request. The region field indicates the code value from the “List of regions” request. The region-related code may correspond to either a country (see “Glossary“) or a region (i.e., a group of countries, see “Glossary“). Attention! Leading zeros cannot be removed from code or id_prod if they are present!
The response to a request is a JSON string. Structure of the response covers the data and reflects the below mentioned parameters.
Annual or monthly data
There are two types of data in terms of period granularity: annual and monthly.
When requesting annual data, you must use the start and finish year parameters year_start and year_finish . Also in this case there should be a monthly parameter with a value of 0 .
If monthly data is required, then in addition to the year_start and year_finish parameters, you must also specify the starting and finishing months in the values of the month_start and month_finish parameters within the range between 1 (January) to 12 (December). Also in this case there should be a monthly parameter with a value of 1 .
Total data or countrywise breakdown
Annual and monthly data can be obtained for a selected combination of product/region in two possible ways:
- the total volume of a factor (e.g, imports/exports) for a country for a selected period. To get this data, you need to pass value 0 in the countrywise parameter.
- with a breakdown by country (see details below). To get the countrywise breakdown, pass 1 into this parameter, otherwise pass 0 .
In case if a region (e.g, “Asia”, code=966, see “Glossary“ for term explanation) is selected, the countrywise=1 parameter will return values for each country from the list of respective countries that belong to the region, for a single selected factor (see “Factor selection” below). Otherwise, having countrywise=0 , the call will return total values for the selected region for all factors (factor selection is disabled in this case).
In case if a country (e.g, “China”, code=156, see “Glossary“ for term explanation) is selected, the countrywise=1 parameter will return values for the list of country’s trade partners (i.e. import suppliers or export destinations), for a single selected factor (see “Factor selection” below). Otherwise, having countrywise=0 , the call will return total values for the selected country for all factors (factor selection is disabled in this case).
Factor selection
If you need to obtain data with the countrywise breakdown as described above, then you must pass 1 as the countrywise value, and also use the factor parameter, which is required in this case, the values of which are given below.
Below is the full list of factors available through the API. This list of factors is available for annual data when a region (e.g, “Asia”, code=966, see “Glossary“ for term explanation) is selected with the countrywise parameter = 1 . For some products, the list of available factors may differ due to the factor reasonability (e.g, for the “Wheat” product, “Harvested area” is available, but “Producing animals” is not relevant and not available). Each request returns the maximum possible number of factors.
Below is the list of factors available for annual data when a country (e.g, “China”>, code=156) is selected with the countrywise parameter = 1 . In case countrywise = 0 is selected, the full list of the applicable factors will be retrieved as described above.
Monthly data is available only for the following factors regardless what country or region is selected:
Response layout selection
The response to any request is a JSON string. There are two types of JSON layout: nested (default) and tabular. To switch between the nested and tabular layouts, use the layout parameter in your request.
Default layout
By default, the JSON contains nested structures, with values grouped by idprod, HS codes, region, period, and factor. To use the DEFAULT LAYOUT, simply do not use the layout parameter in your request. Here is a typical structure of the nested (default) response to a request for a product/region pair:
If there is no data in any field, null will be returned.
Monthly data are available from January, 2019 to the most recent period, which is individual for each particular country, but cannot be more than the current month. In case you will specify the time period ( year_start , year_finish , month_start , month_finish ) out of this range in your request, the API will nevertheless return data for the most extensive period available for the specified country.
The value of the unit parameter will contain information about the units of measurement for each of the retrieved factors, whether the request was for partner countries and a specific factor, or for a list of countries and one single factor.
Tabular layout
To use the TABULAR LAYOUT, add the layout parameter = tab to your request.
This will change the layout so that each combination of JSON keys (e.g. datatype, year, value type) will become a separate row in a table. The conversion will involve creating rows with columns such as country, year, factor (for example, "Consumption Volume", "Import Volume", etc.), as well as specific values (res, raw, mir). This will allow you to conveniently present the data in a more traditional tabular form, where each row contains all the necessary information on a separate indicator for a specific year.
Here is a typical structure of the tabular response to a request for a product/region pair:
HTTP request example:
/api_v2/?action=get_data&id_prod=0803®ion=250&monthly=0&year_start=2012&year_finish=2013&countrywise=1&factor=import_price&layout=tab&api_key=YOUR_API_KEY
Response example:
[
{
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"year": 2012,
"partner": "Afghanistan",
"factor_name": "Import Price",
"unit": "USD per kg",
"res": 1.135147,
"raw": 1.135132,
"mir": null
},
{
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"year": 2013,
"partner": "Afghanistan",
"factor_name": "Import Price",
"unit": "USD per kg",
"res": 1.001012,
"raw": 0.464864,
"mir": null
},
{
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"year": 2012,
"partner": "Austria",
"factor_name": "Import Price",
"unit": "USD per kg",
"res": 0.999736,
"raw": 0.999741,
"mir": 1.033823
}
]
Response and request examples for a product/region pair
Request annual data by product/region
Request structure and description of parameters used:
HTTP request example:
/api_v2/?action=get_data&id_prod=0803®ion=250&monthly=0&year_start=2012&year_finish=2012&countrywise=0&api_key=YOUR_API_KEY
Response example:
{
"data": {
"Consumption Volume": {
"2012": {
"res": 3200,
"raw": 3200,
"mir": 2643
}
},
"Consumption Value": {
"2012": {
"res": 25955,
"raw": 2594,
"mir": 1833
}
},
"Import Volume": {
"2012": {
"res": 5865,
"raw": 5865,
"mir": 4275
}
},
"Import Value": {
"2012": {
"res": 4753,
"raw": 4753,
"mir": 3001
}
},
"Export Volume": {
"2012": {
"res": 2664,
"raw": 2665,
"mir": 1631
}
},
"Export Value": {
"2012": {
"res": 2001,
"raw": 2001,
"mir": 1285
}
},
"Import Price": {
"2012": {
"res": 0.81,
"raw": 0.81,
"mir": 0.70
}
},
"Export Price": {
"2012": {
"res": 0.75,
"raw": 0.75,
"mir": 0.78
}
},
"Per Capita Consumption": {
"2012": {
"res": 0.0048,
"raw": 0.0048,
"mir": 0.0040
}
},
"Net Export Volume": {
"2012": {
"res": -3200,
"raw": -3200,
"mir": -2643
}
},
"Net Export Value": {
"2012": {
"res": -2752,
"raw": -2752,
"mir": -1715
}
}
},
"unit": "kg",
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"year_start": 2012,
"year_finish": 2012
}
Request monthly data by product/region
Request structure and description of parameters used:
HTTP request example:
/api_v2/?action=get_data&id_prod=0803®ion=250&monthly=1&year_start=2020&year_finish=2020&month_start=1&month_finish=2&countrywise=0&api_key=YOUR_API_KEY
Response example:
{
"data": {
"Import Volume": {
"202001": {
"raw": 5349
},
"202002": {
"raw": 6465
}
},
"Import Value": {
"202001": {
"raw": 4396
},
"202002": {
"raw": 5463
}
},
"Export Volume": {
"202001": {
"raw": 1880
},
"202002": {
"raw": 1527
}
},
"Export Value": {
"202001": {
"raw": 1304
},
"202002": {
"raw": 1159
}
},
"Import Price": {
"202001": {
"raw": 0.82
},
"202002": {
"raw": 0.84
}
},
"Export Price": {
"202001": {
"raw": 0.69
},
"202002": {
"raw": 0.75
}
},
"Net Export Volume": {
"202001": {
"raw": -3469
},
"202002": {
"raw": -4937
}
},
"Net Export Value": {
"202001": {
"raw": -3091
},
"202002": {
"raw": -4303
}
}
},
"unit": "kg",
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"month_start": 1,
"month_finish": 2,
"year_start": 2020,
"year_finish": 2020
}
Request for annual data by product/factor and partner countries
Request structure and description of parameters used:
In case if a collective region is selected, the countrywise = 1 parameter will return values for each country from the list of respective countries that belong to the region.
In case if a single country is selected, the countrywise = 1 parameter will return values for the list of country’s trade partners (e.g., import suppliers or export destinations).
The factor parameter must also be used with this parameter. Data will be obtained only for the specified factor and for all respective countries.
HTTP request example:
/api_v2/?action=get_data&id_prod=0803®ion=250&monthly=0&year_start=2012&year_finish=2012&countrywise=1&factor=import_price&api_key=YOUR_API_KEY
Response example:
{
"data": {
"Afghanistan": {
"2012": {
"res": 1.13,
"raw": 1.13,
"mir": null
}
},
"Austria": {
"2012": {
"res": 0.99,
"raw": 0.99,
"mir": 1.03
}
}
},
"unit": "USD per kg",
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"factor_name": "Import Price",
"year_start": 2012,
"year_finish": 2012
}
Request for monthly data by product/factor and partner countries
Request structure and description of parameters used:
In case if a collective region is selected, the countrywise = 1 parameter will return values for each country from the list of respective countries that belong to the region.
In case if a single country is selected, the countrywise = 1 parameter will return values for the list of country’s trade partners (e.g., import suppliers or export destinations).
The factor parameter must also be used with this parameter. Data will be obtained only for the specified factor and for all respective countries.
HTTP request example:
/api_v2/?action=get_data&id_prod=0803®ion=250&monthly=1&year_start=2020&year_finish=2020&month_start=1&month_finish=2&countrywise=1&factor=import_price&api_key=YOUR_API_KEY
Response example:
{
"data": {
"Austria": {
"202001": {
"raw": 0.48
},
"202002": {
"raw": null
}
},
"Bangladesh": {
"202001": {
"raw": 2.62
},
"202002": {
"raw": 2.13
}
}
},
"unit": "USD per kg",
"id_prod": "0803",
"hs_code": "080300,080310,080390",
"region": "France",
"factor_name": "Import Price",
"month_start": 1,
"month_finish": 2,
"year_start": 2020,
"year_finish": 2020
}
Units of measurement
Unless specified otherwise, the values in physical terms are presented in units relevant to each particular product (units of weight, volume, or number of items). The list of units and the relevant API codes is presented in the table below.
In monetary terms, the indicators are presented at the current U.S. dollars. (nominal values for each particular year, not adjusted to inflation). Secondary factors (i.e, those calculated from other factors) are presented in units relevant for a particular product.
| Unit of measure | API code |
|---|---|
| Kilograms | kg |
| Number of items | units |
| Cubic meters | m3 |
| Square meters | m2 |
| Number of pairs | 2u |
| Volume in litres | litres |
| Weight in carats | carats |
| USD per unit of measurement | USD per “unit” |
| Kilograms per carcass | kg per “unit” |
| Hectares | ha |
| Numbers of producing animals slaughtered | heads |
| Per capita consumption | “unit” per person |
Data categories (raw/mirror/normalized)
The system uses the following data categories:
| Data category | API code | Explanation |
|---|---|---|
| Raw | raw | Data obtained directly from a primary source. With regard to import/export, this also means that this is ‘direct’ data, i.e. the data reported directly from a particular country. |
| Mirror | mir | This data refers to import/export only. This data reflects imports/exports for a particular country, but the data is obtained by ‘mirroring’ trade flow data reported by a country’s trade partners. |
| Normalized | res | Data obtained after combining raw and mirror data and performing IndexBox AI algorithms to eliminate any data anomalies and complete missing data. |
Example how raw and mirror data concepts work:
Raw data: COUNTRY_A reported imports 1000t of avocados from COUNTRY_B in 2010. Thus, raw imports for COUNTRY_A = 1000 tons in 2010.
Mirror data: COUNTRY_C did not report any avocado imports from COUNTRY_B in 2010, so the raw data is ‘0’. But when we check exports of avocados, we find that COUNTRY_B reported 200t of avocados exported to COUNTRY_C (despite the recipient country reported nothing). Thus, COUNTRY_C raw data for 2010 is ‘0’, but the mirror data is ‘200’.
Please refer to a further explanation here: https://app.indexbox.io/meta
Example how raw and mirror data concepts work:
Raw data: COUNTRY_A reported imports 1000t of avocados from COUNTRY_B in 2010. Thus, raw imports for COUNTRY_A = 1000 tons in 2010.
Mirror data: COUNTRY_C did not report any avocado imports from COUNTRY_B in 2010, so the raw data is ‘0’. But when we check exports of avocados, we find that COUNTRY_B reported 200t of avocados exported to COUNTRY_C (despite the recipient country reported nothing). Thus, COUNTRY_C raw data for 2010 is ‘0’, but the mirror data is ‘200’.
Please refer to a further explanation here: https://app.indexbox.io/meta
Error reporting
The IndexBox API uses a simple error reporting mechanism to indicate the success or failure of a request. In case of an error, an array will be returned in the form of a JSON string with the error statement, the contents of which will explain the reason for the failure.
Typical values for the error statements: