Skip to main content
Here we’ll walk you through how to use our Search satellite images endpoint to query all available satellite imagery. This endpoint lets you filter and retrieve satellite images based on various criteria, helping you find the exact imagery you need. We’ll break down the JSON request into steps, explain each parameter, and provide sample snippets for clarity.

​
Overview

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

​
Authorization

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

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. You need the following fields in Body :

FieldTypeRequiredDescription
collection_idstringYesUnique identifier for the collection.
satellite_idstringYesUnique identifier for the satellite.
idstringYesFilter for cloud cover (eo:cloud_cover)
minintegerYesMinimum acceptable cloud cover.
maxintegerYesMaximum acceptable cloud cover.
start_datestringNoDate range of satellite images.
end_datestringNoDate range of satellite images.
coordinatesarrayNoGeometry of the AOI.
typestringNoType of the geometry (e.g. Polygon, Rectangle).
Here is a sample of the Body:
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
}

​
Response

​
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.
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:
404 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
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.