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.

If you have an app key for any other servers, you may select the appropriate one using the drop-down menus. Currently Live, Staging, Staging2 and a local development server are supported.

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 entered a valid “Destination” and “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 Assessment Drop-down: specify which assessment to show results for, for calls which act on a single assessment.

  • Destination Drop-down: which server you wish to connect to; app.coolfarmtool.org is the main server.

  • Port Text Input: TCP port to connect on – this can be left blank unless you are running your own instance of the CFT.

  • 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.

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": "temperate",
        "average_temperature": {
          "value": 15,
          "unit": "°C"
        },
        "farm_identifier": ""
      },
      "crop": {
        "type": "Potato",
        "field_size": {
          "value": 100,
          "unit": "ha"
        },
        "soil": {
          "texture_id": 1,
          "organic_matter_id": 2,
          "moisture_id": 1,
          "drainage_id": 1,
          "ph_id": 4,
          "organic_matter_custom": null
        },
        "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"
        }
      },
      "pesticides": [
        {
          "applications": 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"
          },
          "rate_measure": "product",
          "method": 2,
          "inhibition_id": 1,
          "added_within_20_years": false,
          "years_ago": null,
          "allocation": null
        }
      ],
      "machinery": [
        {
          "operations": 1,
          "machinery": 24,
          "fuel_type": "diesel"
        }
      ],
      "irrigation": [
        {
          "method": 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",
          "usage": {
            "value": 1000,
            "unit": "litre"
          }
        }
      ],
      "land_management": [
        {
          "change_id": 10,
          "years_ago": 1,
          "allocation": 100,
          "forest": {
            "type": "temperate oceanic forest",
            "age_years": 1
          }
        }
      ],
      "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
          }
        }
      ]
    }
]
''')

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": null
        },
       "summary":{
          "emissions_total":[
             "-390882.95",
             "kg CO2e"
          ],
          "emissions_per_area":[
             "-3895.93",
             "kg CO2e / ha"
          ],
          "emissions_per_product":[
             "-389.59",
             "kg CO2e / tonne"
          ],
          "soil_organic_carbon":"2.00%",
          "machinery_fuel_usage":"140.00 litre"
       },
       "total_emissions":[
          {
             "name":"co_product",
             "CO2":"-195441.48",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"-195441.48",
             "total_CO2e_per_area":"-1954.41",
             "total_CO2e_per_product":"-195.44"
          },
          {
             "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"
          },
          {
             "name":"fertiliser_soil",
             "CO2":"0.00",
             "N2O":"37.39",
             "CH4":"0.00",
             "total_CO2e":"11143.12",
             "total_CO2e_per_area":"111.43",
             "total_CO2e_per_product":"11.14"
          },
          {
             "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"
          },
          {
             "name":"irrigation",
             "CO2":"1790.09",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"1790.09",
             "total_CO2e_per_area":"17.90",
             "total_CO2e_per_product":"1.79"
          },
          {
             "name":"machinery",
             "CO2":"250.13",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"250.13",
             "total_CO2e_per_area":"2.50",
             "total_CO2e_per_product":"0.25"
          },
          {
             "name":"management_changes",
             "CO2":"-415427.91",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"-415427.91",
             "total_CO2e_per_area":"-4154.28",
             "total_CO2e_per_product":"-415.43"
          },
          {
             "name":"pesticide",
             "CO2":"1366.67",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"1366.67",
             "total_CO2e_per_area":"13.67",
             "total_CO2e_per_product":"1.37"
          },
          {
             "name":"processing",
             "CO2":"5.77",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"5.77",
             "total_CO2e_per_area":"0.06",
             "total_CO2e_per_product":"0.01"
          },
          {
             "name":"residue",
             "CO2":"0.00",
             "N2O":"29.23",
             "CH4":"0.00",
             "total_CO2e":"8711.36",
             "total_CO2e_per_area":"87.11",
             "total_CO2e_per_product":"8.71"
          },
          {
             "name":"seed",
             "CO2":"-3870.13",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"-3870.13",
             "total_CO2e_per_area":"-38.70",
             "total_CO2e_per_product":"-3.87"
          },
          {
             "name":"storage",
             "CO2":"3269.93",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"3269.93",
             "total_CO2e_per_area":"32.70",
             "total_CO2e_per_product":"3.27"
          },
          {
             "name":"transportation",
             "CO2":"1810.67",
             "N2O":"0.00",
             "CH4":"0.00",
             "total_CO2e":"1810.67",
             "total_CO2e_per_area":"18.11",
             "total_CO2e_per_product":"1.81"
          }
       ]
    }
]

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": "temperate",
        "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",
          "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"
          }
       ]
    }
]