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.

Contents

Quick Start Guide
- HTML Demo Tool
  - Interface breakdown
- Python

HTML Demo Tool ¶

The CFT includes an 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": "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 ¶