Fieldprint API – /v5/ScaledBenchmarks
/v5/ScaledBenchmarks
The ScaledBenchmarks endpoint returns scaled sustainability scoring for a farmer’s field across all Fieldprint Platform metrics. Given raw metric results (from the /v5/Calculator endpoint or equivalent), it compares them against state and national benchmarks and returns a scaled score (0–100) indicating how the field performs relative to other fields producing the same crop.
This endpoint is commonly used to power visual displays of farmer performance, such as the Fieldprint Analysis spider chart in the Fieldprint Platform UI.
Endpoint Details
| Endpoint | POST https://api.fieldtomarket.org/v5/ScaledBenchmarks |
|---|---|
| Authentication | API Key (provided by Field to Market) |
| Content-Type | application/json |
| Response Format | JSON |
Request Body
The request body is a JSON object containing the crop, location, irrigation status, and the raw metric values to be scored against benchmarks.
Input Fields
| Field | Type | Required | Description |
|---|---|---|---|
crop_id |
integer | Yes | Numeric crop identifier from the /v5/ReferenceData/Crops endpoint. For example, 1 = Corn (grain). |
isIrrigated |
boolean | Yes | Whether the field is irrigated. Affects which benchmark distributions are used for comparison. |
state |
string | Yes | Two-letter US state abbreviation (e.g., "IA" for Iowa). Used to look up state-level benchmarks. |
metrics |
object | Yes | An object containing the raw fieldprint results to be scaled. See Metric Input Fields below. |
Metric Input Fields (metrics object)
Each metric value within the metrics object represents the raw fieldprint result from the Calculator. Most metrics require both a value and a unit; Water Quality and Biodiversity are unitless scores.
| Field | Type | Description |
|---|---|---|
metrics.landUse |
object: { value, unit } |
Land Use Efficiency result. Units vary by crop, e.g., "acre / bushel" for grain crops. |
metrics.soilConservation |
object: { value, unit } |
Soil Conservation result. Typically "ton / acre / year". |
metrics.irrigationWaterUse |
object: { value, unit } |
Irrigation Water Use result. E.g., "acre_inch / bushel". Only relevant if isIrrigated is true. |
metrics.energyUse |
object: { value, unit } |
Energy Use result. E.g., "btu / bushel". |
metrics.greenhouseGas |
object: { value, unit } |
Greenhouse Gas Emissions result. E.g., "lbs_co2e / bushel". |
metrics.waterQuality |
integer | Water Quality score (STEP index, integer value). |
metrics.biodiversity |
float | Biodiversity score (Habitat Potential Index, 0–1 float value). |
Example Request
{
"crop_id": 1,
"isIrrigated": true,
"state": "IA",
"metrics": {
"biodiversity": 0.88,
"energyUse": {
"unit": "btu / bushel",
"value": 98699
},
"greenhouseGas": {
"unit": "lbs_co2e / bushel",
"value": 20.8
},
"irrigationWaterUse": {
"unit": "acre_inch / bushel",
"value": 0.043
},
"landUse": {
"unit": "acre / bushel",
"value": 0.0068
},
"soilConservation": {
"unit": "ton / acre / year",
"value": 5.7
},
"waterQuality": 1
}
}
Response Body
The response returns the scaled scores for each metric, along with state and national benchmark values for context.
Top-Level Fields
| Field | Type | Description |
|---|---|---|
isIrrigated |
boolean | Echoed from the request input. |
crop |
string | Human-readable crop name resolved from the crop_id input. |
state |
string | Echoed from the request input. |
Per-Metric Response Structure
Each metric in the response (e.g., landUse, soilConservation, energyUse, greenhouseGas, irrigationWaterUse) contains the following fields:
| Field | Type | Description |
|---|---|---|
fieldprintResult.value |
float | The raw metric value provided in the request. |
fieldprintResult.unit |
string | The unit of measurement for the metric. |
scaledFieldprintResult |
float | The scaled score (0–100) representing where this field falls within the distribution of all fields. Higher values indicate the field is using more resources relative to peers (see note below). |
benchmarks.state.fieldprintResult |
object | The average (mean) metric value for this crop in the specified state, with value and unit. |
benchmarks.state.scaledFieldprintResult |
float | The scaled score for the state benchmark itself. |
benchmarks.national.fieldprintResult |
object | The national average metric value for this crop, with value and unit. |
benchmarks.national.scaledFieldprintResult |
float | The scaled score for the national benchmark. |
benchmarks.scaleBasis |
string | Indicates which benchmark was used for scaling: "State", "National", or "N/A" if no benchmark data is available. |
Note on Water Quality & Biodiversity: These two metrics use index-based scoring rather than unit-based measurement. Their response structure differs slightly —
fieldprintResult contains value and index (instead of unit), and they do not include state/national benchmark comparisons. The index field indicates the scoring system used (e.g., "STEP" for Water Quality, "HPI" for Biodiversity).
Understanding Scaled Scores
The scaledFieldprintResult is a percentile-based score from 0 to 100, derived from the cumulative distribution of all fields producing the same crop. The scaling is based on comparing the field’s raw result to the benchmark mean:
- A score near 50 means the field is performing close to the average.
- A score near 0 means the field is among the lowest resource users (best for resource efficiency metrics).
- A score near 100 means the field is among the highest resource users.
The scaleBasis field tells you whether the state-level or national-level benchmark was used as the reference point. State benchmarks are preferred when available; the system falls back to national benchmarks when state data is insufficient.
Example Response
{
"isIrrigated": true,
"crop": "Corn (grain)",
"state": "IA",
"landUse": {
"fieldprintResult": {
"value": 0.0068,
"unit": "acre / bushel"
},
"scaledFieldprintResult": 88.29545,
"benchmarks": {
"state": {
"fieldprintResult": {
"value": 0.00566152,
"unit": "acre / bushel"
},
"scaledFieldprintResult": 70.33333
},
"national": {
"fieldprintResult": {
"value": 0.00571211,
"unit": "acre / bushel"
},
"scaledFieldprintResult": 71.59923
},
"scaleBasis": "State"
}
},
"soilConservation": {
"fieldprintResult": {
"value": 5.7,
"unit": "ton / acre / year"
},
"scaledFieldprintResult": 90.87418,
"benchmarks": {
"state": {
"fieldprintResult": {
"value": 3.21246532,
"unit": "ton / acre / year"
},
"scaledFieldprintResult": 62
},
"national": {
"fieldprintResult": {
"value": 3.59932336,
"unit": "ton / acre / year"
},
"scaledFieldprintResult": 70.0212
},
"scaleBasis": "State"
}
},
"irrigationWaterUse": {
"fieldprintResult": {
"value": 0.043,
"unit": "acre_inch / bushel"
},
"scaledFieldprintResult": 0,
"benchmarks": {
"state": {
"fieldprintResult": {
"value": 0.6913444,
"unit": "acre_inch / bushel"
},
"scaledFieldprintResult": 69.78261
},
"national": {
"fieldprintResult": {
"value": 0.19127557,
"unit": "acre_inch / bushel"
},
"scaledFieldprintResult": 3.94466
},
"scaleBasis": "State"
}
},
"energyUse": {
"fieldprintResult": {
"value": 98699.0,
"unit": "btu / bushel"
},
"scaledFieldprintResult": 97.50148,
"benchmarks": {
"state": {
"fieldprintResult": {
"value": 37664.14917566,
"unit": "btu / bushel"
},
"scaledFieldprintResult": 69
},
"national": {
"fieldprintResult": {
"value": 48699.29751561,
"unit": "btu / bushel"
},
"scaledFieldprintResult": 81.8247
},
"scaleBasis": "State"
}
},
"greenhouseGas": {
"fieldprintResult": {
"value": 20.8,
"unit": "lbs_co2e / bushel"
},
"scaledFieldprintResult": 94.6216,
"benchmarks": {
"state": {
"fieldprintResult": {
"value": 11.46262823,
"unit": "lbs_co2e / bushel"
},
"scaledFieldprintResult": 72
},
"national": {
"fieldprintResult": {
"value": 11.39536712,
"unit": "lbs_co2e / bushel"
},
"scaledFieldprintResult": 71.43669
},
"scaleBasis": "State"
}
},
"waterQuality": {
"fieldprintResult": {
"value": 1,
"index": "STEP"
},
"scaledFieldprintResult": 75.0
},
"biodiversity": {
"fieldprintResult": {
"value": 0.88,
"index": "HPI"
},
"scaledFieldprintResult": 12.0
}
}
Validation Errors
If the request contains invalid data, the API will return error details. Common validation errors include:
| Error Code | Field | Description |
|---|---|---|
REQUIRED |
crop_id |
A crop identifier must be specified. |
CHOICE |
crop_id |
The provided crop_id is not a valid choice. Use /v5/ReferenceData/Crops to get valid crop IDs. |
UNITS |
Various metrics | The provided units don’t match the expected units for the crop. Units vary by crop type (e.g., grain crops use per-bushel units, while sugar crops use per-ton units). |
TYPE |
metrics.biodiversity |
The value could not be converted to the expected type (e.g., a string was provided where a float was expected). |
Usage Notes
Typical Workflow: The
/v5/ScaledBenchmarks endpoint is typically used after calling the /v5/Calculator endpoint. The Calculator returns raw fieldprint results, which are then passed into ScaledBenchmarks to obtain the percentile-based scaled scores and benchmark comparisons needed for farmer-facing displays.
Units Must Match: The units provided in the
metrics input must match the units returned by the Calculator for the specific crop. Units vary by crop type — for example, grain crops use "bushel"-based denominators while sugar crops use "ton_sugar"-based denominators. Use the Calculator output units directly to avoid UNITS validation errors.
Scale Basis Fallback: The system prefers state-level benchmarks for scoring. If state benchmarks are not available for a given crop/state combination, it falls back to national benchmarks. The
scaleBasis field in the response indicates which level was used. If the field is not irrigated and no benchmarks exist, scaleBasis will return "N/A".
Related Endpoints
| Endpoint | Description |
|---|---|
/v5/Calculator |
Computes raw sustainability metric results for a field. Provides the inputs needed for ScaledBenchmarks. |
/v5/ReferenceData/Crops |
Returns the list of valid crop IDs and names for use in API requests. |