Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.appliedaifoundation.org/llms.txt

Use this file to discover all available pages before exploring further.

The platform accepts Excel consumption logs in .xlsx and .xls. Files up to 50 MB are supported. There’s no rigid schema — column headers are normalised on the fly to camelCase database fields, and only a handful of fields are strictly required.

​
Header normalisation

Excel headers are converted to camelCase using these rules (src/lib/utils/excelParser.ts):
  • Split on whitespace, parentheses, /, -, %
  • Strip degree symbols (°)
  • Convert ³ → 3, ² → 2
  • First token lowercased, subsequent tokens TitleCased
  • Result: a PostgreSQL column name
Examples:
Excel headerDatabase field
Timestamp (UTC)timestampUtc
Cargo Weight (t)cargoWeightT
Active ReefersactiveReefers
Distance Over Ground (nm)distanceOverGroundNm
Average Speed Over Ground (corrected) (kn)averageSpeedOverGroundCorrectedKn
CII Attained (g/t-nm CO2)ciiAttainedGTNmCo2
Heading (°)heading
Total Waste Disposal (m³)totalWasteDisposalM3
This means you don’t need to rename your existing vendor exports — drop them in and the platform figures it out.

​
Required column

Exactly one column is strictly required:
  • timestampUtc (any header that normalises to this — typically Timestamp (UTC))
Rows without a valid timestampUtc are flagged in the preview and not inserted. The richer your data, the more the platform can do. The following fields drive specific calculations:

​
Identity

  • imo — vessel IMO (also supplied via the upload form)
  • voyageName — voyage number (e.g. 99W, 102E)
  • event — BOSP (Beginning of Sea Passage), EOSP, etc. Required for accurate EU ETS leg detection.
  • state — In Port / At Sea (drives port-vs-sea CO₂ split)

​
Position & route

  • portOfOrigin / portOfOriginUnloc — departure port + UN/LOCODE
  • portOfDestination / portOfDestinationUnloc — arrival port + UN/LOCODE
  • lat / lng — geographic position (powers the Maps page)

​
Distance & speed

  • distanceOverGroundNm
  • averageSpeedOverGroundCorrectedKn

​
Emissions

  • totalCo2T — total CO₂ in tonnes for the period
  • Optional breakdowns: main engine, auxiliary, boiler

​
Fuel consumption (tonnes per period)

  • totalFocT — total fuel consumption
  • By type: totalFocHfoHsT, totalFocHfoLsT, totalFocLfoT, totalFocMdoT, totalFocMgoT, totalFocLngT, totalFocMethanolT, totalFocBioFuelBlendT

​
CII

  • ciiAttainedGTNmCo2
  • ciiRequired
  • ciiRating
If supplied, the platform uses these directly for vessel-level CII display. The methodology engine still computes Required and Attained CII from raw inputs for cross-checking.

​
Cargo

  • cargoWeightT — for weight-based EEOI
  • cargoTeu — for TEU-based EEOI

​
Reefer correction

  • activeReefers — count of active reefer containers in this period
Reefer-hours are accumulated as Σ activeReefers × period, which feeds reefer correction.

​
Timestamp parsing

timestampUtc accepts:
  • ISO 8601 strings (2025-04-15T08:00:00Z)
  • Excel date serial numbers (auto-detected, converted as UTC)
  • Short formats like 4/15/25 08:00
All timestamps are stored as UTC.

​
Duplicate detection

A row is considered a duplicate if a record already exists for the same imo + timestampUtc. Duplicates are skipped (not overwritten) — the upload preview tells you exactly how many will be skipped before you commit.

​
Preview behaviour

The preview endpoint (POST /api/upload/consumption?action=preview):
  • Returns column count, total rows, date range, valid rows
  • Returns the first 10 rows of normalised data so you can verify column mapping
  • Reports any duplicate count
  • Returns explicit row-level errors for invalid timestamps or missing required fields
Once preview looks right, the same endpoint without ?action=preview performs the insert.

​
Reference

  • Parser: src/lib/utils/excelParser.ts
  • Upload route: src/app/api/upload/consumption/route.ts
  • Service layer: src/lib/services/UploadService.ts