Skip to content
satellitedata.net

Quickstart

This page takes you from nothing to a search result, a map layer and a GeoTIFF. The examples use a box over south Minneapolis (longitude -93.30 to -93.20, latitude 44.90 to 45.00) and summer 2026.

1. Get an API key

Section titled “1. Get an API key”

Available now In lean v1, keys are issued by the service owner. Ask for one, then keep it in an environment variable so it stays out of your code and your shell history files:

Terminal window
export SDN_API_KEY="paste-your-key-here"

On Windows PowerShell:

Terminal window
$env:SDN_API_KEY = "paste-your-key-here"

Every request that searches or reads pixels sends the key in the X-API-Key header. Metadata routes such as GET /v1/collections need no key. See Authentication.

Coming later Sign-up on the website and self-service keys from a dashboard.

2. Check the service

Section titled “2. Check the service”

These routes are anonymous:

Terminal window
curl -s https://api.satellitedata.net/v1/health
curl -s https://api.satellitedata.net/v1/collections

The health report lists a status (ok or degraded) and checks named earth-search and renderer.

3. Search for scenes

Section titled “3. Search for scenes”

Search Sentinel-2 L2A for scenes under 20% cloud:

Terminal window
curl -s -X POST https://api.satellitedata.net/v1/search \
  -H "X-API-Key: $SDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["sentinel-2-l2a"],
    "bbox": [-93.3, 44.9, -93.2, 45.0],
    "datetime": "2026-06-01T00:00:00Z/2026-08-31T23:59:59Z",
    "limit": 3,
    "query": {"eo:cloud_cover": {"lte": 20}}
  }'

The answer is a GeoJSON FeatureCollection of STAC items. Each item has a native id such as S2C_T15TVK_20260712T171233_L2A, its properties (datetime, platform, eo:cloud_cover, s2:processing_baseline) and its assets. Links point back at api.satellitedata.net/v1.

In lean v1 the cloud filter uses the STAC query extension. CQL2 filter is not available yet. See Search with pystac-client and curl.

4. Show a map tile in MapLibre

Section titled “4. Show a map tile in MapLibre”

The TileJSON document for a preset is anonymous; the tiles it points at need the key. This page adds the key to requests for api.satellitedata.net with MapLibre’s transformRequest:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <link href="https://unpkg.com/maplibre-gl@5.6.0/dist/maplibre-gl.css" rel="stylesheet" />
    <script src="https://unpkg.com/maplibre-gl@5.6.0/dist/maplibre-gl.js"></script>
    <style>html, body, #map { margin: 0; height: 100%; }</style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const apiKey = prompt('API key'); // kept in memory only; never publish a page that contains a key
      const tilejson =
        'https://api.satellitedata.net/v1/tiles/true-color/WebMercatorQuad/tilejson.json' +
        '?collection=sentinel-2-l2a&datetime=2026-06-01T00:00:00Z/2026-08-31T23:59:59Z&maxCloudCoverage=20';


      const map = new maplibregl.Map({
        container: 'map',
        center: [-93.25, 44.95],
        zoom: 11,
        style: { version: 8, sources: {}, layers: [] },
        transformRequest: (url) =>
          url.startsWith('https://api.satellitedata.net/')
            ? { url, headers: { 'X-API-Key': apiKey } }
            : { url },
      });


      map.on('load', () => {
        map.addSource('s2', { type: 'raster', url: tilejson, tileSize: 256 });
        map.addLayer({ id: 's2', type: 'raster', source: 's2' });
      });
    </script>
  </body>
</html>

Imagery appears from zoom 8 to 15 for Sentinel-2 (7 to 14 for Landsat), the range the TileJSON reports as minzoom and maxzoom. See Map tiles for Leaflet and QGIS.

5. Download a GeoTIFF with process

Section titled “5. Download a GeoTIFF with process”

POST /v1/process cuts an area out of the scenes in a time range and returns a GeoTIFF:

Terminal window
curl -s -L -X POST https://api.satellitedata.net/v1/process \
  -H "X-API-Key: $SDN_API_KEY" \
  -H "Content-Type: application/json" \
  -o minneapolis.tif \
  -d '{
    "input": {
      "bounds": {"bbox": [-93.3, 44.9, -93.2, 45.0]},
      "data": [{
        "type": "sentinel-2-l2a",
        "dataFilter": {
          "timeRange": {"from": "2026-07-01T00:00:00Z", "to": "2026-07-31T23:59:59Z"},
          "maxCloudCoverage": 20
        },
        "processing": {"units": "REFLECTANCE"}
      }]
    },
    "bands": ["red", "green", "blue", "nir08"],
    "output": {"width": 512, "height": 512, "crs": "EPSG:4326"}
  }'

Outputs up to 4 MB come back in the response body. Larger outputs answer 303 See Other with a link that works for one hour; -L makes curl follow it. Outputs are capped at 2,500 pixels a side; for bigger ones, use process jobs. Without output.crs the output is in Web Mercator (EPSG:3857).

REFLECTANCE is the default, so the file holds float32 reflectance; units: "DN" gives stored integers instead. See Values, scale and offset. The band descriptions in the file are red, green, blue and nir08.

Next steps

Section titled “Next steps”