Skip to main content

​
Overview

The Pixxel platform uses a unified DataType format for passing data between processing blocks, insights, workflows, and jobs. This page documents all supported data types and their schemas.

​
Insights

This section explains how to construct input data for running insights (analytical models) on your AOI.

​
Using Input Schema from List Blocks API

The easiest way to construct inputs is to use the input schema returned by the List Blocks API. Each block includes an inputs array that defines the expected structure. You only need to populate the value or stac_url field for each input.

​
Step 1: Get the Block’s Input Schema

Call the List Blocks API to get the block specification: 
GET /v0/blocks/insights?name=cropclassification
The response includes the inputs array for the block: 
{
  "blocks": [
    {
      "spec": {
        "name": "cropclassification",
        "version": "1.0.0",
        "inputs": [
          {
            "format": "raster",
            "name": "input_image",
            "type": "url",
            "description": "Input satellite imagery",
            "properties": {
              "bands": ["B02", "B03", "B04", "B08"]
            }
          },
          {
            "format": "date",
            "name": "start_date",
            "type": "string",
            "description": "Analysis start date"
          },
          {
            "format": "date",
            "name": "end_date",
            "type": "string",
            "description": "Analysis end date"
          }
        ]
      }
    }
  ]
}

​
Step 2: Populate Values

Copy the input structure and add value or stac_url for each input:
  • For raster inputs from AOI assets: add stac_url and asset_source
  • For raster inputs from insight outputs: add value and asset_source
  • For date, string, number inputs: add value
The value field is always a string. The actual data type is determined by the type field (e.g., "type": "number" with "value": "0.8").
stac_url vs value for raster inputs:
  • Use stac_url when the input is from AOI assets (satellite imagery from STAC catalog)
  • Use value when the input is from a previous insight’s output (S3 URLs)
Example: Using AOI asset as raster input (stac_url) 
{
  "input": [
    {
      "format": "raster",
      "name": "input_image",
      "type": "url",
      "description": "Input satellite imagery",
      "properties": {
        "bands": ["B02", "B03", "B04", "B08"]
      },
      "stac_url": "https://stac.pixxel.space/collections/pixxel-td2/items/TD2_...",
      "asset_source": {
        "id": "asset_12345",
        "type": "raw_mosaic"
      }
    },
    {
      "format": "date",
      "name": "start_date",
      "type": "string",
      "description": "Analysis start date",
      "value": "2024-01-01"
    },
    {
      "format": "date",
      "name": "end_date",
      "type": "string",
      "description": "Analysis end date",
      "value": "2024-06-30"
    }
  ]
}
Example: Using insight output as raster input (value)
When using an insight’s output as input to another insight, copy the properties from the output to your input. This preserves visualization and discretization settings.
{
  "input": [
    {
      "format": "raster",
      "name": "classified_image",
      "type": "url",
      "description": "Input from previous insight",
      "value": "s3://pixxel-insights/outputs/inference-123/result.tif",
      "asset_source": {
        "id": "insight_xyz789",
        "type": "model_output"
      },
      //properties copied from the insight output.properties
      "properties": {
        "bands": ["classification"],
        "dtype": "uint8",
        "visualisation": {
          "type": "discrete",
          "discrete": {
            "1": "#00FF00",
            "2": "#FF0000"
          }
        },
        "discretization": {
          "type": "index",
          "classes": [
            { "name": "Vegetation", "value": "1", "color": "#00FF00" },
            { "name": "Built-up", "value": "2", "color": "#FF0000" }
          ]
        }
      }
    }
  ]
}

​
Asset Source

The asset_source field is required for raster and vector inputs to track data lineage.
Input Sourceasset_source.idasset_source.type
AOI asset (original imagery/data)asset_idraw_mosaic
Insight output (from previous run)insight_idmodel_output

​
Example: AOI Asset

"asset_source": {
  "id": "asset_abc123",
  "type": "raw_mosaic"
}

​
Example: Insight Output

"asset_source": {
  "id": "insight_xyz789",
  "type": "model_output"
}

​
Common Mistakes

Avoid these common errors when constructing input data:
MistakeCorrection
Using value instead of stac_url for AOI satellite assetsUse stac_url for STAC item references
Using stac_url for insight outputsUse value for S3 URLs from insight outputs
Forgetting asset_source for raster/vector inputsAlways include asset_source for data lineage
Wrong asset_source.typeUse raw_mosaic for AOI assets, model_output for insight outputs
Missing type fieldAlways specify the value type (url, string, number, boolean)

​
Complete Example

Here’s a complete example showing multiple input types for running an insight: 
{
  "name": "Crop Classification Analysis",
  "block": {
    "name": "cropclassification",
    "version": "1.0.0"
  },
  "input": [
    {
      "format": "raster",
      "name": "input_image",
      "type": "url",
      "stac_url": "https://stac.pixxel.space/collections/pixxel-td2/items/TD2_...",
      "asset_source": {
        "id": "asset_12345",
        "type": "raw_mosaic"
      },
      "properties": {
        "bands": ["B02", "B03", "B04", "B08"],
        "source": "pixxel-td2",
        "date": "2024-06-15"
      }
    },
    {
      "format": "date",
      "name": "start_date",
      "type": "string",
      "value": "2024-01-01"
    },
    {
      "format": "date",
      "name": "end_date",
      "type": "string",
      "value": "2024-06-30"
    },
    {
      "format": "number",
      "name": "confidence_threshold",
      "type": "number",
      "value": "0.8"
    }
  ]
}