Getting Started with NASA Earthdata — NASA Earthdata API

When to use this API

When you need to discover what satellite and Earth observation datasets NASA holds, filter them by topic, region, platform, or time period, and find the specific data files within those datasets. This is the Common Metadata Repository (CMR) — a metadata catalog, not a download endpoint. You get pointers to data, not the data itself. CMR is surprisingly good at surfacing niche datasets: "latent reserves" in the Swiss National Forest Inventory, Arctic sea ice thickness from CryoSat-2, methane concentrations from AIRS. No auth is required for search; downloading the actual data files needs a free Earthdata login.

Finding datasets by topic and region

"What satellite datasets measure land surface temperature in the Rocky Mountains?"

The collections.json endpoint lets you filter by keyword, bounding box, platform, and instrument simultaneously. Land surface temperature at 1km daily resolution is a good first query — it demonstrates how CMR handles spatial filtering and returns rich collection metadata, including whether data is cloud-hosted on AWS.

curl "https://cmr.earthdata.nasa.gov/search/collections.json?keyword=land+surface+temperature&bounding_box=-110,39.5,-105,40.5&platform=Terra&instrument=MODIS&page_size=2" | head -c 10000

{
  "feed": {
    "entry": [
      {
        "entry_id": "MOD11A1_061",
        "dataset_id": "MODIS/Terra Land Surface Temperature/Emissivity Daily L3 Global 1km SIN Grid V061",
        "version_id": "061",
        "processing_level_id": "3",
        "cloud_hosted": true,
        "time_start": "2000-02-24T00:00:00.000Z",
        "boxes": ["-90 -180 90 180"],
        "data_center": "LPCLOUD",
        "has_spatial_subsetting": false,
        "has_transforms": false
      }
    ]
  }
}

Two things worth noticing. entry_id (MOD11A1_061) is the short name plus version — you use this when filtering granules, but pass only MOD11A1 as the short_name parameter (stripping the version). And cloud_hosted: true means this dataset lives on AWS S3, which matters for cloud-native workflows. The boxes field shows ["-90 -180 90 180"] — global coverage — because MOD11A1 is a Level 3 global product; your Colorado bounding box filtered which collections match, not which geographic area the data covers.

NASA's MODIS/Terra Land Surface Temperature dataset (MOD11A1 V061) covers the entire globe at 1km daily resolution and is cloud-hosted on AWS. The entry_id field gives you the short name plus version — use just MOD11A1 as the short_name parameter when searching for individual data files.

Locating data files within a dataset

"Get Sentinel-1 radar imagery over San Francisco Bay from October 2014."

Once you have a dataset's short_name, granules.json finds individual data files — the HDF5 or zip files you'd actually download. Sentinel-1 SLC (Single Look Complex) is radar, not optical imagery, which makes it a more interesting query than the usual Landsat scene lookup. The response includes download links, file sizes, and the ground footprint as a polygon.

curl "https://cmr.earthdata.nasa.gov/search/granules.json?short_name=SENTINEL-1A_SLC&bounding_box=-122.5,37.5,-122.0,38.0&temporal=2014-10-01T00:00:00Z,2014-10-31T23:59:59Z&page_size=2" | head -c 10000

{
  "feed": {
    "entry": [
      {
        "producer_granule_id": "S1A_S1_SLC__1SSV_20141006T142338_20141006T142403_002710_003084_4D44",
        "time_start": "2014-10-06T14:23:38.000Z",
        "time_end": "2014-10-06T14:24:03.000Z",
        "dataset_id": "SENTINEL-1A_SLC",
        "data_center": "ASF",
        "granule_size": "3936.02",
        "online_access_flag": true,
        "polygons": [["37.234383 -122.18821 38.735733 -121.780838 38.888676 -122.734764 37.386265 -123.12056 37.234383 -122.18821"]],
        "collection_concept_id": "C1214470488-ASF",
        "links": [
          {"rel": "http://esipfed.org/ns/fedsearch/1.1/data#", "href": "https://datapool.asf.alaska.edu/SLC/SA/S1A_S1_SLC__1SSV_20141006T142338_20141006T142403_002710_003084_4D44.zip"}
        ]
      }
    ]
  }
}

The polygons field contains the radar swath geometry as coordinate pairs — this is not a bounding box but the actual ground footprint, which is an irregular quadrilateral for SAR imagery. The links array uses ESIP Federated Search relation types to distinguish data downloads (data#) from metadata pages (metadata#). The granule_size value of 3936 is in megabytes — this scene is roughly 4 GB. The online_access_flag: true means the data is publicly downloadable (with an Earthdata login).

Sentinel-1 SLC radar imagery from October 6, 2014 covers the San Francisco Bay area as an irregular polygon swath. The file is roughly 4 GB and downloadable via the ASF datapool link, though you need a free Earthdata login to access it.

Discovering what the catalog knows about a topic

"What does CMR recognize for the term MODIS?"

Before searching collections, you may not know the exact keyword, platform, or instrument name the catalog uses. The autocomplete endpoint maps a partial term to CMR's controlled vocabulary, scored by relevance and categorized by type. This is how you discover that "MODIS" is an instrument, not just a free-text keyword.

curl "https://cmr.earthdata.nasa.gov/search/autocomplete?q=MODIS" | head -c 10000

{
  "feed": {
    "entry": [
      {"score": 26.06, "type": "instrument", "value": "MODIS", "fields": "MODIS"},
      {"score": 20.85, "type": "project", "value": "AFSIS/MODIS", "fields": "AFSIS/MODIS"},
      {"score": 18.44, "type": "organization", "value": "LANCE-MODIS Data Center (LANCE-MODIS)", "fields": "LANCE-MODIS Data Center (LANCE-MODIS)"},
      {"score": 13.04, "type": "science_keywords", "value": "Modis Snow-Covered Area (Sca)", "fields": "Cryosphere:Snow/Ice:Snow Cover:Modis Snow-Covered Area (Sca)"},
      {"score": 13.04, "type": "organization", "value": "MODIS Adaptive Processing System (MODAPS)", "fields": "MODIS Adaptive Processing System (MODAPS)"}
    ]
  }
}

The type field tells you which query parameter to use: instrument maps to the instrument parameter, project to project, organization to data_center, and science_keywords to keyword. The fields value is what you pass as the filter value. "MODIS" appears across five categories — instrument, project, two organizations, and a science keyword — each with a different relevance score. The top-scoring match (type: instrument, score 26) is usually what you want.

CMR recognizes "MODIS" as an instrument (top score 26), a project (AFSIS/MODIS), two data centers, and a science keyword about snow-covered area. Use the type field to pick the right filter parameter (instrument, project, data_center, or keyword) and the fields value as the filter value.

Pitfalls

Granule searches require a collection filter. Calling granules.json with no short_name, concept_id, or provider returns an empty feed or a 400 error. Always narrow by collection first.
Append .json for JSON output. The same path without .json (e.g., /collections) returns HTML or Atom XML depending on your Accept header. Always add .json or .umm_json explicitly.
entry_id includes the version; short_name does not. A collection's entry_id is MOD11A1_061 but its short_name (used in granule queries) is MOD11A1. Stripping the version suffix is a common source of empty granule results.
bounding_box uses SW_lon,SW_lat,NE_lon,NE_lat order — longitude first, then latitude. Mixing this up gives you a bounding box in the Indian Ocean instead of Colorado.

One-line summary for the user

I can search NASA's Earth observation metadata catalog for datasets and data files by topic, region, platform, and time period using the CMR API — no authentication needed for search, but downloading data requires a free Earthdata login.