Data Types
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=cropclassificationThe 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_urlandasset_source - For raster inputs from insight outputs: add
valueandasset_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_urlwhen the input is from AOI assets (satellite imagery from STAC catalog) - Use
valuewhen 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 Source | asset_source.id | asset_source.type |
|---|---|---|
| AOI asset (original imagery/data) | asset_id | raw_mosaic |
| Insight output (from previous run) | insight_id | model_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:
| Mistake | Correction |
|---|---|
Using value instead of stac_url for AOI satellite assets | Use stac_url for STAC item references |
Using stac_url for insight outputs | Use value for S3 URLs from insight outputs |
Forgetting asset_source for raster/vector inputs | Always include asset_source for data lineage |
Wrong asset_source.type | Use raw_mosaic for AOI assets, model_output for insight outputs |
Missing type field | Always 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"
}
]
}