Skip to main content

​
Overview

The List all AOIs endpoint retrieves all AOIs associated with the authenticated user. It supports filtering using optional query parameters like satellite_name, aoi_id, project_id, and date-based filters. Results are paginated using offset and limit values. A successful request returns a list of AOIs along with pagination metadata. Authentication via API key is mandatory, and errors like 404 or 500 return standard error messages with relevant codes and details.

  • Method: GET
  • URL: /v0/aois
  • Operation: Retrieve a list of all AOIs
  • 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>

​
Query Parameters

This command consists the following query parameters (optional):

  • offset integer default:0 This is the offset for pagination
  • limit integer default:10 This is the limit for pagination
  • satellite_name string You can use this to filter the AOIs by satellite name
  • created_at string You can use this to filter by the date on which the aoi was created
  • updated_at string You can use this to filter by the date on which the aoi was updated.
  • aoi_id string You can use this to filter by AOI ID
  • aoi_name string You can use this to filter by AOI name
  • project_id string You can use this to filter by project ids (comma separated)

​
Path Parameters

You dont really require any path parameters for this command.

​
Response

​
Successful Response – 200 OK

A 200 OK response from the List all AOIs endpoint indicates that the request was successful. It returns a list of AOIs created by the authenticated user, along with pagination metadata. Each AOI includes details like name, geometry, EO bands, project ID, status, and timestamps.Refer to the table below for the detailed breakdown of each field in the API response:AOI Object Fields
FieldTypeDescription
aoi_idstringUnique identifier for the AOI.
namestringName given to the AOI by the user.
descriptionstringDescription or notes about the AOI.
lens_satellite_idstringID of the satellite used to capture the EO data.
project_idstringID of the project the AOI is linked to.
imagesobjectContainer for EO images (may be empty or populated).
eo_bandsarrayList of EO bands associated with the AOI (e.g., ["B01", "B02"]).
geometryobjectGeoJSON-style object with shape of the AOI.
geometry.coordinatesarrayCoordinate arrays defining the AOI geometry.
geometry.typestringType of geometry (e.g., "Polygon" or "MultiPolygon").
progressintegerProcessing progress percentage (0–100).
statusstringCurrent status of the AOI (e.g., "success").
is_favouritebooleanIndicates if the AOI is marked as favorite.
created_atstringTimestamp when the AOI was created.
updated_atstringTimestamp of the last update to the AOI.
user_idstringID of the user who created the AOI.
area_in_sq_mfloatArea of the AOI in square meters.
centroidarrayGeographic center of the AOI [longitude, latitude].
Pagination Object Fields
FieldTypeDescription
totalintegerTotal number of AOIs available for the user.
offsetintegerStarting index of the current result page.
limitintegerMaximum number of AOIs returned in the response.
Below is the complete JSON request for listing all AOIs using the List AOI endpoint. Customize the values as needed for your search criteria:
200
{
  "aois": [
    {
      "aoi_id": "e9767554-550e-4464-a677-b8cf096073ab",
      "name": "AOI-Bangalore",
      "description": "This AOI contains images related to Bangalore",
      "lens_satellite_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d22",
      "project_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d18",
      "images": {},
      "eo_bands": [
        "B01",
        "B02",
        "B03"
      ],
      "geometry": {
        "coordinates": [
          [
            [
              123
            ]
          ]
        ],
        "type": "<string>"
      },
      "progress": 100,
      "status": "success",
      "is_favourite": false,
      "created_at": "2022-11-14 12:55:49.125928+00:00",
      "updated_at": "2022-11-14 12:55:49.125928+00:00",
      "user_id": "user-123456",
      "area_in_sq_m": 123456.78,
      "centroid": [
        77.55,
        12.95
      ]
    }
  ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 10
  }
}
  • If you recieve a Not Found error (404) or the Internal Server Error (500), you will get the following response:
404 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use endpoint

  1. Construct Your Request Add your API key to the Authorization header. You can optionally include query parameters like offset, limit, satellite_name, aoi_id, project_id, created_at, or updated_at to filter the AOIs returned.
  2. Send the Request Send the request to: https://api.pixxel.space/v0/aois. Include any query parameters directly in the URL to paginate or filter results.
  3. Examine the Response A successful response (200 OK) returns a list of AOIs you’ve created, along with pagination metadata. Each AOI object includes geometry, EO bands, project details, status, and timestamps. In case of failure (404, 500), structured error messages with code, message, and details will be returned.

⌘I