Archive Search

In this guide, we’ll walk you through how to use our Search All Items endpoint to query archived imagery. This endpoint lets you filter and retrieve STAC items 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 All Items endpoint allows you to perform a flexible search across all archived imagery. You can filter results by date ranges, spatial extents, and metadata such as cloud cover or platform type. This is particularly useful when you need to narrow down a large archive to a set of relevant items.

• Endpoint: POST /v0/archives/search
• Method: POST
• Content-Type: application/json
• Authentication: Include your API key in the header as:

  Authorization: Bearer <YOUR_API_KEY>
  

​

Step-by-Step Breakdown of the Search Request

​

1. Define the Date Range

Specify the time period during which the imagery was captured.

• Field: datetime
• Format: ISO8601 date range, e.g., "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"

Snippet:

{
"datetime": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
}

​

2. Select the Collection

Filter your search to a specific collection by its ID.
This is useful if you know you want to query items from a particular dataset/collection you are interested in(e.g., pixxel-td-l2a).

• Field: collections
• Format: An array of collection IDs.

Snippet

{
  "collections": ["pixxel-td-l2a"]
}

​

3. Set Spatial Filters

There are two ways to define the spatial extent of your search:

​

a. Using GeoJSON (intersects)

Limit the search to imagery that intersects with a specified Area of Interest (AOI).

• Field: intersects
• Format: A GeoJSON geometry (typically a Polygon)

Snippet:

{
  "intersects": {
    "type": "Polygon",
    "coordinates": [
      [
        [<LONGITUDE_1>, <LATITUDE_1>],
        [<LONGITUDE_2>, <LATITUDE_2>],
        [<LONGITUDE_3>, <LATITUDE_3>],
        [<LONGITUDE_4>, <LATITUDE_4>],
        [<LONGITUDE_1>, <LATITUDE_1>]
      ]
    ]
  }
}

​

b. Using a Bounding Box (bbox)

Alternatively, you can define a bounding box to constrain the spatial search.

• Field: bbox
• Format: An array of four numbers: [minLongitude, minLatitude, maxLongitude, maxLatitude]

Snippet

{
  "bbox": [<MIN_LONGITUDE>, <MIN_LATITUDE>, <MAX_LONGITUDE>, <MAX_LATITUDE>]
}

Note: You can use either intersects or bbox based on your preference. They serve similar purposes but offer different levels of precision.

​

4. Apply Additional Attribute Filters

Narrow down the results based on specific metadata, such as cloud cover or platform.

• Field: query
• Format: JSON object containing field-specific filters.
• Example Filters:
  • cloud_cover: Items with cloud cover less than a certain percentage.
  • platform: Items captured by a specific satellite.

Snippet:

{
  "query": {
    "cloud_cover": { "lt": 20 },
    "platform": "Satellite-X"
  }
}

​

5. Sorting the Results

Order the search results based on one or more fields (e.g., datetime, cloud_cover).

• Field: sortby
• Format: An array of sort objects. Each sort object should have:
  • field: The field to sort by.
  • direction: Either "asc" (ascending) or "desc" (descending).

Snippet

{
  "sortby": [
    { "field": "datetime", "direction": "asc" }
  ]
}

​

6. Control Pagination

Manage the number of results returned and navigate through large result sets.

• Fields:
  • limit: Maximum number of items to return (e.g., 10).
  • offset: Number of items to skip (e.g., 0 for the first page).

Snippet:

{
  "limit": 10,
  "offset": 0
}

​

Putting It All Together

Below is the complete JSON request for searching archived imagery using the “Search All Items” endpoint. Customize the values as needed for your search criteria.

{
  "datetime": "2021-07-01/2021-07-31",
  "collections": ["pixxel-td2-l2a"],
  "intersects": {
    "type": "Polygon",
    "coordinates": [
      [
        [<LONGITUDE_1>, <LATITUDE_1>],
        [<LONGITUDE_2>, <LATITUDE_2>],
        [<LONGITUDE_3>, <LATITUDE_3>],
        [<LONGITUDE_4>, <LATITUDE_4>],
        [<LONGITUDE_1>, <LATITUDE_1>]
      ]
    ]
  },
  "bbox": [<MIN_LONGITUDE>, <MIN_LATITUDE>, <MAX_LONGITUDE>, <MAX_LATITUDE>],
  "query": {
    "cloud_cover": { "lt": 20 },
    "platform": "Satellite-X"
  },
  "sortby": [
    { "field": "datetime", "direction": "asc" }
  ],
  "limit": 10,
  "offset": 0
}

​

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/archives/search with the JSON body.
3. Examine the Response:
   The API will return a FeatureCollection containing matching STAC Items, along with pagination details.