Calculating using the CFT

This topic guide explains how to send data to the CFT’s calculation modules.

Note

  • calculate.py has Python examples of these methods

  • Data schemas are available for reference

  • This version of the API has significant changes to these methods; see changelog

  • The CFT now contains two calculation engines for irrigation.

    1. Using the volume of water, pumping depth and pumping distance.

    2. Using the volume of water only.

    Method 2, using volume only, uses factors provided by IPCC in 2013 based on geographical location, irrigation method and the power source.

  • The CFT has updated its machinery module, please see updated Data schemas The expected data has not changed much, except when using a baler type machine. To find out if you are using one, please check the Machine to see if you need to add an additional field number_of_bales to your machinery data.

Note

As of version 2.2, a new section called ‘Disaggregation Totals’ has been added to the calculate response.

When using either the Dairy or Crop Calculate endpoints, a new field named disaggregation_totals has been introduced. This field provides an breakdown of the total emissions attributable to each Constituent gas. No changes to your input JSON are required to receive this new field, as it’s now a default output.

Here’s an example of what the new disaggregation_totals field will look like in the response from within the summary field

{
    "disaggregation_totals": [
        {
            "CO2": {
                "metric_tonnes_CO2": [
                    "423.83",
                    "tonnes CO2"
                ],
                "metric_tonnes_CO2e": [
                    "423.83",
                    "tonnes CO2e"
                ]
            }
            "N2O": {
                "metric_tonnes_N2O": [
                    "0.36",
                    "tonnes N2O"
                ],
                "metric_tonnes_CO2e": [
                    "97.15",
                    "tonnes CO2e"
                ]
            },
            "CH4": {
                "metric_tonnes_CH4": [
                    "12.07",
                    "tonnes CH4"
                ],
                "metric_tonnes_CO2e": [
                    "336.82",
                    "tonnes CO2e"
                ]
            },
        }
    ]
}

All URLs start with /api/v1/.

Crop assessment

POST /crop_product/calculate/

Calculate emissions for a crop product, without saving it to the database

Example request

POST /crop_product/calculate/ HTTP/1.1
Host: app.coolfarmtool.org
Accept: application/json
Content-Type: application/json
[
  {
    "farm": {
      "country": "United States of America",
      "territory": "Alabama",
      "climate": "Warm Temperate Dry",
      "average_temperature": {
        "value": 15,
        "unit": "°C"
      },
      "soil_characteristics": "Sandy Soils",
      "farm_identifier": "",
      "latitude": 32.318,
      "longitude": -86.902
    },
    "crop": {
      "type": "Potato",
      "harvesting_year": 2022,
      "feed_type": null,
      "field_size": {
        "value": 100,
        "unit": "ha"
      },
      "soil": {
        "texture_id": 1,
        "organic_matter_id": 2,
        "drainage_id": 1,
        "ph_id": 4,
        "organic_matter_custom": null,
        "custom_measured_years_ago": 0
      },
      "product_fresh": {
        "value": 1000,
        "unit": "tonne"
      },
      "product_finished": {
        "value": 990,
        "unit": "tonne"
      },
      "residue": {
        "value": null,
        "unit": null,
        "management": "Left distributed on field, OR incorporated, OR mulched"
      },
      "seed_amount": {
        "value": 10,
        "unit": "tonne"
      },
      "irrigation_calculation_type": "volume_depth_distance_irrigation_type"
    },
    "pesticides": [
      {
        "type_id": 1,
        "category_id": 3,
        "percentage_rate": 100,
        "application_rate": {
          "value": 1,
          "unit": "kg / acre"
        }
      }
    ],
    "fertilisers": [
      {
        "type": "Compose your own NPK",
        "production": "Europe 2014",
        "custom_ingredients": {
          "n_total_percentage": 0.0,
          "n_ammonia_percentage": 0.0,
          "n_nitric_percentage": 0.0,
          "n_urea_percentage": 0.0,
          "p2o5_percentage": 0.0,
          "p2o5_percentage_type_id": 4,
          "k2o_percentage": 0.0,
          "k2o_percentage_type_id": 5
        },
        "application_rate": {
          "value": 15,
          "unit": "kg / ha"
        },
        "application_date": "unknown",
        "rate_measure": "product",
        "method": 2,
        "inhibition_id": 1
      }
    ],
    "machinery": [
      {
        "operations": 1,
        "machinery": 24,
        "fuel_type": "diesel (average biofuel blend)"
      }
    ],
    "irrigation": [
      {
        "method": 1,
        "water_source": 1,
        "allocation": 100,
        "pumping_depth": {
          "value": 1,
          "unit": "m"
        },
        "horizontal_distance": {
          "value": 2,
          "unit": "km"
        },
        "water_added": {
          "value": 2,
          "unit": "ha-mm"
        },
        "power_source": 1
      }
    ],
    "direct_energy": [
      {
        "category": "irrigation",
        "source": "diesel (average biofuel blend)",
        "usage": {
          "value": 1000,
          "unit": "litre"
        }
      }
    ],
    "land_management": {
      "carbon_changes": [
        {
          "year_of_change": 2021,
          "allocation": 100,
          "land_use": {
            "from": "cultivated",
            "to": "set-aside"
          },
          "tillage": {
            "from": "reduced",
            "to": "no-till"
          },
          "inputs": {
            "from": "low-c-input",
            "to": "high-c-input-with-manure"
          }
        },
        {
          "year_of_change": 2020,
          "allocation": 44,
          "land_use": {
            "from": "native-forest",
            "to": "cultivated"
          },
          "tillage": {
            "from": "full",
            "to": "reduced"
          },
          "inputs": {
            "from": "high-c-input-without-manure",
            "to": "low-c-input"
          }
        },
        {
          "year_of_change": 2019,
          "allocation": 100,
          "land_use": {
            "from": "native-forest",
            "to": "native-forest"
          },
          "tillage": {
            "from": "reduced",
            "to": "full"
          },
          "inputs": {
            "from": "high-c-input-with-manure",
            "to": "high-c-input-without-manure"
          }
        },
        {
          "year_of_change": 2017,
          "allocation": 29,
          "land_use": {
            "from": "native-forest",
            "to": "native-forest"
          },
          "tillage": {
            "from": "no-till",
            "to": "reduced"
          },
          "inputs": {
            "from": "medium-c-input",
            "to": "high-c-input-with-manure"
          }
        }
      ],
      "forest_biomass": {
        "age_years": 5,
        "type": "boreal mountain system"
      }
    },
    "transport": [
      {
        "mode": "road LGV diesel (light goods vehicle <3.5t)",
        "weight": {
          "value": 4,
          "unit": "tonne"
        },
        "distance": {
          "value": 2000,
          "unit": "km"
        }
      }
    ],
    "tree_biomass": [
      {
        "tree_type": 5,
        "density_last_year": {
          "value": 100,
          "unit": "trees / hectare"
        },
        "size_last_year": {
          "value": 10,
          "unit": "cm"
        },
        "size_this_year": {
          "value": 15,
          "unit": "cm"
        },
        "num_trees_delta": {
          "value": 1,
          "unit": "trees / hectare"
        }
      }
    ],
    "co_products": [
      {
        "name": "test_co_product",
        "percentage_main_value": 50
      }
    ],
    "processing": [
      {
        "_type": 1,
        "allocation": 100,
        "power_source": 102
      }
    ],
    "storage": [
      {
        "cipc_application": 1,
        "cipc_dose": 1,
        "storage_power_source": 106,
        "store_loading_power_source": 102,
        "unloading_power_source": 102,
        "stored_allocation": 100,
        "temperature": {
          "unit": "°C",
          "value": 5
        },
        "time": {
          "unit": 46,
          "value": 1
        }
      }
    ],
    "waste_water": {
      "waste_water_production": {
        "unit": 15,
        "value": 12
      },
      "oxygen_demand": {
        "unit": 18,
        "value": 15
      },
      "oxygen_demand_type": 1,
      "water_treatment_type": 1
    }
  },
  {
    "information": {
      "cft_version": "API_DEMO_TOOL"
    }
  }
]

Example response

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "farm": {
            "farm_identifier": ""
        },
        "summary": {
            "emissions_total": [
                "-327601.26",
                "kg CO2e"
            ],
            "emissions_per_area": [
                "-3276.01",
                "kg CO2e / ha"
            ],
            "emissions_per_product": [
                "-330.91",
                "kg CO2e / tonne"
            ],
            "soil_organic_carbon": "2.00%",
            "regionalised_calculations": false,
            "disaggregation_totals": [
                {
                    "CO2": {
                        "metric_tonnes_CO2": [
                            "-332.65",
                            "tonnes CO2"
                        ],
                        "metric_tonnes_CO2e": [
                            "-332.65",
                            "tonnes CO2e"
                        ]
                    },
                    "N2O": {
                        "metric_tonnes_N2O": [
                            "0.01",
                            "tonnes N2O"
                        ],
                        "metric_tonnes_CO2e": [
                            "2.74",
                            "tonnes CO2e"
                        ]
                    },
                    "CH4": {
                        "metric_tonnes_CH4": [
                            "0.01",
                            "tonnes CH4"
                        ],
                        "metric_tonnes_CO2e": [
                            "0.22",
                            "tonnes CO2e"
                        ]
                    }
                }
            ],
            "machinery_fuel_usage": "200.00 litre"
        },
        "total_emissions": [
            {
                "name": "co_product",
                "CO2": "-163800.63",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "-163800.63",
                "total_CO2e_per_area": "-1638.01",
                "total_CO2e_per_product": "-165.46"
            },
            {
                "name": "fertiliser_production",
                "CO2": "67.35",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "67.35",
                "total_CO2e_per_area": "0.67",
                "total_CO2e_per_product": "0.07",
                "details": [
                    {
                        "fertiliser_name": "Compose your own NPK",
                        "CO2e_emission": "67.347"
                    }
                ]
            },
            {
                "name": "fertiliser_soil",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00"
            },
            {
                "name": "field_energy",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "irrigation",
                "CO2": "2084.13",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "2084.13",
                "total_CO2e_per_area": "20.84",
                "total_CO2e_per_product": "2.11"
            },
            {
                "name": "machinery",
                "CO2": "416.29",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "416.29",
                "total_CO2e_per_area": "4.16",
                "total_CO2e_per_product": "0.42",
                "details": [
                    {
                        "machine_name": "Spraying / Spreading - herbicide spraying",
                        "CO2e_emission": "416.292"
                    }
                ]
            },
            {
                "name": "management_changes",
                "CO2": "-336798.65",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "-336798.65",
                "total_CO2e_per_area": "-3367.99",
                "total_CO2e_per_product": "-340.20"
            },
            {
                "name": "pesticide",
                "CO2": "1139.34",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "1139.34",
                "total_CO2e_per_area": "11.39",
                "total_CO2e_per_product": "1.15",
                "details": [
                    {
                        "crop_protection_name": "Post-emergence - pesticide",
                        "CO2e_emission": "1139.338"
                    }
                ]
            },
            {
                "name": "processing_energy",
                "CO2": "6.67",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "6.67",
                "total_CO2e_per_area": "0.07",
                "total_CO2e_per_product": "0.01",
                "details": [
                    {
                        "processing_name": "Washing - diesel (average biofuel blend)",
                        "CO2e_emission": "6.672"
                    }
                ]
            },
            {
                "name": "residue",
                "CO2": "0.00",
                "N2O": "10.05",
                "CH4": "0.00",
                "total_CO2e": "2743.31",
                "total_CO2e_per_area": "27.43",
                "total_CO2e_per_product": "2.77"
            },
            {
                "name": "seed",
                "CO2": "-3243.58",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "-3243.58",
                "total_CO2e_per_area": "-32.44",
                "total_CO2e_per_product": "-3.28"
            },
            {
                "name": "storage",
                "CO2": "2548.98",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "2548.98",
                "total_CO2e_per_area": "25.49",
                "total_CO2e_per_product": "2.57"
            },
            {
                "name": "transportation",
                "CO2": "3213.92",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "3213.92",
                "total_CO2e_per_area": "32.14",
                "total_CO2e_per_product": "3.25",
                "details": [
                    {
                        "transportation_name": "road LGV diesel (light goods vehicle <3.5t)",
                        "CO2e_emission": "3213.920"
                    }
                ]
            },
            {
                "name": "waste_water",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "7.92",
                "total_CO2e": "220.97",
                "total_CO2e_per_area": "2.21",
                "total_CO2e_per_product": "0.22"
            }
        ]
    },
    {
        "information": {
            "cft_version": "2.5.0"
        }
    }
]
Request Headers
Status Codes

Crop type Rice

POST /crop_product/calculate/

Calculate emissions for a rice crop product, without saving it to the database

Example request

Note

When calculating a rice crop product please note two additional fields: Flooding is a required parameter but optional to provide (if not provided a default value will be used) The time under cultivation may be entered directly in number of days. If it is not provided the IPCC 2019 default number of days based on farm location and region will be applied. Green manure is an optional parameter and may be provided as shown below

"flooding": {
     "time_under_cultivation": {
         "value": 123,
         "unit": "d"
     },
 "before_cultivation": "Not flooded pre-season (for < 180 days)",
 "during_cultivation": "Continuously flooded"
 },
 "green_manure": {
     "amount": {
         "value": 6.6,
         "unit": "tonne / ha"
     }
 }
POST /crop_product/calculate/ HTTP/1.1
Host: app.coolfarmtool.org
Accept: application/json
Content-Type: application/json
[
  {
    "farm": {
      "country": "United Kingdom",
      "territory": null,
      "climate": "Warm Temperate Dry",
      "average_temperature": {
        "value": 16,
        "unit": "\u00b0C"
      },
      "farm_identifier": "",
      "soil_characteristics": "Sandy Soils",
      "latitude": 52.164,
      "longitude": 1.435
    },
    "crop": {
      "type": "Rice",
      "harvesting_year": 2022,
      "feed_type": null,
      "field_size": {
        "value": 10,
        "unit": 10
      },
      "soil": {
        "texture_id": 2,
        "organic_matter_id": 2,
        "drainage_id": 1,
        "ph_id": 1,
        "organic_matter_custom": null,
        "custom_measured_years_ago": 0
      },
      "product_fresh": {
        "value": 10000,
        "unit": "kg"
      },
      "product_finished": {
        "value": 10000,
        "unit": "kg"
      },
      "residue": {
        "value": 4.55,
        "unit": "tonne / ha",
        "management": "Rice straw incorporation less than 30 days before cultivation"
      },
      "seed_amount": {
        "value": 0,
        "unit": ""
      },
      "irrigation_calculation_type": 1
    },
    "pesticides": [],
    "fertilisers": [],
    "machinery": [],
    "irrigation": [],
    "direct_energy": [],
    "land_management": {
      "carbon_changes": [
        {
          "year_of_change": 2022,
          "allocation": 100,
          "land_use": {
            "from": "cultivated",
            "to": "set-aside"
          },
          "tillage": {
            "from": "full",
            "to": "full"
          },
          "inputs": {
            "from": "low-c-input",
            "to": "low-c-input"
          }
        },
        {
          "year_of_change": 2020,
          "allocation": 44,
          "land_use": {
            "from": "native-forest",
            "to": "cultivated"
          },
          "tillage": {
            "from": "full",
            "to": "full"
          },
          "inputs": {
            "from": "low-c-input",
            "to": "low-c-input"
          }
        },
        {
          "year_of_change": 2019,
          "allocation": 100,
          "land_use": {
            "from": "native-forest",
            "to": "native-forest"
          },
          "tillage": {
            "from": "full",
            "to": "full"
          },
          "inputs": {
            "from": "low-c-input",
            "to": "low-c-input"
          }
        },
        {
          "year_of_change": 2017,
          "allocation": 29,
          "land_use": {
            "from": "native-forest",
            "to": "native-forest"
          },
          "tillage": {
            "from": "full",
            "to": "full"
          },
          "inputs": {
            "from": "low-c-input",
            "to": "low-c-input"
          }
        }
      ],
      "forest_biomass": {
        "age_years": 5,
        "type": "boreal mountain system"
      }
    },
    "transport": [],
    "tree_biomass": [],
    "co_products": [],
    "processing": [],
    "storage": [],
    "flooding": {
      "time_under_cultivation": {
        "value": 123,
        "unit": "day"
      },
      "before_cultivation": "Not flooded pre-season (for < 180 days)",
      "during_cultivation": "Continuously flooded"
    },
    "green_manure": {
      "amount": {
        "value": 6.6,
        "unit": "tonne / ha"
      }
    }
  }
]

Example response

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "farm": {
            "farm_identifier": ""
        },
        "summary": {
            "emissions_total": [
                "190329.13",
                "kg CO2e"
            ],
            "emissions_per_area": [
                "19032.91",
                "kg CO2e / ha"
            ],
            "emissions_per_product": [
                "19.03",
                "kg CO2e / kg"
            ],
            "soil_organic_carbon": "2.00%",
            "disaggregation_totals": [
                {
                    "CO2": {
                        "metric_tons_CO2": [
                            "0.31",
                            "tons CO2"
                        ],
                        "metric_tons_CO2e": [
                            "0.31",
                            "tons CO2e"
                        ]
                    },
                    "CH4": {
                        "metric_tons_CH4": [
                            "6.79",
                            "tons CH4"
                        ],
                        "metric_tons_CO2e": [
                            "189.49",
                            "tons CO2e"
                        ]
                    },
                    "N2O": {
                        "metric_tons_N2O": [
                            "0.00",
                            "tons N2O"
                        ],
                        "metric_tons_CO2e": [
                            "0.53",
                            "tons CO2e"
                        ]
                    }
                }
            ],
            "machinery_fuel_usage": "0.00 litre"
        },
        "total_emissions": [
            {
                "name": "fertiliser_production",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "fertiliser_soil",
                "CO2": "0.00",
                "N2O": "0.13",
                "CH4": "0.00",
                "total_CO2e": "36.34",
                "total_CO2e_per_area": "3.63",
                "total_CO2e_per_product": "0.00"
            },
            {
                "name": "field_energy",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "irrigation",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00"
            },
            {
                "name": "machinery",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "management_changes",
                "CO2": "305.50",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "305.50",
                "total_CO2e_per_area": "30.55",
                "total_CO2e_per_product": "0.03"
            },
            {
                "name": "paddy_methane",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "6791.87",
                "total_CO2e": "189493.07",
                "total_CO2e_per_area": "18949.31",
                "total_CO2e_per_product": "18.95"
            },
            {
                "name": "pesticide",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "processing_energy",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "residue",
                "CO2": "0.00",
                "N2O": "1.81",
                "CH4": "0.00",
                "total_CO2e": "494.23",
                "total_CO2e_per_area": "49.42",
                "total_CO2e_per_product": "0.05"
            },
            {
                "name": "seed",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00"
            },
            {
                "name": "storage",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00"
            },
            {
                "name": "transportation",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00",
                "details": []
            },
            {
                "name": "waste_water",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00"
            },
            {
                "name": "waste_water",
                "CO2": "0.00",
                "N2O": "0.00",
                "CH4": "0.00",
                "total_CO2e": "0.00",
                "total_CO2e_per_area": "0.00",
                "total_CO2e_per_product": "0.00"
            }
        ]
    },
    {
        "information": {
            "cft_version": "2.1.0"
        }
    }
]
Request Headers
Status Codes

Local region calculations

POST /crop_product/calculate/

The crop calculate API endpoint provides the flexibility to perform calculations using factors and methods specific to a local region. This allows for more accurate and tailored results based on regional characteristics.

Note

This functionality is restricted to farms located in specific regions. Currently, it is only available for farms located in Australia.

To enable local region calculations, include the following optional keys in the API request:

{
   "farm": {
     ...
     "local_calculations": true,
     "local_climate": "Dry"
   }
   ...
},
  • local_calculations (Boolean): Set this key to true to enable local region calculations (Default: false).

  • local_climate (String): Specify the local climate of the farm using this key. Choose from the available options based on your region. For example, you can set it to Dry or Wet. Please ensure that you provide the accurate local climate information to obtain precise calculations based on the specific region.

Dairy assessment

POST /dairy_product/calculate/

Calculate emissions for a dairy product, without saving it to the database

Example request

POST /dairy_product/calculate/ HTTP/1.1
Host: app.coolfarmtool.org
Accept: application/json
Content-Type: application/json
[
  {
    "farm": {
      "country": 840,
      "territory": "Wisconsin",
      "climate": "Warm Temperate Dry",
      "average_temperature": {
        "value": 15,
        "unit": "°C"
      },
      "soil_characteristics": "Sandy Soils",
      "farm_identifier": "",
      "latitude": 43.784,
      "longitude": -88.788
    },
    "general": {
      "grazing_area": {
        "value": 50,
        "unit": "ha"
      },
      "feed_approach": "dmi",
      "fertilisation_approach": 1
    },
    "milk_production": {
      "variety": "Normande",
      "reporting_year": 2019,
      "date_time": "start",
      "date_month": 1,
      "name": "normande_2019",
      "product_dry": {
        "value": 500000,
        "unit": "litre"
      },
      "fat_content": 4.2,
      "protein_content": 3.5,
      "protein_measure": 1
    },
    "herd_sections": [
      {
        "phase": "Dairy calves",
        "animals": 40,
        "live_weight": {
          "value": 166,
          "unit": "kg"
        },
        "sold_animals": 15,
        "sold_weight": {
          "value": 166,
          "unit": "kg"
        },
        "purchased_animals": 10,
        "purchased_weight": {
          "value": 166,
          "unit": "kg"
        }
      },
      {
        "phase": "Meat calves",
        "animals": 30,
        "live_weight": {
          "value": 230,
          "unit": "kg"
        },
        "sold_animals": 10,
        "sold_weight": {
          "value": 230,
          "unit": "kg"
        },
        "purchased_animals": 5,
        "purchased_weight": {
          "value": 230,
          "unit": "kg"
        }
      },
      {
        "phase": "Milk cows",
        "animals": 100,
        "live_weight": {
          "value": 555,
          "unit": "kg"
        },
        "sold_animals": 5,
        "sold_weight": {
          "value": 555,
          "unit": "kg"
        },
        "purchased_animals": 0,
        "purchased_weight": {
          "value": 555,
          "unit": "kg"
        }
      }
    ],
    "grazing": [
      {
        "herd_section": "Dairy calves",
        "days": 100,
        "hours": 12,
        "category": 2,
        "quality": 1
      },
      {
        "herd_section": "Meat calves",
        "days": 100,
        "hours": 12,
        "category": 3,
        "quality": 2
      },
      {
        "herd_section": "Milk cows",
        "days": 150,
        "hours": 12,
        "category": 2,
        "quality": 1
      }
    ],
    "fertilisers": [
      {
        "type": "Ammonium nitrate - 33.5% N (prilled)",
        "production": "Europe 2014",
        "custom_ingredients": {},
        "application_rate": {
          "value": 30,
          "unit": "kg / ha"
        },
        "application_date": "unknown",
        "rate_measure": "",
        "inhibition": 1
      },
      {
        "type": "Compose your own NPK",
        "production": "Europe 2014",
        "custom_ingredients": {
          "n_ammonia_percentage": 6,
          "n_total_percentage": 12,
          "n_nitric_percentage": 4,
          "n_urea_percentage": 2,
          "p2o5_percentage": 8,
          "p2o5_percentage_type_id": 4,
          "k2o_percentage": 4,
          "k2o_percentage_type_id": 5
        },
        "application_rate": {
          "value": 20,
          "unit": "kg / ha"
        },
        "application_date": "unknown",
        "rate_measure": "",
        "inhibition": 1
      }
    ],
    "feed_components": [
      {
        "herd_section": "Dairy calves",
        "item": "Grass fresh managed - on farm",
        "region": "Global (world)",
        "dry_matter": {
          "value": 0.41,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Dairy calves",
        "item": "Maize / corn grain",
        "region": "Global (world)",
        "dry_matter": {
          "value": 10,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Dairy calves",
        "item": "Oats",
        "region": "Global (world)",
        "dry_matter": {
          "value": 4,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Dairy calves",
        "item": "Compound dairy feed: Belgium (65% soy)",
        "region": "Global (world)",
        "dry_matter": {
          "value": 5,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Meat calves",
        "item": "Grass fresh managed - on farm",
        "region": "Global (world)",
        "dry_matter": {
          "value": 0.62,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Meat calves",
        "item": "Maize / corn grain",
        "region": "Global (world)",
        "dry_matter": {
          "value": 5,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Meat calves",
        "item": "Soybean cake/meal",
        "region": "Global (world)",
        "dry_matter": {
          "value": 5,
          "unit": "kg"
        },
        "certified": false
      },
      {
        "herd_section": "Milk cows",
        "item": "Straw",
        "region": "Global (world)",
        "dry_matter": {
          "value": 10,
          "unit": "kg"
        },
        "certified": false
      }
    ],
    "feed_additives": [
      {
       "herd_section": "Dairy calves",
       "type": "3NOP",
       "dose": 100,
       "dose_unit": "mg / kg",
       "ndf": 40,
       "crude_fat": 5,
       "days": 10,
       "herd_section_percentage": 100
     },
     {
       "herd_section": "Milk cows",
       "type": "Nitrate",
       "dose": 30,
       "dose_unit": "g / kg",
       "days": 10,
       "herd_section_percentage": 100
     }
    ],
    "manure": [
      {
        "herd_section": "Dairy calves",
        "type": "Solid storage",
        "allocation": 100
      },
      {
        "herd_section": "Milk cows",
        "type": "Aerobic treatment - natural aeration",
        "allocation": 100
      }
    ],
    "bedding": [
      {
        "type": 621,
        "quantity": {
          "value": 100,
          "unit": "kg"
        }
      }
    ],
    "direct_energy": [
      {
        "source": "diesel (average biofuel blend)",
        "usage": {
          "value": 1200,
          "unit": "litre"
        },
        "category": 1
      },
      {
        "source": "electricity (grid)",
        "usage": {
          "value": 1000,
          "unit": "kWh"
        },
        "category": 1
      }
    ],
    "transport": [
      {
        "mode": "road LGV diesel (light goods vehicle <3.5t)",
        "weight": {
          "value": 5,
          "unit": "tonne"
        },
        "distance": {
          "value": 3500,
          "unit": "km"
        }
      }
    ]
  },
  {
    "information": {
      "cft_version": "API_DEMO_TOOL"
    }
  }
]

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "total_emissions": [
    {
      "CH4": "0.00",
      "CO2": "1344.73",
      "N2O": "0.00",
      "name": "energy",
      "total_CO2e": "1344.73"
    },
    {
      "CH4": "2267.14",
      "CO2": "0.00",
      "N2O": "0.00",
      "name": "enteric",
      "total_CO2e": "56678.61"
    },
    {
      "CH4": "0.00",
      "CO2": "26461.58",
      "N2O": "0.00",
      "name": "feed",
      "total_CO2e": "26461.58"
    },
    {
      "CH4": "0.00",
      "CO2": "6939.96",
      "N2O": "0.00",
      "name": "grazing",
      "total_CO2e": "6939.96"
    },
    {
      "CH4": "0.00",
      "CO2": "10480.26",
      "N2O": "0.00",
      "name": "manure",
      "total_CO2e": "10480.26"
    },
    {
      "CH4": "0.00",
      "CO2": "2716.00",
      "N2O": "0.00",
      "name": "transport",
      "total_CO2e": "2716.00"
    }
  ],
  "summary": {
    "emissions_total": [
      "100560.4049907536020612299397",
      "kg CO2e"
    ]
  }
}
Request Headers
Status Codes

Feed

The Cool farm tool allows 2 types of format for the feed section.

Feed approach 1: Dry Matter Intake (if you know the DMI values)

{
  "general": {
     "grazing_area": {
         "value": 60,
         "unit": "ha"
     },
     "feed_approach": "dmi"
  },
  "feed_components": [
    {
      "herd_section": "Dairy calves",
      "item": "Oats",
      "region": "Global (world)",
      "dry_matter": {
        "value": 10,
        "unit": "kg"
      },
      "certified": false
    },
    {
      "herd_section": "Meat calves",
      "item": "Grass fresh managed - on farm",
      "region": "Global (world)",
      "dry_matter": {
        "value": 1.37,
        "unit": "kg"
      },
      "certified": false
    },
    {
      "herd_section": "Meat calves",
      "item": "Maize / corn grain",
      "region": "Global (world)",
      "dry_matter": {
        "value": 5,
        "unit": "kg"
      },
      "certified": false
    },
    {
      "herd_section": "Milk cows",
      "item": "Sorghum",
      "region": "Global (world)",
      "dry_matter": {
        "value": 15,
        "unit": "kg"
      },
      "certified": false
    }
  ]
}

Feed approach 2: Average feed (the tool will estimate the DMI)

{
  "general": {
     "grazing_area": {
         "value": 60,
         "unit": "ha"
     },
     "feed_approach": "average"
  },
  "feed_components": [
    {
      "item": "Oat hay",
      "region": "Global (world)",
      "percentage": 60
    },
    {
      "item": "Straw",
      "region": "Global (world)",
      "percentage": 40
    }
  ]
}

Calculate a crop assessment first

You can also use the crop API to first calculate a crop assessment that then can be used as a feed item within the Dairy API for both feed approach 1 and 2. See calculate a crop assessment.

You will need to choose an existing feed item to use as the base for manure and enteric fermentation properties.

List of the available feed types

Example for feed approach 1

{
  "feed_components": [
    {
      "herd_section": "Meat calves",
      "crop_product": {
        "type": "Soyabean",
        "product_dry": {
          "value": 5,
          "unit": "tonne"
        },
        "feed_type": "Soybean",
        "emissions_total": {
          "value": 22469.393582158074,
          "unit": "kg CO2e"
        }
      },
       "dry_matter": {
         "value": 5,
         "unit": "kg"
      },
      "certified": false
    }
  ]
}

Example for feed approach 2

{
  "feed_components": [
    {
      "item": "Oat hay",
      "region": "Global (world)",
      "percentage": 60
    },
    {
      "crop_product": {
        "type": "Maize",
        "product_dry": {
          "value": 2,
          "unit": "tonne"
        },
        "feed_type": "Maize silage",
        "emissions_total": {
          "value": 267.5460271629662,
          "unit": "kg CO2e"
        }
      },
      "region": "Global (world)",
      "percentage": 40
    }
  ]
}

Water assessment

POST /crop_product/water/calculate/

Calculate water assessment for a crop, without saving it to the database

Example request

POST /crop_product/water/calculate/ HTTP/1.1
Host: app.coolfarmtool.org
Accept: application/json
Content-Type: application/json
[
    {
        "farm": {
            "country": "Spain",
            "territory": "Madrid",
            "climate": "Warm Temperate Dry",
            "average_temperature": {
                "value": 15,
                "unit": "°C"
            },
            "farm_identifier": "my_identifier",
            "soil_characteristics": "Sandy Soils",
            "latitude": 40.417,
            "longitude": -3.704
        },
        "crop": {
            "type": "Potato",
            "field_size": {
                "value": 51,
                "unit": "ha"
            },
            "product_fresh": {
                "value": 3000,
                "unit": "tonne"
            },
            "product_dry": {
                "value": 3000,
                "unit": "tonne"
            },
            "reporting_year": 2016,
            "planting_date": {
                "time": 1,
                "month": 1,
                "year": 2016
            },
            "harvest_date": {
                "time": 1,
                "month": 3
            },
            "name": "potato_2016",
            "soil": {
                "label": "sandy wet",
                "type": "sandy_clay",
                "moisture_at_sowing": "wet"
            }
        },
        "irrigation": {
            "irri_start_date": {
                "time": 1,
                "month": 1,
                "year": 2016
            },
            "irri_end_date": {
                "time": 1,
                "month": 2,
                "year": 2016
            },
            "method": 2,
            "water_source": 1,
            "irrigation_events": [
                {
                    "water_added": {
                        "value": 20.78,
                        "unit": "mm"
                    },
                    "allocation": 100,
                    "has_source_pump": false,
                    "water_source": 3
                },
                {
                    "water_added": {
                        "value": 27.3,
                        "unit": "mm"
                    },
                    "allocation": 100
                },
                {
                    "water_added": {
                        "value": 23.55,
                        "unit": "mm"
                    },
                    "allocation": 100
                },
                {
                    "water_added": {
                        "value": 25,
                        "unit": "mm"
                    },
                    "allocation": 100
                },
                {
                    "water_added": {
                        "value": 21,
                        "unit": "mm"
                    },
                    "allocation": 100
                }
            ]
        }
    },
  {
    "information": {
      "cft_version": "API_DEMO_TOOL"
    }
  }
]

Example response

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "farm": {
            "farm_identifier": "my_identifier"
        },
        "summary": {
            "water_productivity": {
                "value": 93.3,
                "unit": "kg / m3"
            },
            "water_footprint": {
                "value": 10.72,
                "unit": "litre / kg",
                "green": 7.22,
                "blue": 3.5
            },
            "irrigation_efficiency": {
                "value": 1.87,
                "unit": "litre / litre"
            },
            "water_balance": {
                "unit": "mm",
                "water_requirement": {
                    "total_value": 63.05,
                    "weekly": [
                        3.75,
                        5.31,
                        6.35,
                        6.58,
                        7.85,
                        5.15,
                        11.82,
                        9.04,
                        7.2
                    ]
                },
                "water_added": {
                    "rainfall": {
                        "total_value": 93.35,
                        "weekly": [
                            21.69,
                            4.94,
                            0.0,
                            1.55,
                            4.55,
                            28.47,
                            4.85,
                            25.76,
                            1.54
                        ]
                    },
                    "irrigation": {
                        "total_value": 117.63,
                        "weekly": [
                            20.78,
                            27.3,
                            23.55,
                            25.0,
                            21.0
                        ]
                    }
                },
                "irrigation_percolation": -70.85,
                "irrigation_runoff": -26.19,
                "rainfall_runoff": -18.44,
                "rainfall_percolation": -40.07,
                "irrigation_balance": 20.5,
                "interception_losses": -12.88
            }
        }
    },
  {
    "information": {
      "cft_version": "API_DEMO_TOOL"
    }
  }
]
Request Headers
Status Codes

Calculating the number of weeks between irrigation dates

To enter the correct number of irrigation events follow the formula below to calculate the correct number of weeks/irrigation events between the irrigation start date and irrigation end date.

Number of days between irrigation start date and irrigation end date (knowing that “start” = 5th, “middle” = 15th and “end” = 25th day of the month and last day not included) divided by 7 and rounded to the highest integer number. See the example below:

  • irrigation start date: start April 2016 -> 2016-04-05

  • irrigation end date: middle May 2016 -> 2016-05-15

  • days between: 40

  • 40 / 7 = 5.71428 -> So rounded to highest integer is 6 weeks

Water source

To select an irrigation water source enter the “water_source” key under the irrigation key. This value will be used as the default for all irrigation events.

In order to enter a different water source for a specific irrigation event just add two fields to override the default value as per the example below:

{
     "water_added": {
        "value": 12000,
        "unit": "litre"
    },
    "allocation": 100,
    "has_source_pump": false,
    "water_source": 3
}

JSON export

From the web interface on a crop or dairy assessment, you can generate a JSON file compatible with the API. This can be used to test and debug the API. To find the JSON export functionality, go to the ‘more’ page of an assessment.