.. include:: /banner.rst

=====================
What's new in CFT 2.0
=====================

Useful resources
----------------
* For a full description of the input format, take a look at the :doc:`data schemas page <../v1/data-schemas>`.
* For the list of reference data, take a look at the :doc:`reference data page <../../reference-data/index>`.

.. contents::


.. _Farm-Object:
Farm Object update
-------------------

The farm object is used across multiple endpoints, this has been updated to include the additional information below.

Farm Location
#############
The farm location is now required.

The ``latitude`` and ``longitude`` fields have been added to the farm object. These two fields are mandatory.

The coordinates need to be provided in the `decimal degree format <https://en.wikipedia.org/wiki/Decimal_degrees>`_ with 3 decimal places.

.. code-block::

   {
      farm": {
      ...
      "latitude": 51.414,
      "longitude": -1.196
   },

Soil Characteristics
#######################

The farm object has been updated to include a new key ``soil_characteristics``.
The full list of soil characteristic options can be found in the :doc:`reference data page <../../reference-data/tables/soil-characteristics>`.



.. note::
   The webapp CFT programmatically obtains the soil characteristics from Soil Grids based on farm location.
   If you wish to retrieve soil classifications automatically, contact CFT support for additional guidance.
   Please see the :doc:`Soil Grids documentation <soil_grids/soil_grids>` for guidance on how to implement this.

.. code-block::

   {
      farm": {
      ...
      "soil_characteristics": "High Activity Clay Soils"
   },

Climate Zones
#######################
Climate options have been updated in line with the IPCC Climate Zones.

``temperate`` and ``tropical`` are no longer valid climate types. These have been replaced with ``Tropical Montane``,
``Tropical Wet``, ``Tropical Moist``, ``Tropical Dry``, ``Warm Temperate Moist``, ``Warm Temperate Dry``,
``Cool Temperate Moist``, ``Cool Temperate Dry``, ``Boreal Moist`` and ``Boreal Dry``.

The full list of climate zones and their IDs can be found in the :ref:`climate zones <climate>`.

Crop API - calculate & create endpoints
-------------------

Farm
#######################
Please see :ref:`Farm Object update`  for more information on the updated farm object.

Crop
#######################

Changes to the crop factors have affected the valid options for the ``type`` field in the ``crop`` section.
Please see :ref:`Crop Type Factors` for further details.

Soil
#######################
The ``soil`` section has been updated. The optional key ``organic matter custom`` remains in the tool,
however when this own measurement is included an additional key ``custom measured years ago`` will also need to be used.
The ``custom measured years ago`` key requires a numerical figure to specify the number of years ago that the
organic matter was measured.

The ``moisture_id`` key is no longer required as soil moisture is derived from the climate zone.

.. note::
   The ``custom_measured_years_ago`` key is used with the ``organic_matter_custom`` value in order to derive a user defined SOC value,
   ``custom_measured_years_ago`` remains an optional field. The keys are optional but if one is included, they both need to be included.

.. code-block:: json

   {
      "crop": {
         ...,
         "soil": {
         ...,
         "organic_matter_custom": 1.5,
         "custom_measured_years_ago": 1
         },
      },
   }

Harvest Year
#######################
The ``harvesting_year`` field has been added to the ``crop`` section. This is a required field. The input must be an
integer between 1980 and the current year.

.. code-block:: json

    "crop": {
      "type": "Potato",
      "harvesting_year": 2022,
      "feed_type": null,
      "field_size": {
        "value": 100,
        "unit": "ha"
    }
Fertiliser application
#######################
The ``application_date`` field has been added for the date of fertiliser applications. This is a required field in the
schema, however, if the application date is unknown you may input the string "unknown". If the date is known, it should be inputted as
a string in "yyyy-mm-dd" format.

If there are multiple applications of a unique product in a single month you can aggregate to a single ``Fertiliser application``
and use the midpoint of the month as the date of application. A new ``Fertiliser application`` must be inputted for each month
that a product is applied.

.. note::
   The date inputted must be within the harvest year or the year prior.

.. code-block:: json

 "fertilisers": [
      {
        "type": "Ammonium nitrate - 33.5% N",
        "production": "World",
        "custom_ingredients": {
        },
        "application_rate": {
          "value": 15,
          "unit": "kg / ha"
        },
        "application_date": "2022-11-25",
        "rate_measure": "product",
        "method": 2,
        "inhibition_id": 1
      }
    ]

Organic fertiliser (20 years change)
******************
``added_within_20_years``, ``years_ago`` and ``allocation`` fields have been removed from the ``fertilisers`` section.

The impact of organic fertiliser on the land managment emissions should be provided by you in the ``land_management`` section.

Fertiliser type renamed
***********************
The fertiliser type ``Horse manure - 0.7 % N`` has been renamed to ``Horse manure - 0.5 % N``.
Please use the new name. The ID remain the same.

The full list of fertiliser types can be found in the :ref:`fertiliser types <fertiliser type>`.

Land Management
#######################
The old ``land_management`` object format shown below has been removed.

.. code-block:: json

   {
      "change_id": 10,
      "years_ago": 1,
      "allocation": 100,
      "forest": {
         "type": "temperate oceanic forest",
         "age_years": 1
        }
      }

The of the new ``land_management`` section, which now accepts up-to and no more than 4 changes, see example JSON below.

.. note::
   This sequence will be replicated for each prior change that is implemented. Up to 4 prior changes can be included.

.. code-block:: json

   {
      "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"
      }
    }

This is a completely new format for the JSON schema, with the following keys:

* ``year_of_change`` - the year of the change ( presented as a YYYY format)

* ``allocation`` - the % of field allocation in which the ‘to’ change has taken place

* ``land_use``

   * ``from`` - the land use change from

   * ``to`` - the land use change to

* ``tillage``

   * ``from`` - the tillage change from

   * ``to`` - the tillage change to

* ``inputs``

   * ``from`` - the inputs change from

   * ``to`` - the inputs change to


.. note::
   When recording a % land use change it will always be applied to the ‘to’ phase of the change. Thus, in the most recent change the % is that of the current land usage.

See :ref:`Land Management` for more information on the new ``land_use``, ``tillage`` and ``inputs``.

The existing ``forest_biomass`` section has been modified so it's now no longer apart of the ``carbon_changes`` key,
This is an optional key in the land_management section when a land use change from / to 'native forest' has been inputted

.. code-block:: json
   {
      "forest_biomass": {
         "age_years": 5,
         "type": "boreal mountain system"
      }
   }

See below a fully populated example of the new ``land_management`` section.

.. code-block:: json

   "land_management": {
      "carbon_changes": [
        {
          "year_of_change": 2021,
          "allocation": 100,
          "land_use": {
            "from": "native-forest",
            "to": "set-aside"
          },
          "tillage": {
            "from": "reduced",
            "to": "no-till"
          },
          "inputs": {
            "from": "low-c-input",
            "to": "high-c-input-with-manure"
          }
        },
        ...
      ],
      ,
      "forest_biomass": {
        "age_years": 5,
        "type": "boreal mountain system"
      }
   }


Direct Energy
#######################

Changes to the energy factors have affected the valid options for the ``source`` field in the ``direct_energy`` section.
Please see :ref:`DEFRA Energy Factors` for further details.


Machinery
#######################

Changes to the energy factors have affected the valid options for the ``fuel_type`` field in the ``machinery`` section.
Please see :ref:`DEFRA Energy Factors` for further details.

Irrigation
#######################

Changes to the energy factors have affected the valid options for the ``power_source`` field in the ``irrigation`` section.
Please see :ref:`DEFRA Energy Factors` for further details.

Processing
#######################

Changes to the energy factors have affected the valid options for the ``power_source`` field in the ``processing`` section.
Please see :ref:`DEFRA Energy Factors` for further details.

Storage
#######################

Changes to the energy factors have affected the valid options for the ``storage_power_source``,
``store_loading_power_source`` and ``unloading_power_source`` fields in the ``storage`` section.
Please see :ref:`DEFRA Energy Factors` for further details.


Dairy API
---------------------------------------

Updated Farm Object
#######################
Please see :ref:`Farm Object update` for more information on the updated farm object.

Fertiliser application
#######################
The ``application_date`` field has been added for the date of fertiliser applications. This is a required field in the
schema, however, if the application date is unknown you may input "unknown". If the date is known, it should be inputted as
a string in "yyyy-mm-dd" format.

If there are multiple applications of a unique product in a single month you can aggregate to a single ``Fertiliser application``
and use the midpoint of the month as the date of application. A new ``Fertiliser application`` must be inputted for each month
that a product is applied.

.. note::
   The date inputted must be within the harvest year or the year prior.

.. code-block:: json

  "fertilisers": [
      {
        "type": "Ammonium nitrate - 33.5% N (prilled)",
        "production": "Europe 2014",
        "custom_ingredients": {},
        "application_rate": {
          "value": 30,
          "unit": "kg / ha"
        },
        "application_date": "2022-11-25",
        "rate_measure": ""
      }
    ]

Fertiliser type renamed
***********************

The fertiliser type ``Horse manure - 0.7 % N`` has been renamed to ``Horse manure - 0.5 % N``.
Please use the new name, the ID remain the same.

The full list of fertiliser types can be found in the :ref:`fertiliser types <fertiliser type>`.

Fertiliser inhibition
*********************
An ``inhibition`` field is now available to the ``fertilisers`` section. This is an optional field.

See the full list of available :ref:`inhibitors <fertiliser inhibition>`.

Manure management
#################

The following manure management options have been renamed:

* ``Composting - forced aeration`` option has been renamed to ``Composting - In vessel (forced aeration)``.
* ``Composting - non-forced aeration`` option has been renamed to ``Composting - Passive window (infrequent turning)``.
* ``Pit storage below animal confinements (> 1 month)`` option has been renamed to ``Pit storage below animal confinements (6 month)``.
* ``Pit storage below animal confinements (< 1 month)`` option has been renamed to ``Pit storage below animal confinements (1 month)``.
* ``Anaerobic digester`` option has been renamed to ``Anaerobic Digester, High leakage, low quality technology, high quality gastight storage technology``.
* ``Deep bedding - no mixing`` option has been renamed to ``Deep bedding - no mixing (< 1 month)``.
* ``Deep bedding - active mixing`` option has been renamed to ``Deep bedding - active mixing (< 1 month)``.

Please use the new names, the IDs remain the same.

The following manure management options have been added.

.. list-table::
   :widths: 5 10
   :header-rows: 1

   * - ID
     - Name
   * - 19
     - Pit storage below animal confinements (3 months)
   * - 20
     - Pit storage below animal confinements (4 months)
   * - 21
     - Pit storage below animal confinements (12 months)
   * - 22
     - Solid storage – Covered/compacted
   * - 23
     - Solid storage – Bulking agent addition
   * - 24
     - Solid storage – Additives
     - Solid storage – Additives
   * - 25
     - Composting - Static pile (Forced aeration)
   * - 26
     - Composting - Intensive windrow
   * - 27
     - Anaerobic Digester, Low leakage, High quality gastight storage, best complete industrial technology
   * - 28
     - Anaerobic Digester, Low leakage, High quality industrial technology, low quality gastight storage technology
   * - 29
     - Anaerobic Digester, Low leakage, High quality industrial technology, open storage
   * - 30
     - Anaerobic Digester, High leakage, low quality technology, low quality gastight storage technology
   * - 31
     - Anaerobic Digester, High leakage, low quality technology, open storage
   * - 32
     - Liquid slurry with cover
   * - 33
     - Deep bedding - no mixing (> 1 month)
   * - 34
     - Deep bedding - active mixing (> 1 month)

The full list of manure management options can be found in the :ref:`manure management options <manure type>`.

Direct Energy
#######################

Changes to the energy factors have affected the valid options for the ``source`` field in the ``direct_energy`` section.
Please see :ref:`DEFRA Energy Factors` for further details.


Miscellaneous
-------------------

Retired Endpoints
#######################

* **POST /energy/calculate/** endpoint has been retired.

Reference data tables updated
-------------------

Fertiliser
##########
* The :ref:`Fertiliser type <fertiliser type>` data table has been updated.

Land Management
#######################
New reference data tables for the land_use, tillage and inputs sections have been added.

* :doc:`Updated Land use options  <../../reference-data/tables/land-use>`
* :doc:`Update Tillage options  <../../reference-data/tables/tillage>`
* :doc:`Updated carbon inputs  <../../reference-data/tables/carbon-inputs>`

Soil Characteristics
#######################
New reference data table for the soil characteristics has been added.

* :doc:`Soil Characteristics <../../reference-data/tables/soil-characteristics>`


Manure management
#######################
* The :ref:`manure management <manure type>` data table has been updated.

DEFRA energy factors
#######################
The following energy options have been renamed:

* ``diesel`` option has been renamed to ``diesel (average biofuel blend)``.
* ``petrol`` option has been renamed to ``petrol (average biofuel blend)``.
* ``biodiesel`` option has been renamed to ``biodiesel ME``.
* ``high density biomass`` option has been renamed to ``wood pellets``.
* ``biodiesel (low)`` option has been renamed to ``biodiesel HVO``.

Please use the new names. The IDs remain the same.

The ``bioethanol (low)`` option has been removed.

The following new energy options have been added.

.. list-table::
   :widths: 5 10
   :header-rows: 1

   * - ID
     - Name
   * - 1220
     - petrol (100% mineral petrol)
   * - 1221
     - diesel (100% mineral diesel)

See the full list of :ref:`energy options <direct-energy-type>`.

DEFRA transport factors
#######################
The following transport options have been renamed:

* ``ship large container vessel (~20 000t)`` option has been renamed to ``ship large container vessel (2,000+ TEU)``.
* ``ship small container vessel (~2500t)`` option has been renamed to ``ship small container vessel (0-1999 TEU)``.
* ``air long haul (>1600km)`` option has been renamed to ``air long haul (>3700km)``.
* ``air short haul (800 - 1600km)`` option has been renamed to ``air short haul (800 - 3700km)``.
* ``road HGV (heavy goods vehicle >3.5t)`` option has been renamed to ``road HGV (average heavy goods vehicle)``.

Please use the new names. The IDs remain the same.

The following new transport options have been added.

.. list-table::
   :widths: 5 10
   :header-rows: 1

   * - ID
     - Name
   * - 1217
     - car diesel
   * - 1218
     - car petrol
   * - 1219
     - motorbike

See the full list of :ref:`transport options <transport-type>`.

Crop type factors
#######################

The following crop has been renamed:

* ``Vegetable`` has been renamed to ``Vegetable - above ground``.

Please use the new name. The ID remains the same.

The following new crops have been added.

.. list-table::
   :widths: 5 10
   :header-rows: 1

   * - ID
     - Name
   * - 40
     - Sugarcane
   * - 41
     - Vegetable - root


See the full list of :ref:`crop types <crop-type>`.