Data Relationships

Understanding the relationships between different API entities is crucial for effective integration with the G17Eco platform. This page outlines the hierarchical structure and connections between various data types.

Entity Relationship Overview

Core Entities

Initiatives

Initiatives form the foundation of the organizational structure in G17Eco. They represent companies, subsidiaries, or organizational units that track sustainability metrics.

Relationships:

• Can have parent-child relationships with other initiatives via parentId
• Contains multiple surveys/reports
• Forms a hierarchical tree structure

See Initiative API for the complete TypeScript interface.

Surveys (Reports)

Surveys, also known as Reports, are periodic data collection instruments that capture sustainability metrics for a specific time period.

Report Coverage Period:

The effectiveDate represents the end date of the reporting period. The coverage range is determined by:

Relationships:

• Belongs to exactly one initiative via initiativeId
• Contains multiple Universal Tracker Values (UTRVs)
• lastUpdated is aggregated from contained UTRV changes

See Survey API for the complete TypeScript interface.

Universal Tracker Values (UTRVs)

UTRVs are the actual data points that store sustainability metrics. They represent specific measurements like emissions, energy consumption, or social metrics.

Key Data Storage:

• Simple values: Stored in value field for numeric/percentage data
• Complex values: Stored in valueData field
  • data: Text, arrays, or selections
  • table: 2D arrays for matrix data (e.g., emissions by scope)
  • notApplicableType: 'na' or 'nr' flags

Relationships:

• Belongs to a survey (inherits period, effectiveDate, evidence/verification requirements)
• References a Universal Tracker for metadata and validation rules
• May reference value lists for controlled vocabularies

See UTRV API for the complete TypeScript interface.

Universal Trackers

Universal Trackers define the metadata and schema for UTRVs. They act as templates that specify what type of data should be collected.

Relationships:

• One-to-many with UTRVs
• Defines validation rules, units, and data types
• May reference value lists for dropdown options

Value Lists

Value Lists provide controlled vocabularies for dropdown and select fields in the system.

Relationships:

• Referenced by UTRVs that use controlled vocabularies
• Can be shared across multiple UTRVs
• Fetched via /value-list/lookup endpoint

Data Flow Patterns

Hierarchical Data Retrieval

1. Fetch Initiative Tree
   └── Get all child initiatives
       └── For each initiative, get surveys
           └── For each survey, get UTRVs
               └── For each UTRV, get Universal Tracker metadata

Change-Based Synchronization

1. Query surveys with changedSince parameter
2. System aggregates max(lastUpdated) from UTRVs
3. Returns only surveys with changes after specified date
4. Fetch detailed data for changed surveys only

Complex Data Structures

Table Data in UTRVs

UTRVs can store complex matrix data using the table structure:

{
  "valueData": {
    "table": [
      [
        { "code": "scope1", "value": 1250.5, "unit": "tCO2e", "numberScale": "single" },
        { "code": "scope2", "value": 850.3, "unit": "tCO2e", "numberScale": "single" }
      ],
      [
        { "code": "scope3_upstream", "value": 5.2, "unit": "tCO2e", "numberScale": "thousands" },
        { "code": "scope3_downstream", "value": 3.8, "unit": "tCO2e", "numberScale": "thousands" }
      ]
    ]
  }
}

This structure allows for:

• Multi-dimensional data representation
• Different units and scales per cell
• Complex emissions breakdowns
• Category-based reporting

Best Practices for Data Relationships

API Endpoints by Relationship