Skip to main content

​
Overview

This endpoint lets users create a new visulaization over an AOI using specified index and assets. It requires a JSON request body with fields like aoi_id, index_id, and src_asset_id. Once created, the API returns the visualization object with a 201 Created status. API key authentication is mandatory. Errors for invalid input or duplication are returned with appropriate codes and messages.

  • Method: POST
  • URL: /v0/aois/{aoi_id}/visualizations
  • Operation: Create a new visualization oven an AOI
  • Authentication Required: Yes

​
Authorization

You need the api key which you can get from the API tab in Organization Settings. The api key is required in almost all the commands

Authorization: <YOUR_API_KEY>

​
Body

You need the following fields in Body :

FieldTypeRequiredDescription
index_idstring✅ID of the Index to be visualized
src_asset_idarray of string✅ID of the assets of AOI to be included in visualization
Here is a sample of the Body:
body
{
  "index_id": "<string>",
  "src_asset_ids": [
    "<string>",
    "<string>"
  ]
}

​
Path Parameters

This endpoint require aoi_id as the only path parameter.

NameTypeRequiredDescription
aoi_idstringYesUnique ID of the AOI

​
Response

The response for this endpoint confirms successful visualization creation with a 201 Created status. It returns detailed information about the visualization, including its ID, area, bands, expression, geometry, and timestamps. If there’s an error, such as missing fields or duplication, a structured error message with relevant status code is returned.Please refer to the table below for explaination of the fields in the response:

NameTypeDescription
aoi_idarray of stringUnique ID of the AOI
created_atstringTimestamp when the visualization was created (ISO 8601 format)
expressionstringMathematical expression applied using the selected bands
expression_typestringType of the expression (e.g., “index”, “formula”)
idstringUnique identifier of the visualization
index_idstringUnique ID of the AOI
index_namestringHuman-readable name of the index
progressstringDetails of progress in visualization creation
rescalenumberMin and max range used to normalize or rescale the output values
statusstringStatus of the visualization(“creating”, “success”, “failed”, “partial_success”)
typestringType of formula, usually “custom” for user-defined expressions
updated_atstringTimestamp when the visualization was last updated (ISO 8601 format)
user_idstringUnique ID of the user
Here is a sample 201 response:
201
{
  "aoi_id": "<string>",
  "assets": [
    {
      "aoi_id": "<string>",
      "area_in_sq_m": 0,
      "asset_type": "mosaic",
      "band_list": [
        "<string>",
        "<string>"
      ],
      "centroid": [
        77.55,
        12.95
      ],
      "created_at": "2022-11-14 12:55:49.125928+00:00",
      "date": "2022-11-14",
      "description": "<string>",
      "geometry": {
        "coordinates": [
          [
            [
              123
            ]
          ]
        ],
        "type": "<string>"
      },
      "id": "<string>",
      "name": "<string>",
      "path": "https://storage.account",
      "progress": 0,
      "status": "success",
      "updated_at": "2022-11-14 12:55:49.125928+00:00",
      "visualization_id": "<string>"
    }
  ],
  "created_at": "2022-11-14 12:55:49.125928+00:00",
  "expression": "<string>",
  "expression_type": "index",
  "id": "<string>",
  "index_id": "<string>",
  "index_name": "<string>",
  "progress": 100,
  "rescale": [
    0,
    1
  ],
  "status": "success",
  "tenant_id": "<string>",
  "type": "custom",
  "updated_at": "2022-11-14 12:55:49.125928+00:00",
  "user_id": "<string>"
}
For this endpoint, there are 3 error responses that you might recieve. The three error responses include: 400 Bad Request for missing or invalid fields in the request body, 409 Conflict when an index with similar properties already exists, and 500 Internal Server Error for unexpected server-side failures. Each returns a structured JSON error with a code, message, and optional details.
400 409 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the endpoint

  1. Construct your Request:
    Create a JSON object with fields like aoi_id, index_id, and src_asset_id. Make sure all fields are filled correctly as required.
  2. Send the Request:
    Include the JSON body and path parameter in the headers and make a POST request to https://api.pixxel.space/v0/aois/{aoi_id}/visualizations.
  3. Examine the Response:
    If successful, the API returns a 201 Created response with the full visualization object, including ID, expression, associated bands, and timestamps. If something is wrong (missing fields, duplicate assets, etc.), you’ll receive a structured error message with a relevant status code.