Input Values

This guide explains the different types of values that can be submitted through the G17Eco Public API and how to structure them correctly.

Value Types Overview

The API supports the following data types for Universal Tracker Values based on the UtrValueType enum:

Numeric Values

Numeric values are stored in the value field and support decimal precision configuration.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "value": 12345.67,
  "valueType": "number"
}

Validation Rules:

• Decimal precision: 0-5 places (configured per tracker)
• Number scale can be applied (thousands, millions, etc.)

Text Values

Text values are stored in valueData.data as strings.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "data": "This is a text response describing our sustainability practices."
  },
  "valueType": "text"
}

Validation Rules:

• Maximum length: 5,000 characters
• UTF-8 encoding supported
• Line breaks preserved

Date Values

Dates must be provided in ISO 8601 format.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "data": "2024-12-31"
  },
  "valueType": "date"
}

Format Options:

• Date only: YYYY-MM-DD
• Date and time: YYYY-MM-DDTHH:mm:ss
• With timezone: YYYY-MM-DDTHH:mm:ssZ

Value List (Single Selection)

For trackers with predefined options, submit the selected option ID from the associated value list.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "data": "option_id_123"
  },
  "valueType": "valueList"
}

Value List Multi (Multiple Selection)

Multiple selections are submitted as an array of option IDs.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "data": ["option_1", "option_2", "option_3"]
  },
  "valueType": "valueListMulti"
}

Validation Rules:

• Maximum 100 selected items
• All IDs must exist in the associated value list

Text Value List (Multiple Text Checkboxes)

For text-based checkbox lists where users provide text values for selected options. Data is stored as key-value pairs where keys are the value list codes from the associated value list.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "data": {
      "country_uk": "London office",
      "country_us": "New York office",
      "country_jp": "Tokyo office"
    }
  },
  "valueType": "textValueList"
}

Note: The keys (country_uk, country_us, etc.) are value list codes that must exist in the value list referenced by valueValidation.valueList.listId. To get the display labels for these codes, resolve them through the /value-list/lookup endpoint.

Numeric Value List (Multiple Numeric Checkboxes)

For numeric-based checkbox lists where users provide numeric values for selected options. Data is stored as key-value pairs where keys are the value list codes from the associated value list.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "data": {
      "country_uk": 500,
      "country_us": 700,
      "country_jp": 300,
      "country_de": 450
    }
  },
  "valueType": "numericValueList"
}

Note: The keys (country_uk, country_us, etc.) are value list codes that must exist in the value list referenced by valueValidation.valueList.listId. To get the display labels for these codes (e.g., "United Kingdom", "United States"), resolve them through the /value-list/lookup endpoint.

Table Values

Tables store structured data in a 2D array format, useful for complex metrics like emissions breakdowns.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "table": [
      [
        { "code": "scope1", "value": 1250.5 },
        { "code": "scope2", "value": 850.3 }
      ],
      [
        { "code": "scope3_upstream", "value": 5200 },
        { "code": "scope3_downstream", "value": 3800 }
      ]
    ]
  },
  "valueType": "table"
}

Extended Table Format with Units:

{
  "valueData": {
    "table": [
      [
        { 
          "code": "emissions_direct",
          "value": 1250.5,
          "unit": "tCO2e",
          "numberScale": "single"
        },
        {
          "code": "emissions_indirect",
          "value": 2.3,
          "unit": "tCO2e", 
          "numberScale": "thousands"
        }
      ]
    ]
  }
}

Validation Rules:

• Maximum 1,000 rows
• Maximum 50 columns
• Each cell can have its own unit and number scale
• Cell values can be numbers or strings

Percentage Values

Percentage values are numeric values constrained to 0-100 range.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "value": 85.5,
  "valueType": "percentage"
}

Validation Rules:

• Typically 0 to 100, but can exceed based on use case
• Decimal precision: 0-2 places typically

Not Applicable Values

When a metric is not applicable or not reported, use the notApplicableType field.

{
  "universalTrackerId": "507f1f77bcf86cd799439011",
  "valueData": {
    "notApplicableType": "na"  // or "nr" for not reported
  }
}

Options:

• "na" - Not Applicable (metric doesn't apply to this entity)
• "nr" - Not Reported (metric applies but data unavailable)

Validation Best Practices

Next Steps

• Review Unit Types for measurement units and conversions
• Check Data Relationships to understand entity connections
• See API Routes for submission endpoints