Getting Started Authentication Unified Search Scene Details Asset Resolver Processing Data Sources SDKs

Unified Search

Unified Search API

Search across all connected satellite data providers in a single request. The search endpoint returns a STAC-compliant FeatureCollection with scenes from Sentinel-2, Landsat, and Planetary Computer.

Endpoint

GET/api/v1/search

Requires authentication via Bearer token. Queries are dispatched to all active providers in parallel with a configurable timeout.

Query Parameters

Parameter	Type	Required	Description
bbox	string	Required	Bounding box as four comma-separated coordinates: `west,south,east,north` in WGS84 (EPSG:4326). Example: `-122.5,37.5,-122.0,38.0`
datetime	string	Required	ISO 8601 date or date range. Single date: `2025-01-15`. Range: `2025-01-01/2025-02-01`. Open range: `2025-01-01/..`
collections	string	Optional	Comma-separated collection IDs to filter providers. See Data Sources for valid IDs. Example: `sentinel-2-l2a,landsat-c2-l2`. Omit to search all collections.
cloud_cover_lt	number	Optional	Maximum cloud cover percentage (0-100). Only returns scenes with `eo:cloud_cover` below this value. Default: no filter.
limit	number	Optional	Maximum number of results to return. Range: 1-100. Default: 10. Results are sorted by datetime descending (most recent first).

Example Request

cURL

terminal

curl "https:"color: #6b7280">//astraos.cloud/api/v1/search?\
  bbox=-122.5,37.5,-122.0,38.0&\
  datetime=2025-01-01/2025-02-01&\
  collections=sentinel-2-l2a&\
  cloud_cover_lt=15&\
  limit=3" \
  -H "Authorization: Bearer astra_sk_live_your_key_here"

Python

search_example.py

import requests
response = requests.get(
    "https://astraos.cloud/api/v1/search",
    params={
        "bbox": "-122.5,37.5,-122.0,38.0",
        "datetime": "2025-01-01/2025-02-01",
        "collections": "sentinel-2-l2a",
        "cloud_cover_lt": 15,
        "limit": 3,
    },
    headers={"Authorization": "Bearer astra_sk_live_your_key_here"},
)
data = response.json()
for scene in data["features"]:
    props = scene["properties"]
    print(f"{scene[&"color: #6b7280">#39;id&#39;]}  cloud={props[&#39;eo:cloud_cover&#39;]}%  {props[&#39;datetime&#39;]}")

JavaScript

search_example.js

const params = new URLSearchParams({
  bbox: "-122.5,37.5,-122.0,38.0",
  datetime: "2025-01-01/2025-02-01",
  collections: "sentinel-2-l2a",
  cloud_cover_lt: "15",
  limit: "3",
});
const res = await fetch(`https:"color: #6b7280">//astraos.cloud/api/v1/search?${params}`, {
  headers: { Authorization: "Bearer astra_sk_live_your_key_here" },
});
const data = await res.json();
data.features.forEach((scene) => {
  const { datetime, "eo:cloud_cover": cloud } = scene.properties;
  console.log(`${scene.id}  cloud=${cloud}%  ${datetime}`);
});

Response Format

The response is a STAC-compliant FeatureCollection containing an array of STAC Items, a context object, and a warnings array.

response.json

1{
2  "type": "FeatureCollection",
3  "features": [
4    {
5      "type": "Feature",
6      "stac_version": "1.0.0",
7      "id": "sentinel-2:S2B_MSIL2A_20250115T184929",
8      "geometry": {
9        "type": "Polygon",
10        "coordinates": [[[-122.5,37.5],[-122.0,37.5],[-122.0,38.0],[-122.5,38.0],[-122.5,37.5]]]
11      },
12      "bbox": [-122.5, 37.5, -122.0, 38.0],
13      "properties": {
14        "datetime": "2025-01-15T18:49:29Z",
15        "eo:cloud_cover": 8.2,
16        "platform": "sentinel-2b",
17        "constellation": "sentinel-2",
18        "gsd": 10,
19        "proj:epsg": 32610,
20        "astra:provider": "copernicus",
21        "astra:collection": "sentinel-2-l2a"
22      },
23      "assets": {
24        "B02": { "href": "https://...", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "eo:bands": [{"name": "B02", "common_name": "blue"}] },
25        "B03": { "href": "https://...", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "eo:bands": [{"name": "B03", "common_name": "green"}] },
26        "B04": { "href": "https://...", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "eo:bands": [{"name": "B04", "common_name": "red"}] },
27        "B08": { "href": "https://...", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "eo:bands": [{"name": "B08", "common_name": "nir"}] },
28        "visual": { "href": "https://...", "type": "image/tiff; application=geotiff; profile=cloud-optimized" }
29      },
30      "links": [
31        { "rel": "self", "href": "https://astraos.cloud/api/v1/scenes/sentinel-2:S2B_MSIL2A_20250115T184929" }
32      ]
33    }
34  ],
35  "context": {
36    "matched": 12,
37    "returned": 3,
38    "limit": 3
39  },
40  "warnings": []
41}

Context Object

The context field provides pagination metadata:

Field	Type	Description
matched	number	Total number of scenes matching the query across all providers
returned	number	Number of scenes returned in this response (may be less than limit)
limit	number	The limit value used for this request

Warnings Array

The warnings array contains non-fatal issues that occurred during the search. These do not prevent results from being returned, but may mean that some provider data is incomplete.

warnings_example.json

{
  "warnings": [
    {
      "provider": "planetary-computer",
      "code": "PROVIDER_TIMEOUT",
      "message": "Planetary Computer did not respond within 8s. Results may be incomplete."
    },
    {
      "provider": "copernicus",
      "code": "PARTIAL_RESULTS",
      "message": "Copernicus returned a partial result set. Retry for complete coverage."
    }
  ]
}

Code	Description
PROVIDER_TIMEOUT	An upstream provider did not respond within the timeout window. Results from that provider may be missing.
PARTIAL_RESULTS	A provider returned fewer results than expected. Pagination or retry may yield additional data.
PROVIDER_ERROR	A provider returned an error. The error is isolated and does not affect results from other providers.

← Authentication Scene Details →