## Overview

<p align="justify">
The **Search satellite images** endpoint allows you to perform a flexible search across all available satellite imagery. You can filter results by date ranges, spatial extents, collection id, and metadata such as cloud cover. This is particularly useful when you need to narrow down a large set of satellite images to a set of relevant images.

- Method: `POST`

- URL: `/v0/search`

- Operation: Retrieve a list of available satellite images and their metadata

- Authentication Required: Yes

</p>

## Authorization
<p align="justify">
You need the **api key** which you can get from the **API** tab in **Workspace Settings**. The api key is required in almost all the commands

```json
Authorization: <YOUR_API_KEY>
```
</p>
---
## Body
<p align="justify">
The **body** of an API request is where you send the actual data that the server needs to perform an action. You need the following fields in **Body :**

| Field               | Type               | Required | Description |
|---------------------|--------------------|----------|-------------|
| `collection_id`     | `string`           | Yes      | Unique identifier for the collection. |
| `satellite_id`      | `string`           | Yes      | Unique identifier for the satellite. |
| `id`                | `string`           | Yes      | Filter for cloud cover (eo:cloud_cover) |
| `min`               | `integer`          | Yes      | Minimum acceptable cloud cover. |
| `max`               | `integer`          | Yes      | Maximum acceptable cloud cover. |
| `start_date`        | `string`           | No       | Date range of satellite images. |
| `end_date`          | `string`           | No       | Date range of satellite images. |
| `coordinates`       | `array`            | No       | Geometry of the AOI. |
| `type`              | `string`           | No       | Type of the geometry (e.g. Polygon, Rectangle). |

Here is a sample of the Body:

```json body
{
  "start_date": "2023-04-18T11:56:49.865Z",
  "end_date": "2023-05-03T11:56:49.865Z",
  "satellite": {
    "collection_id": "<string>",
    "satellite_id": "<string>"
  },
  "filters": [
    {
      "id": "eo:cloud_cover",
      "min": 0,
      "max": 100
    }
  ],
  "geometry": {
    "coordinates": "<any>",
    "type": "Polygon"
  },
  "skip": 0,
  "limit": 10
}
```

</p>

## Response

<p align="justify">

### Successful Response – 200 OK

Below is the complete JSON response for searching satellite images using the **Search satellite images** endpoint. Response in `items` field varies as per `collection_id` and `satellite_id` provided.

``` json 200
{
  "items": {},
  "pagination": {
    "limit": 10,
    "skip": 0,
    "total": 100
  }
}
```

- If you recieve a **Not Found** error (**404**) or the **Internal Server Error** (**500**),  you will get the following response: 
``` json 404 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}
```
</p>
## How to Use the Endpoint

1. **Construct Your Request:**  
    Use the snippets above to build a JSON request tailored to your search needs.
2. **Send the Request:**  
    Make a POST request to `https://api.pixxel.space/v0/search` with the JSON body.
3. **Examine the Response:**  
    The API will return a FeatureCollection containing matching STAC Items, along with pagination details.