Input Payload Documentation

The input_payload parameter is a complex nested structure that contains detailed agricultural and supply chain data for emissions calculations. It consists of three main payload types: CFT (Cool Farm Tool), LCA (Life Cycle Assessment), and EUDR (EU Deforestation Regulation).

Overview

The input_payload parameter is used in both /batch_process and /batch_supply_shed endpoints to provide detailed agricultural practices and supply chain information for accurate emissions calculations.

{
  "input_payload": {
    "cft_payload": { ... },
    "lca_payload": { ... },
    "eudr_payload": { ... }
  }
}

CFT Payload (Cool Farm Tool)

The CFT payload contains detailed agricultural practices data for calculating farm-level emissions.

Structure

{
  "cft_payload": {
    "land_management": {
      "tillage": "conventional",
      "residue_management": "incorporated",
      "cover_crop": false
    },
    "crop": {
      "type": "cocoa",
      "variety": "forastero",
      "planting_density": 1000,
      "yield": {
        "value": 500,
        "unit": "kg/ha"
      }
    },
    "farm": {
      "size": {
        "value": 10,
        "unit": "ha"
      },
      "location": {
        "country": "Ghana",
        "region": "Western Region"
      }
    },
    "fertilisers": [
      {
        "type": "NPK",
        "application_rate": {
          "value": 200,
          "unit": "kg/ha"
        },
        "application_method": "broadcast",
        "application_timing": "pre-planting"
      }
    ],
    "pesticides": [
      {
        "type": "herbicide",
        "active_ingredient": "glyphosate",
        "application_rate": {
          "value": 2,
          "unit": "L/ha"
        }
      }
    ],
    "irrigation": [
      {
        "type": "drip",
        "water_source": "groundwater",
        "application_rate": {
          "value": 500,
          "unit": "mm/year"
        }
      }
    ],
    "machinery": [
      {
        "type": "tractor",
        "fuel_type": "diesel",
        "fuel_consumption": {
          "value": 50,
          "unit": "L/ha"
        }
      }
    ],
    "transport": [
      {
        "type": "truck",
        "distance": {
          "value": 50,
          "unit": "km"
        },
        "fuel_type": "diesel",
        "load_factor": 0.8
      }
    ],
    "tree_biomass": [
      {
        "species": "cocoa",
        "age": 15,
        "density": {
          "value": 1000,
          "unit": "trees/ha"
        }
      }
    ],
    "processing": [
      {
        "type": "fermentation",
        "duration": {
          "value": 5,
          "unit": "days"
        },
        "temperature": {
          "value": 25,
          "unit": "C"
        }
      }
    ],
    "storage": [
      {
        "type": "warehouse",
        "duration": {
          "value": 30,
          "unit": "days"
        },
        "temperature": {
          "value": 20,
          "unit": "C"
        }
      }
    ],
    "direct_energy": [
      {
        "type": "electricity",
        "source": "grid",
        "consumption": {
          "value": 100,
          "unit": "kWh/ha"
        }
      }
    ],
    "waste_water": {
      "treatment": "anaerobic",
      "volume": {
        "value": 1000,
        "unit": "L/ha"
      }
    },
    "co_products": [
      {
        "type": "cocoa_pod_husk",
        "yield": {
          "value": 200,
          "unit": "kg/ha"
        },
        "use": "compost"
      }
    ]
  }
}

Key Fields

Land Management

• tillage: Tillage practice (conventional, reduced, no_till)
• residue_management: How crop residues are managed (incorporated, burned, removed)
• cover_crop: Whether cover crops are used (true/false)

Crop Information

• type: Crop type (must match valid crop values)
• variety: Crop variety
• planting_density: Number of plants per hectare
• yield: Expected yield with value and unit

Farm Details

• size: Farm size in hectares
• location: Country and region information

Inputs

• fertilisers: List of fertiliser applications with type, rate, method, and timing
• pesticides: List of pesticide applications with type, active ingredient, and rate
• irrigation: Irrigation systems and water usage
• machinery: Farm machinery usage and fuel consumption

Processing and Storage

• processing: Post-harvest processing steps
• storage: Storage conditions and duration
• transport: Transportation details and fuel usage

LCA Payload (Life Cycle Assessment)

The LCA payload provides comprehensive life cycle assessment data for the entire supply chain.

Using the LCA payload for batch non-biomass emissions

Non-biomass emissions calculations are integrated directly into batch processing. To enable them, set: - non_biomass=true on /batch_process or /batch_supply_shed - Provide input_payload.lca_payload (structure below)

Supported crop types (current): - tea - timber - shrimp

If non_biomass=true is used with an unsupported crop_type, the API will return an error.

Empty lists (e.g. chemicals: [], materials: [], etc.) do not mean zero emissions — they trigger defaults / emission factors so the inventory remains complete.

Structure

{
  "lca_payload": {
    "hatchery": {
      "inputs": [
        {
          "type": "feed",
          "amount": {
            "value": 100,
            "unit": "kg"
          }
        }
      ]
    },
    "nursery": {
      "inputs": [
        {
          "type": "seedling",
          "amount": {
            "value": 1000,
            "unit": "units"
          }
        }
      ]
    },
    "farmgate": {
      "inputs": [
        {
          "type": "fertiliser",
          "amount": {
            "value": 200,
            "unit": "kg"
          }
        }
      ]
    },
    "land_use": {
      "previous_land_use": "forest",
      "conversion_date": "2020-01-01"
    },
    "processing": {
      "type": "primary",
      "inputs": [
        {
          "type": "energy",
          "amount": {
            "value": 50,
            "unit": "kWh"
          }
        }
      ]
    },
    "distribution": {
      "transport_mode": "truck",
      "distance": {
        "value": 100,
        "unit": "km"
      }
    },
    "co_products": [
      {
        "type": "waste",
        "amount": {
          "value": 50,
          "unit": "kg"
        }
      }
    ],
    "country": "Ghana",
    "year": 2024,
    "base_year": 2020,
    "commodity_type": "cocoa",
    "commodity_yield": {
      "value": 500,
      "unit": "kg/ha"
    },
    "product_fresh": {
      "value": 1000,
      "unit": "kg"
    },
    "product_finished": {
      "value": 800,
      "unit": "kg"
    },
    "product_cf": 0.8,
    "production_area": {
      "value": 10,
      "unit": "ha"
    }
  }
}

Key Fields

Supply Chain Stages

• hatchery: Inputs and processes at hatchery stage
• nursery: Nursery operations and inputs
• farmgate: Farm-level inputs and operations
• processing: Processing stage inputs and energy use
• distribution: Transportation and distribution details

Land Use

• previous_land_use: Previous land use before conversion
• conversion_date: Date of land use conversion

Product Information

• commodity_type: Type of commodity being produced
• commodity_yield: Yield per unit area
• product_fresh: Fresh product quantity
• product_finished: Finished product quantity
• product_cf: Conversion factor from fresh to finished

EUDR Payload (EU Deforestation Regulation)

The EUDR payload contains information required for EUDR compliance and risk assessment.

Structure

{
  "eudr_payload": {
    "hs_code": "180100",
    "product_trade_name": "Cocoa Beans",
    "product_quantity": 1000.0,
    "product_type": "cocoa",
    "product_description": "Organic cocoa beans",
    "production_country": "Ghana",
    "production_year": 2024,
    "species_common_name": "Cocoa",
    "species_scientific_name": "Theobroma cacao",
    "supplier_name": "Ghana Cocoa Board",
    "supplier_address": "Accra, Ghana",
    "supplier_email": "contact@ghanacocoaboard.com",
    "operator_name": "Epoch Trading Ltd",
    "operator_address": "London, UK",
    "operator_email": "contact@epoch.blue",
    "operator_country": "United Kingdom",
    "operator_eori": "GB123456789012",
    "operator_phone": "+44 20 1234 5678",
    "referenced_dds": [
      {
        "referenceNumber": "25BEM0MMW93068",
        "verificationNumber": "IA5BHNFL"      
      }
    ]
  }
}

Key Fields

Product Information

• hs_code: Harmonized System code for the product (must be from EUDR Annex I - see Valid HS Codes below)
• product_trade_name: Commercial name of the product
• product_quantity: Quantity in kilograms
• product_type: Type of commodity
• product_description: Detailed product description

Production Details

• production_country: Country where the product was produced
• production_year: Year of production
• species_common_name: Common name of the species
• species_scientific_name: Scientific name of the species

Supply Chain Actors

• supplier_name: Name of the supplier
• supplier_address: Supplier address
• supplier_email: Supplier contact email
• operator_name: Name of the operator (importer)
• operator_address: Operator address
• operator_email: Operator contact email
• operator_country: Operator country
• operator_eori: Operator EORI (Economic Operators Registration and Identification) number
• operator_phone: Operator phone number

Compliance

• referenced_dds: List of referenced Due Diligence Statements with referenceNumber and verificationNumber

Valid HS Codes

The hs_code field must contain a Harmonized System (HS) code from EUDR Annex I, as specified in Regulation (EU) 2023/1115. The following HS codes are valid for EUDR compliance:

Cattle (Beef)

HS Code	Description
0201	Meat of bovine animals, fresh or chilled
0202	Meat of bovine animals, frozen
0210	Meat and edible meat offal, salted, in brine, dried or smoked
1602	Other prepared or preserved meat, meat offal or blood

Cocoa

HS Code	Description
1801	Cocoa beans, whole or broken, raw or roasted
1802	Cocoa shells, husks, skins and other cocoa waste
1803	Cocoa paste, whether or not defatted
1804	Cocoa butter, fat and oil
1805	Cocoa powder, not containing added sugar or other sweetening matter
1806	Chocolate and other food preparations containing cocoa

Coffee

HS Code	Description
0901	Coffee, whether or not roasted or decaffeinated; coffee husks and skins; coffee substitutes containing coffee in any proportion

Palm Oil

HS Code	Description
1511	Palm oil and its fractions, whether or not refined, but not chemically modified
151110	Crude palm oil
151190	Other palm oil and its fractions, refined but not chemically modified

Soy

HS Code	Description
1201	Soya beans, whether or not broken
1507	Soya-bean oil and its fractions, whether or not refined, but not chemically modified
2304	Oil-cake and other solid residues, whether or not ground or in the form of pellets, resulting from the extraction of soya-bean oil

Rubber

HS Code	Description
4001	Natural rubber, balata, gutta-percha, guayule, chicle and similar natural gums, in primary forms or in plates, sheets or strip
4002	Synthetic rubber and factice derived from oils, in primary forms or in plates, sheets or strip
4005	Compounded rubber, unvulcanised, in primary forms or in plates, sheets or strip
4006	Other forms (for example, rods, tubes and profile shapes) and articles (for example, discs and rings), of unvulcanised rubber
4007	Vulcanised rubber thread and cord
4008	Plates, sheets, strip, rods and profile shapes, of vulcanised rubber other than hard rubber
4009	Tubes, pipes and hoses, of vulcanised rubber other than hard rubber, with or without their fittings (for example, joints, elbows, flanges)
4010	Conveyor or transmission belts or belting, of vulcanised rubber
4011	New pneumatic tyres, of rubber
4012	Retreaded or used pneumatic tyres of rubber; solid or cushion tyres, tyre treads and tyre flaps, of rubber
4013	Inner tubes, of rubber
4014	Hygienic or pharmaceutical articles (including teats), of vulcanised rubber other than hard rubber, with or without fittings of hard rubber
4015	Articles of apparel and clothing accessories (including gloves, mittens and mitts), for all purposes, of vulcanised rubber other than hard rubber
4016	Other articles of vulcanised rubber other than hard rubber
4017	Hard rubber (for example, ebonite) in all forms; articles of hard rubber

Wood

HS Code	Description
4401	Fuel wood, in logs, in billets, in twigs, in faggots or in similar forms; wood in chips or particles; sawdust and wood waste and scrap, whether or not agglomerated in logs, briquettes, pellets or similar forms
4403	Wood in the rough, whether or not stripped of bark or sapwood, or roughly squared
4404	Hoopwood; split poles; piles, pickets and stakes of wood, pointed but not sawn lengthwise; wooden sticks, roughly trimmed but not turned, bent or otherwise worked, suitable for the manufacture of walking-sticks, umbrellas, tool handles or the like; chipwood and the like
4406	Railway or tramway sleepers (cross-ties) of wood
4407	Wood sawn or chipped lengthwise, sliced or peeled, whether or not planed, sanded or end-jointed, of a thickness exceeding 6 mm
4408	Veneer sheets and sheets for plywood (whether or not spliced) and other wood sawn lengthwise, sliced or peeled, whether or not planed, sanded, spliced or end-jointed, of a thickness not exceeding 6 mm
4409	Wood (including strips and friezes for parquet flooring, not assembled) continuously shaped (tongued, grooved, rebated, chamfered, V-jointed, beaded, moulded, rounded or the like) along any of its edges, ends or faces, whether or not planed, sanded or end-jointed
4410	Particle board, oriented strand board (OSB) and similar board (for example, waferboard) of wood or other ligneous materials, whether or not agglomerated with resins or other organic binding substances
4411	Fibreboard of wood or other ligneous materials, whether or not bonded with resins or other organic substances
4412	Plywood, veneered panels and similar laminated wood
4413	Densified wood, in blocks, plates, strips or profile shapes
4414	Wooden frames for paintings, photographs, mirrors or similar objects
4415	Packing cases, boxes, crates, drums and similar packings, of wood; cable-drums of wood; pallets, box pallets and other load boards, of wood; pallet collars of wood (not including packing material used exclusively as packing material to support, protect or carry another product placed on the market)
4416	Casks, barrels, vats, tubs and other coopers' products and parts thereof, of wood, including staves
4417	Tools, tool bodies, tool handles, broom or brush bodies and handles, of wood; boot or shoe lasts and trees, of wood
4418	Builders' joinery and carpentry of wood, including cellular wood panels, assembled flooring panels, shingles and shakes
4419	Tableware and kitchenware, of wood
4420	Wood marquetry and inlaid wood; caskets and cases for jewellery or cutlery, and similar articles, of wood; statuettes and other ornaments, of wood; wooden articles of furniture not falling in Chapter 94
4421	Other articles of wood

Pulp and Paper

HS Code	Description
4701	Mechanical wood pulp
4702	Chemical wood pulp, dissolving grades
4703	Chemical wood pulp, soda or sulphate, other than dissolving grades
4704	Chemical wood pulp, sulphite, other than dissolving grades
4705	Semi-chemical wood pulp
4706	Pulps of fibres derived from recovered (waste and scrap) paper or paperboard or of other fibrous cellulosic material
4707	Recovered (waste and scrap) paper or paperboard
4801	Newsprint, in rolls or sheets
4802	Uncoated paper and paperboard, of a kind used for writing, printing or other graphic purposes, and punch card stock and punch tape paper, in rolls or sheets, not further worked or processed than as specified in Note 3 to this Chapter
4803	Toilet or facial tissue stock, towel or napkin stock and similar paper of a kind used for household or sanitary purposes, cellulose wadding and webs of cellulose fibres, whether or not creped, crinkled, embossed, perforated, surface-coloured, surface-decorated or printed, in rolls or sheets
4804	Uncoated kraft paper and paperboard, in rolls or sheets, not further worked or processed than as specified in Note 3 to this Chapter
4805	Other uncoated paper and paperboard, in rolls or sheets, not further worked or processed than as specified in Note 3 to this Chapter
4806	Vegetable parchment, greaseproof papers, tracing papers and glassine and other glazed transparent or translucent papers, in rolls or sheets
4807	Composite paper and paperboard (made by sticking flat layers of paper or paperboard together with an adhesive), not surface-coated or impregnated, whether or not internally reinforced, in rolls or sheets
4808	Paper and paperboard, corrugated (with or without flat surface sheets), creped, crinkled, embossed or perforated, in rolls or sheets, other than paper of the kind described in heading 4803
4809	Carbon paper, self-copy paper and other copying or transfer papers (including coated or impregnated paper for duplicating stencils or offset plates), whether or not printed, in rolls or sheets
4810	Paper and paperboard, coated on one or both sides with kaolin (China clay) or other inorganic substances, with or without a binder, and with no other coating, whether or not surface-coloured, surface-decorated or printed, in rolls or sheets
4811	Paper, paperboard, cellulose wadding and webs of cellulose fibres, coated, impregnated, covered, surface-coloured, surface-decorated or printed, in rolls or sheets, other than goods of the kind described in heading 4803, 4809 or 4810
4812	Filter blocks, slabs and plates, of paper pulp
4813	Cigarette paper, whether or not cut to size or in the form of booklets or tubes
4814	Wallpaper and similar wall coverings; window transparencies of paper
4815	Floor coverings on a base of paper or of paperboard, whether or not cut to size
4816	Carbon paper, self-copy paper and other copying or transfer papers (including coated or impregnated paper for duplicating stencils or offset plates), whether or not printed, in rolls or sheets
4817	Envelopes, letter cards, plain postcards and correspondence cards, of paper or paperboard
4818	Toilet paper and similar paper, cellulose wadding or webs of cellulose fibres, of a kind used for household or sanitary purposes, in rolls of a width not exceeding 36 cm, or cut to size or shape; handkerchiefs, cleansing tissues, towels, tablecloths, serviettes, bed sheets and similar household, sanitary or hospital articles, articles of apparel and clothing accessories, of paper pulp, paper, cellulose wadding or webs of cellulose fibres
4819	Cartons, boxes, cases, bags and other packing containers, of paper, paperboard, cellulose wadding or webs of cellulose fibres; box files, letter trays, storage boxes and similar articles, of paper or paperboard, of a kind used in offices, shops or the like
4820	Registers, account books, note books, order books, receipt books, letter pads, memorandum pads, diaries and similar articles, exercise books, blotting-pads, binders (loose-leaf or other), folders, file covers, manifold business forms, interleaved carbon sets and other articles of stationery, of paper or paperboard; albums for samples or for collections and book covers, of paper or paperboard
4821	Paper or paperboard labels of all kinds, whether or not printed
4822	Bobbins, spools, cops and similar supports of paper pulp, paper or paperboard (whether or not perforated or hardened)
4823	Other paper, paperboard, cellulose wadding and webs of cellulose fibres, cut to size or shape; other articles of paper pulp, paper, paperboard, cellulose wadding or webs of cellulose fibres
49	Printed books, newspapers, pictures and other products of the printing industry, manuscripts, typescripts and plans, of paper

Additional Wood Products

HS Code	Description
9401	Seats (other than those of heading 9402), whether or not convertible into beds, and parts thereof, of wood
9403	Other furniture and parts thereof
9406	Prefabricated buildings of wood

Source: Regulation (EU) 2023/1115, Annex I

Note: The API accepts HS codes in various formats (e.g., "4005", "ex 4005", "18.01", "1801.00", "1803.10") and will normalize them for validation. The validation checks against the base 4-digit code.

Usage Examples

Basic Usage

# Minimal payload with defaults
input_payload = {
    "cft_payload": {},
    "lca_payload": {},
    "eudr_payload": {}
}

Complete Example

# Complete payload with all fields
input_payload = {
    "cft_payload": {
        "crop": {
            "type": "cocoa",
            "yield": {"value": 500, "unit": "kg/ha"}
        },
        "farm": {
            "size": {"value": 10, "unit": "ha"},
            "location": {"country": "Ghana"}
        },
        "fertilisers": [
            {
                "type": "NPK",
                "application_rate": {"value": 200, "unit": "kg/ha"}
            }
        ]
    },
    "lca_payload": {
        "country": "Ghana",
        "year": 2024,
        "commodity_type": "cocoa"
    },
    "eudr_payload": {
        "product_type": "cocoa",
        "production_country": "Ghana",
        "production_year": 2024
    }
}

Form Data Usage

When using form data (as required by the endpoints), the payload should be JSON stringified:

import json

request_data = {
    "collection_name": "my_cocoa_plots",
    "input_payload": json.dumps(input_payload),
    "crop_type": "cocoa",
    "stats": "luc_emissions,eudr_deforestation"
}

Validation

The input payload is validated against defined models. Key validation rules include:

• Crop types: Must be from the valid crop values list
• Units: Must use standard units (kg, ha, L, etc.)
• Dates: Must be in YYYY-MM-DD format
• Required fields: Certain fields are required for specific calculations

Default Values

If not provided, the system will use default values for most fields. However, for accurate emissions calculations, it's recommended to provide as much detail as possible.

Error Handling

If the input payload contains invalid data, the API will return a 422 validation error with details about which fields are invalid and what the expected format should be.