# Satellite Imagery Scene Finder (STAC): Sentinel-2, Landsat (`datamule/stac-catalog-extractor`) Actor

Find satellite scenes for an area and date range from public STAC catalogs such as Earth Search. Filter by bounding box, dates, collection and cloud cover; get one row per scene with date, cloud %, platform, footprint and asset download links. Pay per scene row.

- **URL**: https://apify.com/datamule/stac-catalog-extractor.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools
- **Features:** Limited permissions
- **Stats:** 4 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Satellite Imagery Scene Finder (STAC): Sentinel-2, Landsat

Find satellite scenes for your area and dates. Give it a bounding box, a date range, a
collection such as Sentinel-2 L2A, and a cloud-cover limit. You get one dataset row per matching
scene with its capture time, cloud %, platform, footprint and links to the scene's files
(thumbnail, true-colour image, individual bands, metadata).

It returns scene **metadata and links**. It does not download or process the imagery itself;
open the asset links in your GIS tool or fetch them yourself. Coverage depends on the catalog you
point it at: it works with public STAC APIs such as Element84 Earth Search, and results are only
as complete as that catalog.

### For AI agents and MCP clients

**Tool description:** Agent tool: find satellite scenes (Sentinel-2, Landsat) for a bounding box and date range from a STAC catalog; one row per scene with date, cloud %, footprint and asset links.

**Output fields (dataset rows):** `_stacRoot`, `_mode`, `id`, `collection`, `title`, `description`, `datetime`, `start_datetime`, `end_datetime`, `platform`, `constellation`, `instruments`, `gsd`, `cloudCover`, `epsg`, `license`, `keywords`, `bbox`, `extentSpatial`, `extentTemporal`, `providers`, `geometryType`, `geometry`, `assetKeys`, `assetCount`, `assets`, `stacVersion`, `stacExtensions`, `properties`, `links`, `itemsUrl`, `searchUrl`, `raw`

**Use cases:**

- Let an AI agent check recent cloud-free imagery over a site: 25 scenes cost about $0.0125.
- Monitor an area of interest for new scenes and hand asset download links to an MCP client or pipeline.
- Pre-filter imagery for ML jobs by cloud cover and platform before paying for downloads.

**Pay-per-event price table (USD; platform compute billed separately by Apify):**

| Event | Charged per | FREE plan | DIAMOND plan |
|---|---|---|---|
| item | Item | $0.0005 | $0.00025 |

Set `maxTotalChargeUsd` on the run to cap spend.

### Quick start: find scenes over an area

This is the exact input of a successful cloud run on the current build (Sentinel-2 over the San
Francisco Bay Area, June 2024, Element84 Earth Search, no account or key needed):

```json
{"stacRoot":"https://earth-search.aws.element84.com/v1","collections":["sentinel-2-l2a"],"bbox":[-122.6,37.6,-122.2,37.9],"datetime":"2024-06-01T00:00:00Z/2024-06-30T23:59:59Z","filterLang":"cql2-json","listCollectionsOnly":false,"limit":100,"maxResults":25}
```

That run returned 24 scene rows (24 `item` events). The first three rows, trimmed to the main
columns (`cloudCover` rounded to 2 decimals):

| id | datetime | cloudCover | platform | assetCount |
|---|---|---|---|---|
| S2B_10SEG_20240630_0_L2A | 2024-06-30T19:14:08.129000Z | 1.27 | sentinel-2b | 35 |
| S2B_10SEH_20240630_0_L2A | 2024-06-30T19:13:54.881000Z | 0.99 | sentinel-2b | 35 |
| S2B_10SEG_20240627_0_L2A | 2024-06-27T19:04:13.374000Z | 3.22 | sentinel-2b | 35 |

Each row's `assets` object holds the file links. For the first row:

- `assets.thumbnail.href`: https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/10/S/EG/2024/6/S2B_10SEG_20240630_0_L2A/thumbnail.jpg
- `assets.visual.href` (true-colour GeoTIFF): https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/10/S/EG/2024/6/S2B_10SEG_20240630_0_L2A/TCI.tif

To use your own search, change these fields:

- **Area**: `bbox` as `[west, south, east, north]` in degrees, or `intersects` with a GeoJSON geometry.
- **Dates**: `datetime`, e.g. `2025-01-01T00:00:00Z/2025-03-31T23:59:59Z`.
- **Collection**: `collections`, e.g. `sentinel-2-l2a` on Earth Search.
- **Cloud cover**: `query` such as `{ "eo:cloud_cover": { "lt": 20 } }` (the run above did not use it).
- **Cost cap**: `maxResults`; each scene row is one billable `item`.

Not sure which collection ids a catalog has? Run once with `"listCollectionsOnly": true` and
the same `stacRoot`; you get one row per collection, then put the id you want in `collections`.

### What it does

- **Search items** — set the STAC root + one or more collections and any of a **bounding box**,
  **date/time window**, **property query** (e.g. cloud cover), item **ids**, or a GeoJSON
  **intersects** geometry, and it pulls every matching STAC Item, auto-following the
  `rel="next"` pagination link up to your **Max results**. Handles both STAC pagination styles:
  a POST `/search` body token *and* a GET `/search` next href.
- **Discover collections** — turn on **List collections only** (or leave the search filters empty) and it reads `{stacRoot}/collections` and returns one row per collection: id, title,
  license, spatial + temporal extent, and a ready-to-use search URL.
- **Normalized + raw** — each Item's well-known properties are promoted to stable columns
  (`id`, `collection`, `datetime`, `cloudCover`, `platform`, `gsd`, `geometryType`, …) while the
  full `properties`, `geometry`, `assets` and the untouched Feature (`raw`) are all preserved, so
  nothing is lost even though every catalog exposes different metadata.

### More example inputs

These variants are illustrative and were not part of the verified run above.

Recent low-cloud Sentinel-2 scenes over the San Francisco Bay Area (Element84 Earth Search, no auth):

```json
{ "stacRoot": "https://earth-search.aws.element84.com/v1", "collections": ["sentinel-2-l2a"], "bbox": [-122.6, 37.6, -122.2, 37.9], "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z", "query": { "eo:cloud_cover": { "lt": 20 } }, "maxResults": 200 }
```

The same search against Microsoft Planetary Computer — just change the root:

```json
{ "stacRoot": "https://planetarycomputer.microsoft.com/api/stac/v1", "collections": ["sentinel-2-l2a"], "bbox": [-122.6, 37.6, -122.2, 37.9], "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z", "maxResults": 100 }
```

Landsat over a point of interest, newest first (USGS):

```json
{ "stacRoot": "https://landsatlook.usgs.gov/stac-server", "collections": ["landsat-c2l2-sr"], "intersects": { "type": "Point", "coordinates": [-122.4, 37.8] }, "sortby": "-properties.datetime", "maxResults": 50 }
```

Discover what a catalog exposes:

```json
{ "stacRoot": "https://earth-search.aws.element84.com/v1", "listCollectionsOnly": true }
```

### Input reference

- `stacRoot` **(required)** — the STAC API root (not `/search` or `/collections`).
- `collections` — collection id(s) to search.
- `bbox` — `[west, south, east, north]` in WGS84 degrees (a 6-number 3D box is also accepted).
- `datetime` — RFC 3339 instant or range; open ranges with `..` (`2024-01-01T00:00:00Z/..`).
- `query` — STAC *query* extension filters, e.g. `{ "eo:cloud_cover": { "lt": 20 } }`.
- `filter` / `filterLang` — CQL2 *filter* extension (for servers that advertise it).
- `intersects` — a GeoJSON geometry, as an alternative to `bbox`.
- `ids` — fetch specific Item id(s) directly.
- `sortby` — e.g. `-properties.datetime` (server must support the *sort* class).
- `limit` — server-side page size (the actor paginates regardless).
- `maxResults` — total item cap across all pages (default 1000).

### Authentication

**None required** for the public catalogs (Earth Search, Planetary Computer, USGS, Digital
Earth). For gated deployments supply a **Bearer token** and/or **Extra request headers** — both
optional, never required, and the token is never logged.

### Output

One dataset item per STAC Item, with normalized columns plus:

- `_stacRoot` / `_mode` — the source catalog and whether the row is an `item` or a `collection`.
- `geometry` — the item footprint (GeoJSON), `assets` — the downloadable asset map (COGs,
  thumbnails, metadata), and `properties` — the full STAC property bag.
- `raw` — the complete, untouched STAC Feature.

A search that matches nothing returns **0 items, not an error**.

### Pricing

**Pay per item** — you're charged one `item` event per record returned (one per collection in
discovery mode). A search that matches nothing costs nothing.

### Notes

- Speaks STAC API 1.0.0 item-search; handles POST and GET `/search`, and both next-link
  pagination styles (POST body token, GET href token).
- Not affiliated with or endorsed by the OGC, Element84, AWS, Microsoft, the USGS, or any target
  catalog. Respect each provider's terms and any per-asset licensing.

# Actor input Schema

## `stacRoot` (type: `string`):

The root URL of ANY STAC API (SpatioTemporal Asset Catalog). Examples: https://earth-search.aws.element84.com/v1 (Element84 / AWS open data), https://planetarycomputer.microsoft.com/api/stac/v1 (Microsoft Planetary Computer), https://landsatlook.usgs.gov/stac-server (USGS). Do NOT include /search or /collections — just the API root.

## `collections` (type: `array`):

Collection id(s) to search, e.g. sentinel-2-l2a, landsat-c2-l2, sentinel-1-grd. Leave EMPTY together with the other search filters to run in discovery mode (list every collection the catalog exposes). Turn on "List collections only" below to just browse what's available first.

## `listCollectionsOnly` (type: `boolean`):

When on, the actor only reads {stacRoot}/collections and returns one row per available collection (id, title, license, spatial/temporal extent, search URL) — it does NOT search any items. Use this to discover what a catalog exposes, then set Collections + a bbox/datetime to extract items.

## `bbox` (type: `array`):

Spatial filter as \[west, south, east, north] in WGS84 decimal degrees (a 6-number \[w,s,minZ,e,n,maxZ] 3D box is also accepted). Example for the San Francisco Bay Area: \[-122.6, 37.6, -122.2, 37.9]. Leave empty for no spatial filter.

## `datetime` (type: `string`):

Temporal filter in RFC 3339. A single instant (2024-06-15T00:00:00Z), a closed range (2024-06-01T00:00:00Z/2024-06-30T23:59:59Z), or an open range using ".." (2024-06-01T00:00:00Z/.. or ../2024-06-30T00:00:00Z). Leave empty for no time filter.

## `ids` (type: `array`):

Fetch specific STAC Item id(s) directly (e.g. S2B_10SEG_20240627_0_L2A). When set, this narrows the search to exactly these items. Leave empty to search by the filters above.

## `query` (type: `object`):

Property filters using the STAC `query` extension, as a JSON object of {property: {op: value}}. Example to keep only low-cloud scenes: {"eo:cloud_cover": {"lt": 20}}. Supported ops depend on the server (eq, neq, lt, lte, gt, gte, in, startsWith …). Leave empty for none.

## `filter` (type: `object`):

Advanced filter using the STAC `filter` extension in CQL2-JSON, as a JSON object. Example: {"op":"<","args":\[{"property":"eo:cloud_cover"},20]}. Only supported on servers that advertise the filter conformance class; use the simpler Property query above when unsure. Leave empty for none.

## `filterLang` (type: `string`):

Language for the CQL2 filter above. Usually cql2-json (the default). Only change if the target server requires cql2-text.

## `intersects` (type: `object`):

Spatial filter as a GeoJSON geometry object (Point, Polygon, etc.) — an alternative to the bounding box for non-rectangular areas of interest. Example: {"type":"Point","coordinates":\[-122.4,37.8]}. Leave empty to use the bbox instead.

## `sortby` (type: `string`):

Sort order (STAC `sort` extension), e.g. -properties.datetime for newest first, or +properties.eo:cloud_cover for least-cloudy first. Only honored by servers that advertise the sort conformance class. Leave empty for the server default order.

## `limit` (type: `integer`):

Server-side page size requested per /search call (the actor auto-follows the rel="next" link regardless). Most servers cap this around 100–1000. Leave at the default unless you have a reason to change it.

## `maxResults` (type: `integer`):

Maximum total number of items to pull across all pages (the actor auto-paginates until this cap or the result set is exhausted). Each returned item is one billable event. Default 25.

## `bearerToken` (type: `string`):

Optional OAuth2 bearer token for gated STAC deployments. Sent as Authorization: Bearer \*\*\*. NOT required for public catalogs (Earth Search, Planetary Computer, USGS) — leave empty. Never logged.

## `extraHeaders` (type: `object`):

Optional extra HTTP headers to send with every request, as a JSON object, e.g. {"Ocp-Apim-Subscription-Key": "..."} for a gated deployment. Leave empty for public catalogs.

## Actor input object example

```json
{
  "stacRoot": "https://earth-search.aws.element84.com/v1",
  "collections": [
    "sentinel-2-l2a"
  ],
  "listCollectionsOnly": false,
  "bbox": [
    -122.6,
    37.6,
    -122.2,
    37.9
  ],
  "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z",
  "filterLang": "cql2-json",
  "limit": 100,
  "maxResults": 25
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "stacRoot": "https://earth-search.aws.element84.com/v1",
    "collections": [
        "sentinel-2-l2a"
    ],
    "bbox": [
        -122.6,
        37.6,
        -122.2,
        37.9
    ],
    "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z",
    "limit": 100,
    "maxResults": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/stac-catalog-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "stacRoot": "https://earth-search.aws.element84.com/v1",
    "collections": ["sentinel-2-l2a"],
    "bbox": [
        -122.6,
        37.6,
        -122.2,
        37.9,
    ],
    "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z",
    "limit": 100,
    "maxResults": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("datamule/stac-catalog-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "stacRoot": "https://earth-search.aws.element84.com/v1",
  "collections": [
    "sentinel-2-l2a"
  ],
  "bbox": [
    -122.6,
    37.6,
    -122.2,
    37.9
  ],
  "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z",
  "limit": 100,
  "maxResults": 25
}' |
apify call datamule/stac-catalog-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datamule/stac-catalog-extractor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/GkdPgr6BrUGPfm8c0/builds/SQ0DSfZ0uR8v5EhB8/openapi.json