Retrieve TrueFruit Bin Scan measurements by orchard and date, including size, colour, blemish, picking quality, and optional intake or bin breakdowns.
Use these endpoints to retrieve fruit size, colour, blemish, and picking quality data captured after fruit has been picked and scanned in bins. The data supports two response types:
- Orchard-level results (
granularity: orchard) — Returns distributions aggregated across all scanned bins for a specific orchard and measurement date. - Bin and intake results (
granularity: bin_grouporgranularity: bin) — Returns the same distributions broken down by intake or individual bin inbin_distributions.
The measurements endpoint returns data aggregated by orchard and date, while the detail endpoint returns the full orchard-level distributions for a single orchard and date. Use granularity on the detail endpoint when you need intake-level or bin-level breakdowns.
Recommended patterns for fetching TrueFruit bin scan data
How to fetch Bin Scan size and grade distributions per orchard
- First pull per orchard size measurement dates for a given time period using the
farming/truefruit/binscan/measurements/endpoint. The response returns a list of objects containing anorchard_idandmeasurement_date. Filter the response using theprocessed_datequery parameter. Using theprocessed_dateis the most robust approach because it avoids missing records where there was a delay between when the data was collected and when it became available to consume. If you are fetching data on a cron, for example once a day, use the date you last fetched data on. - To fetch the detailed orchard distributions and aggregated metrics, pass the
orchard_idandmeasurement_datereceived in thefarming/truefruit/binscan/measurements/response into thefarming/truefruit/binscan/measurements/{orchard_id}/{measurement_date}endpoint. By default, the response returns orchard-level aggregates.
How to fetch Bin Scan size and grade distributions per intake
- First pull per orchard size measurement dates for a given time period using the
farming/truefruit/binscan/measurements/endpoint. - Pass the
orchard_idandmeasurement_datereceived in the measurements response into thefarming/truefruit/binscan/measurements/{orchard_id}/{measurement_date}endpoint. - Set
granularity=bin_groupto retrievebin_distributionsrecords aggregated by intake. Each record includes the associated intake number in thebin_group_idfield.
Optional parameters
Use these query parameters on the detailed endpoint when you need a different response shape:
granularity— Controls the level of detail returned inbin_distributions:orchard(default),bin_group, orbin.size_distribution_format— Changes the bucket ranges used in size distributions. Supported values:1mm,2mm,2.5mm,5mm,harvest_ranges_by_weight,harvest_ranges_by_pieces, andharvest_ranges(deprecated).
Bin Scan Measurement Compact
| Key | Type | Description |
|---|---|---|
farm_id | integer | The unique identifier of the farm, provided by Aerobotics, which the measurement belongs to. |
orchard_id | integer | The unique identifier of the orchard, provided by Aerobotics, which the measurement belongs to. |
measurement_date | date | The date on which the data was collected. |
processed_date | date | The date on which the data completed processing. |
average_fruit_size_mm | number | The average fruit size of the distribution in millimeters. |
count_fruit_measured | integer | Total number of fruit included in the size distribution. |
Example response
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"farm_id": 1234,
"orchard_id": 5678,
"measurement_date": "2025-11-15",
"processed_date": "2025-11-16",
"average_fruit_size_mm": 67.4,
"count_fruit_measured": 8420
}
]
}Bin Scan Measurement Detailed
| Key | Type | Description |
|---|---|---|
farm_id | integer | The unique identifier of the farm, provided by Aerobotics, which the measurement belongs to. |
orchard_id | integer | The unique identifier of the orchard, provided by Aerobotics, which the measurement belongs to. |
measurement_date | date | The date on which the data was collected. |
processed_date | date | The date on which the data completed processing. |
size_distribution[] | [Size Distribution Record] | The size distribution of fruit bucketed by either mm ranges or harvest size categories. |
average_fruit_size_mm | number | The average fruit size of the distribution in millimeters. |
count_fruit_measured | integer | Total number of fruit included in the size distribution. |
blemish_distribution[] | [Grade Distribution Record] | null | An array of grade distribution records that can be used to build a histogram of blemish severity. |
color_distribution[] | [Grade Distribution Record] | null | An array of grade distribution records that can be used to build a histogram of fruit colour categories. |
count_bins | integer | The number of bins measured. |
bin_distributions[] | [Bin Distribution Record] | An array of per-bin or per-intake records. Returned when granularity is set to bin_group or bin. |
picking_quality | [Picking Quality Record] | null | Picking quality summary for the orchard-level response. |
Size Distribution Record
| Key | Type | Description |
|---|---|---|
bin_range | string | Size range of the histogram bin in millimeters. |
percentage | number | Percentage of fruit sizes that fall within the corresponding bin range. |
label | string | null | Name of the histogram bin range. Typically the harvest size category names. (optional) |
Grade Distribution Record
| Key | Type | Description |
|---|---|---|
label | string | Name of the histogram bin range defined by Aerobotics colour or blemish severity labels. |
percentage | number | Percentage of fruit that fall within the corresponding colour or blemish category. |
Picking Quality Record
| Key | Type | Description |
|---|---|---|
count_visible_stems | integer | Number of fruit with visible stems in the image. |
picking_quality_types[] | [Picking Quality Type Record] | A list of picking quality types and their percentage of fruit in each type. |
Picking Quality Type Record
| Key | Type | Description |
|---|---|---|
label | string | Picking quality type label. Classes include good_stem, long_stem, and pulled_stem. |
percentage | number | Percentage of fruit that fall within the corresponding picking quality type. |
Bin Distribution Record
| Key | Type | Description |
|---|---|---|
bin_id | integer | Unique identifier for a bin. Returned when available. |
bin_external_id | string | null | External system identifier for a bin. Returned when available. |
bin_group_id | string | null | External bin shipment, intake, or delivery number. Returned when available. |
latitude | number | null | Latitude of the bin location. |
longitude | number | null | Longitude of the bin location. |
blemish_distribution[] | [Grade Distribution Record] | null | Blemish severity distribution for the bin or intake. |
color_distribution[] | [Grade Distribution Record] | null | Colour distribution for the bin or intake. |
size_distribution[] | [Size Distribution Record] | Size distribution for the bin or intake. |
average_fruit_size_mm | number | The average fruit size of the distribution in millimeters. |
count_fruit_measured | integer | Total number of fruit included in the size distribution. |
picking_quality | [Picking Quality Record] | null | Picking quality summary for the bin or intake. |
Example orchard-level response
{
"farm_id": 1234,
"orchard_id": 5678,
"measurement_date": "2025-11-15",
"processed_date": "2025-11-16",
"size_distribution": [
{
"bin_range": "64-65",
"percentage": 18.0,
"label": null
},
{
"bin_range": "66-67",
"percentage": 41.5,
"label": null
},
{
"bin_range": "68-69",
"percentage": 40.5,
"label": null
}
],
"average_fruit_size_mm": 67.4,
"count_fruit_measured": 8420,
"blemish_distribution": [],
"color_distribution": [],
"count_bins": 24,
"picking_quality": {
"count_visible_stems": 214,
"picking_quality_types": [
{
"label": "good_stem",
"percentage": 83.2
},
{
"label": "long_stem",
"percentage": 10.5
},
{
"label": "pulled_stem",
"percentage": 6.3
}
]
}
}Example response with granularity=bin_group
{
"farm_id": 1234,
"orchard_id": 5678,
"measurement_date": "2025-11-15",
"processed_date": "2025-11-16",
"size_distribution": [
{
"bin_range": "64-65",
"percentage": 18.0,
"label": null
},
{
"bin_range": "66-67",
"percentage": 41.5,
"label": null
},
{
"bin_range": "68-69",
"percentage": 40.5,
"label": null
}
],
"average_fruit_size_mm": 67.4,
"count_fruit_measured": 8420,
"blemish_distribution": [],
"color_distribution": [],
"count_bins": 24,
"bin_distributions": [
{
"bin_group_id": "intake-001",
"latitude": -33.9249,
"longitude": 18.4241,
"size_distribution": [
{
"bin_range": "64-65",
"percentage": 24.0,
"label": null
},
{
"bin_range": "66-67",
"percentage": 39.0,
"label": null
},
{
"bin_range": "68-69",
"percentage": 37.0,
"label": null
}
],
"average_fruit_size_mm": 67.1,
"count_fruit_measured": 4010,
"blemish_distribution": [],
"color_distribution": [],
"picking_quality": {
"count_visible_stems": 96,
"picking_quality_types": [
{
"label": "good_stem",
"percentage": 81.0
},
{
"label": "long_stem",
"percentage": 12.0
},
{
"label": "pulled_stem",
"percentage": 7.0
}
]
}
}
]
}Example response with granularity=bin
{
"farm_id": 1234,
"orchard_id": 5678,
"measurement_date": "2025-11-15",
"processed_date": "2025-11-16",
"size_distribution": [
{
"bin_range": "64-65",
"percentage": 18.0,
"label": null
},
{
"bin_range": "66-67",
"percentage": 41.5,
"label": null
},
{
"bin_range": "68-69",
"percentage": 40.5,
"label": null
}
],
"average_fruit_size_mm": 67.4,
"count_fruit_measured": 8420,
"blemish_distribution": [],
"color_distribution": [],
"count_bins": 24,
"bin_distributions": [
{
"bin_id": 9001,
"bin_external_id": "BIN-001",
"latitude": -33.9249,
"longitude": 18.4241,
"size_distribution": [
{
"bin_range": "64-65",
"percentage": 22.0,
"label": null
},
{
"bin_range": "66-67",
"percentage": 38.0,
"label": null
},
{
"bin_range": "68-69",
"percentage": 40.0,
"label": null
}
],
"average_fruit_size_mm": 67.3,
"count_fruit_measured": 2050,
"blemish_distribution": [],
"color_distribution": [],
"picking_quality": {
"count_visible_stems": 52,
"picking_quality_types": [
{
"label": "good_stem",
"percentage": 82.0
},
{
"label": "long_stem",
"percentage": 11.0
},
{
"label": "pulled_stem",
"percentage": 7.0
}
]
}
}
]
}