---
title: "List NASA GIBS satellite imagery layers (catalog)"
method: GET
path: "/api/v1/environment/nasa-gibs/layers"
tags: ["Environment"]
---

# List NASA GIBS satellite imagery layers (catalog)

`GET /api/v1/environment/nasa-gibs/layers`

Paginated catalog of NASA GIBS layers parsed from the upstream WMTS capabilities document (4.93 MB XML, cached 24 hours). 1236 layers are published on the default `epsg4326` projection, spanning MODIS, VIIRS, AIRS, OMI, OMPS, CERES, AMSR, SMAP, MERRA-2, TEMPO, MISR, Landsat, and more. Filter by `q` (substring against identifier and title), `format` (`image/png`, `image/jpeg`, `application/vnd.mapbox-vector-tile`), and `projection`. Sugra does NOT proxy binary tiles. Data: NASA GIBS / NASA Earthdata (US public domain).

## Query parameters

- `q` string, nullable — Substring match against layer identifier and title (case-insensitive).
- `format` string, nullable — MIME-type filter: `image/png`, `image/jpeg`, or `application/vnd.mapbox-vector-tile`.
- `projection` string — Catalog projection: `epsg4326` (global), `epsg3857` (Web Mercator), `epsg3413` (Arctic), `epsg3031` (Antarctic).
- `limit` integer — Page size (1-200).
- `offset` integer — Pagination offset (0-10000).

## Response `200`

Layer catalog listing. Data: NASA GIBS / NASA Earthdata (US public domain).

- EnvelopeNasaGibsLayersPayload
  - `data` NasaGibsLayersPayload, required — Response payload for `/layers` (layer catalog listing).
    - `projection` string, required — Projection catalog the listing was parsed from.
    - `pathway` string, required — Imagery pathway: `best` (default) / `std` / `nrt`. NASA GIBS keeps three parallel streams.
    - `q` string, nullable — Search term applied client-side against layer identifier and title.
    - `format_filter` string, nullable — MIME-type filter echoed from the `format` query parameter.
    - `total` integer, required — Total layers in the projection catalog before pagination.
    - `filtered` integer, required — Total layers matching the query before pagination.
    - `count` integer, required — Number of layers returned in this page (>= 0, <= limit).
    - `limit` integer, required — Page size echoed from the request.
    - `offset` integer, required — Pagination offset echoed from the request.
    - `layers` GibsLayerSummary[], required — Layer summaries. Data: NASA GIBS / NASA Earthdata (US public domain).
      - `identifier` string, required — Stable machine identifier for the GIBS layer (case-sensitive).
      - `title` string, required — Human-readable English title from NASA GIBS.
      - `format` string, required — Primary tile MIME type (`image/png`, `image/jpeg`, or `application/vnd.mapbox-vector-tile`).
      - `tile_matrix_set` string, nullable — Primary resolution / zoom-pyramid name (e.g. `250m`, `500m`, `1km`, `2km`).
      - `projection` string, required — Projection catalog the layer was fetched from (`epsg4326`, `epsg3857`, `epsg3413`, or `epsg3031`).
      - `bbox` number[], nullable — WGS84 bounding box `[lower_lon, lower_lat, upper_lon, upper_lat]` if upstream declares one.
      - `default_time` string, nullable — Default timestamp (YYYY-MM-DD) used when the client does not pass `time`.
      - `temporal_extent_end` string, nullable — End of the most-recent available interval for the layer (YYYY-MM-DD).
      - `has_time` boolean, required — True when the layer declares a Time dimension (93 percent of GIBS layers do).
      - `is_vector_tile` boolean, required — True when the layer serves Mapbox Vector Tiles instead of raster images.
    - `attribution` string, required — Attribution string for user-facing surfaces.
    - `proxy_note` string, required — Reminder that Sugra does not proxy binary tiles.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/d3e3d9c28132/schema)