Create a new AOI

Overview

The Create a new AOI endpoint lets users create an Area of Interest by submitting a POST request with required metadata and geometry. It requires an API key and a well-structured JSON body that includes fields like name, description, geometry, project ID, and item IDs. On success, it returns a 201 Created response with full AOI details. This endpoint streamlines the process of registering spatial areas for Earth Observation analysis. Errors such as bad requests, authorization failures, or duplicate entries are handled through standard error responses.

• Method: POST

• URL: /v0/aois

• Operation: Create a new 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

The body of an API request is where you send the actual data that the server needs to perform an action. For example, when creating a new AOI, the body contains details like its name, location, description, and related IDs. Think of it like filling out a form — the body holds all the answers you're submitting. It's usually sent in JSON format and is required for actions like POST or PUT requests.

You need the following fields in Body

Here is sample of the body:

data '{
  "name": "AOI-Bangalore",
  "description": "This AOI contains images related to Bangalore",
  "satellite_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d22",
  "provider": "planetary",
  "project_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d18",
  "geometry": {
    "coordinates": [
      [
        [
          123
        ]
      ]
    ],
    "type": "<string>"
  },
  "item_ids": [
    "TD0123233",
    "TD01232344"
  ]
}'

Query Parameters

You dont really need to put query parameters for Create AOI.

Path Parameters

You dont really need to put path parameters for Create AOI.

Response

The response for the Create AOI API confirms that the AOI was successfully created. It returns a 201 Created status along with detailed information about the new AOI, including its ID, name, geometry, project details, and timestamps. This helps verify that your input was received and processed correctly.

Please refer to the table below for explaination of the fields in the response:

{
  "aoi_id": "e9767554-550e-4464-a677-b8cf096073ab",
  "name": "AOI-Bangalore",
  "description": "This AOI contains images related to Bangalore",
  "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
  ]
}

If you recieve a Bad Request error (400), Forbidden error (403), Conflict error (409) or the Internal Server Error (500), you will get the following response:

{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

How to use the endpoint

1. Construct Your request:

   Construct the body by creating a JSON object with all required fields like name, description, geometry, IDs, etc and then include it in the POST request to the endpoint.

2. Send the request

   Make the POST request to https://api.pixxel.space/v0/aois with the JSON body

3. Examine the response

   As a response, the user will see a JSON object with details of the newly created AOI, including its unique ID, name, geometry, project and satellite IDs, status, and timestamps. It confirms successful creation with a 201 Created status. If there’s an error, a structured error message will be returned.