Create Visualization

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 :

Here is a sample of the Body:

{
  "index_id": "<string>",
  "src_asset_ids": [
    "<string>",
    "<string>"
  ]
}

Path Parameters

This endpoint require aoi_id as the only path parameter.

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:

Here is a sample 201 response:

{
  "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.

{
  "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.