This spec covers the REST APIs that powers Cercula's own frontend, which is also available to third-parties for building integrations.

This documentation is generated from the main specification definition, available on GitHub.

For more information about the API, contact Cercula.

The following describes the data model of Cercula's core entities, which power the user-facing frontend web app as well as any API-driven flows.

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│     ___                 _        ___     _   _ _          ___     _      _   _             _    _        ___  _                             │
│    / __|___ _ _ __ _  _| |__ _  | __|_ _| |_(_) |_ _  _  | _ \___| |__ _| |_(_)___ _ _  __| |_ (_)_ __  |   \(_)__ _ __ _ _ _ __ _ _ __     │
│   | (__/ -_) '_/ _| || | / _` | | _|| ' \  _| |  _| || | |   / -_) / _` |  _| / _ \ ' \(_-< ' \| | '_ \ | |) | / _` / _` | '_/ _` | '  \    │
│    \___\___|_| \__|\_,_|_\__,_| |___|_||_\__|_|\__|\_, | |_|_\___|_\__,_|\__|_\___/_||_/__/_||_|_| .__/ |___/|_\__,_\__, |_| \__,_|_|_|_|   │
│                                                    |__/                                          |_|                |___/                   │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                                                                                                               
                                                                                                                                               
                                                                                                                                               
                           ┌────────┐              ╱┌────────┐         ╱┌────────┐      ╱┌──────────┐                                          
                           │Project │┼───────────┼──│ Report │┼○─────┼──│ Batch  │┼○───○─│GWP Search│                                          
                           └────────┘              ╲└────────┘         ╲└────────┘      ╲└──────────┘                                          
                               ╲│╱                                           ┼                 ┼                                               
                                ○                                            │                 │                                               
                                │                                            │                 │                                               
                                │                                            │                 │                                               
                                ┼                                            │                 ○                                               
                         ┌────────────┐                                      ┼                 ┼                                               
                         │Organisation│                                  ┌───────┐       ╱┌────────┐                                           
                         └────────────┘                                  │ Stack │┼─────○─│  Row   │                                           
                                ┼                                        └───────┘       ╲└────────┘                                           
                                │                                                                                                              
                                ┼                                                                                                              
                               ╱│╲                                                                                                             
                           ┌────────┐                                                                                                          
                           │  User  │                                                                                                          
                           └────────┘                                                                                                          

Projects and Reports

The Cercula data model is primarily oriented around the notion of construction "projects", each of which may contain one or more "reports". An organisation may have multiple projects, where a project represents the construction project being built (a house or block of houses, an apartment building, a school, or a highway, for example). Some core properties of a project, like gross internal floor area (GIFA), will affect the carbon values.

For one project, the organisation may choose to upload multiple reports (to compare carbon values across different designs).

GWP (Global Warming Potential)

A GWP calculation is broken into multiple steps, each with an intermediate data type.

• In the case of a spreadsheet upload, the spreadsheet is parsed into a "stack", which is the user's uploaded Bill of Quantities/Bill of Materials spreadsheet broken into "row" objects
• A "report" is created (with a UUID that relates it to a project, as above)
• A "batch" is created and associated with the report
• Every "row" (from the stack, generated from the spreadsheet input) is evaluated and searched for in the database
• The report is updated with the search results, and the batch is marked as completed

Therefore the relations can be described as:

• a report can have many batches; a batch has zero-to-one report
• a batch has many rows; a row-search is associated with zero-to-one batch

All endpoints expect an Authorization header containing a Bearer token. For example, Authorization: Bearer <TOKEN>.