Insights API Usage
The IBM Food Trust™ Insights API enables developers to retrieve scanned and sensor-generated (IoT) data for supply chain and cold chain food product instances. These product metrics can be retrieved from IBM Food Trust at multiple levels, such as individual product lots, cases, containers and pallets, for specific locations and sublocations (zones).
See the Swagger page for details on all Insights API endpoints.
Insights REST API call format: https:</endpoint>?q={"<key>": "<value>", "<key>": "<value>"}
Retrieving consumable and actionable supply chain and cold chain data for product instances is dependent upon the participating supply chain Organizations having uploaded the applicable data in a supported format, as described in detail in Insights Data. The general rules for Insights data prerequisites are as follows:
- Each time a product instance enters a location, a qualifying entry event must be uploaded to IBM Food Trust.
- Each time a product instance exits a location, a qualifying exit event must be uploaded to IBM Food Trust.
Refer to details on qualifying Insights entry events and exit events in Insights Data.
Understanding of the following Insights terms and definitions facilitates API usage:
Temperature minutes above - Total number of minutes a food product instance spent above the maximum user-defined temperature.
Temperature minutes below - Total number of minutes the food product instance spent below the maximum user-defined temperature.
Temperature exception - Aggregated time of temperature sensor readings above or below the user-defined temperature parameters for a food product instance. Temperature exceptions are returned for the specified location and product, or for all locations or all products if left blank.
Example: Frozen peas were recorded above the maximum permitted temperature for 30 total minutes.
The diagram below (Figure 1) demonstrates temperature exceptions—the total time recorded above or below user-defined temperature parameters:
Figure 1. Temperature exceptions
Inventory - Volume of product at specified time and location.
In transit - Inventory between locations (following an exit event but prior to a subsequent entry event).
Dwell time - Time a product spent at a location. Specifying a location returns all product instances at the location. Specifying a product instance returns all locations for the product.
Product Class - The type of product (e.g. Lettuce), which will have multiple product instances. Product class is identified by a GS1 GTIN (Global Trade Item Number) or IBM Food Trust Product Number.
Product Instance - The specific instance of a product class (e.g. Lettuce Lot# abc.123), in SGTIN (Serial GTIN), (LGTIN (Lot GTIN), or SSCC (Serial Shipping Container Code) format or their corresponding IBM Food Trust Identifiers format.
Location - Facility ID where product events occur, as GLN (Global Location Number) format, or the corresponding IBM Food Trust Identifiers format.
Sublocation - Facility ID + non-zero extension for an area (e.g. floor or zone) within a Location where product events occur, as GLN (Global Location Number) format, or the corresponding IBM Food Trust Identifiers format.
Location Type (party_role_code) - Facility type: FARM, PROCESSING_FACILITY, PROCESSING_PLANT, DISTRIBUTION_CENTER