Grade

Use these endpoints to retrieve fruit size, colour, and blemish data collected for a specific orchard and measurement date. The data supports two aggregation types:

Fruit-level measurements (fruit_unit: fruit) — Returns size, colour, and blemish distributions aggregated per fruit.
Bunch-level measurements (fruit_unit: bunch) — Returns size, colour, and blemish distributions aggregated per bunch. Pass include=bunch_detail on the detailed endpoint to include bunch dimension fields.

The fruit_unit response field indicates how the data is aggregated. For Grape orchards, data is returned on a bunch level with fruit_unit: "bunch". In all other cases, data is returned on a fruit level with fruit_unit: "fruit".

The measurements endpoint returns data aggregated by orchard and date, while the detail endpoint returns the full distribution data and sample position averages for a single orchard and date.

Recommended patterns for fetching TrueFruit grade data

How to fetch fruit size, colour and blemish distributions per orchard

First pull per orchard grade measurement dates for a given time period using the farming/truefruit/grade/measurements/ endpoint. The response will return a list of objects containing an orchard_id and measurement_date. Filter the response using the processed_date query parameter. Using the processed_date is the most robust approach because it avoids losing records where there is a large delay between the data collection date 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_id and measurement_date received in the farming/truefruit/grade/measurements/ response into the farming/truefruit/grade/measurements/{orchard_id}/{measurement_date} endpoint.

Optional parameters

Use include=bunch_detail on the detailed endpoint when you need bunch dimension fields in the response. Without this parameter, the response includes the standard grade detail fields only.

Grade 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.
`count_fruit_measured`	integer	Total number of fruit included in the size distribution.
`fruit_unit`	string	Describes the level of data aggregation used in the distributions. For Grapes, the data is aggregated on the bunch level. For all other crops, the data is aggregated on the piece level.

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": 63.8,
      "count_fruit_measured": 1240,
      "fruit_unit": "fruit"
    }
  ]
}

Grade 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]	An array of size distribution records that can be used to build a histogram of fruit sizes.
`blemish_distribution[]`	[Grade Distribution Record]	An array of grade distribution records that can be used to build a histogram of blemish severity.
`color_distribution[]`	[Grade Distribution Record]	An array of grade distribution records that can be used to build a histogram of fruit colour categories.
`average_fruit_size_mm`	number	The average fruit size.
`count_fruit_measured`	integer	The number of individual fruit measured.
`fruit_unit`	string	Describes the level of data aggregation used in the distributions. For Grapes, the data is aggregated on the bunch level. For all other crops, the data is aggregated on the piece level.
`average_bunch_width_mm`	integer \| null	The average bunch width in millimeters. Returned when `include=bunch_detail` is passed.
`bunch_width_distribution[]`	[Bunch Dimension Distribution Record]	The distribution of bunch widths bucketed by mm ranges. Returned when `include=bunch_detail` is passed.
`average_bunch_length_mm`	integer \| null	The average bunch length in millimeters. Returned when `include=bunch_detail` is passed.
`bunch_length_distribution[]`	[Bunch Dimension Distribution Record]	The distribution of bunch lengths bucketed by mm ranges. Returned when `include=bunch_detail` is passed.
`count_sample_positions`	integer	Number of unique geolocations where data was collected within the orchard.
`sample_positions[]`	[Sample Position Record]	An array of sample position records with GPS coordinates and per-position averages.

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.

Bunch Dimension Distribution Record

Key	Type	Description
`bin_range`	string	Size range of the histogram bin in millimeters.
`percentage`	number	Percentage of bunches that fall within the corresponding bin range.

Sample Position Record

Key	Type	Description
`sample_position_id`	integer	Unique identifier for a sample position.
`latitude`	number	Latitude of the sample position location.
`longitude`	number	Longitude of the sample position location.
`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 for the sample position.
`fruit_unit`	string	The unit used for the sample position data.
`average_bunch_width_mm`	number \| null	The average bunch width in millimeters. Returned when `include=bunch_detail` is passed.
`average_bunch_length_mm`	number \| null	The average bunch length in millimeters. Returned when `include=bunch_detail` is passed.

Example response with include=bunch_detail

{
  "farm_id": 1234,
  "orchard_id": 5678,
  "measurement_date": "2025-11-15",
  "processed_date": "2025-11-16",
  "size_distribution": [
    {
      "bin_range": "18-19",
      "percentage": 32.0,
      "label": null
    },
    {
      "bin_range": "20-21",
      "percentage": 45.5,
      "label": null
    },
    {
      "bin_range": "22-23",
      "percentage": 22.5,
      "label": null
    }
  ],
  "blemish_distribution": null,
  "color_distribution": null,
  "average_fruit_size_mm": 20.4,
  "count_fruit_measured": 240,
  "fruit_unit": "bunch",
  "average_bunch_width_mm": 128,
  "bunch_width_distribution": [
    {
      "bin_range": "120-129",
      "percentage": 48.0
    },
    {
      "bin_range": "130-139",
      "percentage": 52.0
    }
  ],
  "average_bunch_length_mm": 176,
  "bunch_length_distribution": [
    {
      "bin_range": "170-179",
      "percentage": 61.0
    },
    {
      "bin_range": "180-189",
      "percentage": 39.0
    }
  ],
  "count_sample_positions": 2,
  "sample_positions": [
    {
      "sample_position_id": 101,
      "latitude": -33.9249,
      "longitude": 18.4241,
      "average_fruit_size_mm": 20.1,
      "count_fruit_measured": 118,
      "fruit_unit": "bunch",
      "average_bunch_width_mm": 126.0,
      "average_bunch_length_mm": 174.0
    },
    {
      "sample_position_id": 102,
      "latitude": -33.9251,
      "longitude": 18.4243,
      "average_fruit_size_mm": 20.7,
      "count_fruit_measured": 122,
      "fruit_unit": "bunch",
      "average_bunch_width_mm": 130.0,
      "average_bunch_length_mm": 178.0
    }
  ]
}