Quick Start Guide

Warning

Before doing anything, you’ll need an app key (and possibly an API key); see Authentication for information on how to obtain it.

HTML Demo Tool

The CFT includes an HTML API demo tool:

HTML API demo tool

You can start making calls immediately; paste your “app” key into the input field and click the “Get API Values” button. The output should be the JSON shown in the relevant section of the API documentation.

You may also get a list of the measurement unit names, values and conversion rates, by clicking the “Get API Values” button with appropriate options selected under API Endpoint. This can be used to get a list of values for units of measurement and fertiliser types (and their composition).

You will need to ensure that you have a valid “App key” to proceed with any form of API call. Calls which access user data will also require a valid “API key”, available from the “Help” page.

Interface breakdown

  • App Key: requested directly from CFA; required for all API calls.

  • API Key: found on the “Help” page; look for the “?” at the top-right of the page.

  • Get API Values: call the adjacent API URL (with the entered data, for calls which accept data).

  • Select Farm Drop-down: specify which farm to show inputs from the “Farm settings” page, which returns a single farm plus a summary list of all of the assessments associated to that farm.

  • Select Assessment Drop-down: specify which assessment to show results for, for calls which act on a single assessment.

  • Select Share Code Drop-down: specify which share code to show results for, for calls which act on a single share code.

  • Select Share Code Assessment Drop-down: specify which share code to show results for, for calls which act on a list of assessment calculation outputs.

  • API Endpoint Drop-down: which API method to call.

  • Textarea 1: This is used to enter data to send to the server during a calculation API call.

  • Textarea 2: This will show the response from the server.

Note

We have recently removed some fields which are considered redundant in version 1.3.0 of the tool. These are as follows:

  • Destination Drop-down

  • Port Text Input

  • API Version Input

We have recently added a new field which are required for Multiple Farms API as of 1.3.0 This is:

  • Select Farm Drop-down

We have also introduced new UI behaviour on this page, only releveant inputs will be shown to the user after selecting an endpoint which requires extra parameters, for example, when the GET / Farms is selected, the “Select farm” input will be revealed to the user. This also applies to other endpoints.

Python

The following Python scripts provide examples to run calculations for crop products and dairy products using the CFT API.

Set-up

  • Ensure that the Requests library is installed

    (pip install requests).

  • Open a python shell or file.

  • Take one of the scripts below and change the API_KEY.

  • Run the script.

Crop assessment

Example

import requests
import json


# insert your API key and include in headers
API_KEY = "<insert-app-api-key-here>"
HEADERS = {
    "Content-Type": "application/json",
    "X-Api-App-Authorization": API_KEY
}

# calculate crop product
crop_input = json.loads('''
[
  {
    "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,
          "n_ammonia_percentage": 0,
          "n_nitric_percentage": 0,
          "n_urea_percentage": 0,
          "p2o5_percentage": 0,
          "p2o5_percentage_type_id": 4,
          "k2o_percentage": 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"
    }
  }
]
''')

crop_output = requests.post("https://app.coolfarmtool.org/api/v1/crop_product/calculate/", json=crop_input, headers=HEADERS)
print(crop_output.json())

Example response

[
    {
        "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%",
            "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.35"
                    }
                ]
            },
            {
                "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.29"
                    }
                ]
            },
            {
                "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.34"
                    }
                ]
            },
            {
                "name": "processing",
                "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"
            },
            {
                "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.92"
                    }
                ]
            },
            {
                "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.1.0"
        }
    }
]

Dairy assessment

Example

import requests
import json


# insert your API key and include in headers
API_KEY = "<insert-app-api-key-here>"
HEADERS = {
    "Content-Type": "application/json",
    "X-Api-App-Authorization": API_KEY
}

# calculate crop product
dairy_input = json.loads('''
[
    {
      "farm": {
        "country": 840,
        "territory": "Wisconsin",
        "climate": "Warm Temperate Dry",
        "average_temperature": {
          "value": 15,
          "unit": "°C"
        },
        "farm_identifier": ""    
      },
      "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"
          },
          "rate_measure": ""
        },
        {
          "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"
          },
          "rate_measure": ""
        }
      ],
      "feed_components": [
        {
          "herd_section": "Dairy calves",
          "item": "Grass fresh managed - on farm",
          "dry_matter": {
            "value": 0.41,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Dairy calves",
          "item": "Maize / corn grain",
          "dry_matter": {
            "value": 10,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Dairy calves",
          "item": "Oats",
          "dry_matter": {
            "value": 4,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Dairy 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": 10,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Dairy calves",
          "item": "Compound dairy feed: Belgium (65% soy)",
          "dry_matter": {
            "value": 5,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Meat calves",
          "item": "Grass fresh managed - on farm",
          "dry_matter": {
            "value": 0.62,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Meat calves",
          "item": "Maize / corn grain",
          "dry_matter": {
            "value": 5,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "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": 8,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Meat calves",
          "item": "Soybean cake/meal",
          "dry_matter": {
            "value": 5,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Milk cows",
          "item": "Straw",
          "dry_matter": {
            "value": 10,
            "unit": "kg"
          },
          "certified": false
        },
        {
          "herd_section": "Milk cows",
          "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
        }
      ],
      "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"
          }
        }
      ]
    }
]
''')

dairy_output = requests.post("https://app.coolfarmtool.org/api/v1/dairy_product/calculate/", json=dairy_input, headers=HEADERS)
print(dairy_output.json())

Example response

[
    {
        "farm": {
            "farm_identifier": null
        },
       "summary":{
          "emissions_total":[
             "3145916.863820172720121063651",
             "kg CO2e"
          ],
          "emissions_per_fpcm":[
             "5.874083039659086256761429343",
             "kg CO2e"
          ]
       },
       "total_emissions":[
          {
             "name":"energy",
             "CO2":"3759.88",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"3759.88"
          },
          {
             "name":"enteric",
             "CO2":"0.00",
             "N2O":"0.00",
             "CH4":"23552.49",
             "total_CO2e":"588812.18"
          },
          {
             "name":"feed",
             "CO2":"2350603.47",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"2350603.47"
          },
          {
             "name":"fertiliser",
             "CO2":"1945.03",
             "N2O":"11.86",
             "CH4":"0.00",
             "total_CO2e":"5477.97"
          },
          {
             "name":"grazing",
             "CO2":"0.00",
             "N2O":"237.67",
             "CH4":"0.00",
             "total_CO2e":"70826.09"
          },
          {
             "name":"manure",
             "CO2":"0.00",
             "N2O":"356.45",
             "CH4":"590.91",
             "total_CO2e":"121002.92"
          },
          {
             "name":"transport",
             "CO2":"5434.36",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"5434.36"
          }
       ]
    }
]