STAC

06 Dec 2023
5 Minutes to read

Print
Share
Dark
Light
PDF

STAC

Updated on 06 Dec 2023
5 Minutes to read

Print
Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

SpatioTemporal Asset Catalog (STAC)

The SpatioTemporal Asset Catalog (STAC) is an open source specification that evolved from different organizations coming together to increase the interoperability of searching for satellite imagery.

It provides a common language to describe a range of geospatial information, so it can more easily be indexed and discovered. A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and time.

STAC Specification

For STAC specification and general usage, please refer to this published standard:
https://stacspec.org/STAC-api.html

In /search endpoint, intersects is not implemented yet.
In /collections/{collectionId}/items endpoint, datetime does not support searching on a specific date

MetroMap STAC API

This document aims to describe the usage of the MetroMap STAC API and only work as a supplement for the STAC API standard document (please refer to: STAC API (stacspec.org) (https://stacspec.org/STAC-api.html).

MetroMap Stac Capabilities

Landing Page

/stac/{api_key}
Returns a JSON object that indicates all available paths

Example

https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b

Response:

{
  "type": "Catalog",
  "id": "metromap-stac",
  "stac_version": "1.0.0",
  "description": "Metromap imagery catalog",
  "links": [
    {
      "rel": "root",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b",
      "type": "application/json",
      "title": "Metromap STAC"
    },
    {
      "rel": "self",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b",
      "type": "application/json"
    },
    {
      "rel": "service-desc",
      "href": "https://api.metromap.com.au",
      "title": "MM API Service description"
    },
    {
      "rel": "service-doc",
      "href": "https://api.metromap.com.au/docs",
      "title": "MM API documents"
    },
    {
      "rel": "conformances",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/conformances",
      "title": "OGC API conformance classes implemented by this server"
    },
    {
      "rel": "data",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections",
      "title": "Information about the feature collections"
    },
    {
      "rel": "search123",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/search",
      "title": "Search the catalog",
      "method": "POST"
    }
  ],
  "stac_extensions": [],
  "title": "Metromap STAC"
}

STAC Conformance

/stac/{api_key}/conformances
Returns standards that this API endpoint complies with

Example

https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/conformances

Response:

{
    "conformsTo": [
        "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
        "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
        "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html",
        "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
    ]
}

STAC Collections

/stac/{api_key}/collections
Returns a JSON object with a list of avaliable collections catagorized by states

Example

https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections

Response:

{
  "links": [
    {
      "rel": "root",
      "type": "application/json",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b"
    },
    {
      "rel": "self",
      "type": "application/json",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections"
    }
  ],
  "collections": [
    {
      "type": "Collection",
      "id": "WA",
      "stac_version": "1.0.0",
      "description": "Metromap imagery layers for WA",
      "links": [
        {
          "rel": "root",
          "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections",
          "type": "application/json",
          "title": "Metromap STAC"
        },
        {
          "rel": "self",
          "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA",
          "type": "application/json"
        }
      ],
      "stac_extensions": [],
      "title": "WA",
      "extent": {
        "spatial": {
          "bbox": [
            [
              113.6024649559999,
              -35.108343849006694,
              128.305571713999,
              -17.68590233599982
            ]
          ]
        },
        "temporal": {
          "interval": [
            [
              "2015-10-08T00:00:00Z",
              "2022-04-07T23:59:59.999999Z"
            ]
          ]
        }
      },
      "license": "proprietary"
    },
    ...... 
  ]
}

STAC Collection

/stac/{api_key}/collections/{collection_id}
Returns a JSON object with one collection and collection_id indicates a state in Australia (shown in the collections response as id)

Example

https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections

Response:

{
  "type": "Collection",
  "id": "WA",
  "stac_version": "1.0.0",
  "description": "Metromap imagery layers for WA",
  "links": [
    {
      "rel": "root",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections",
      "type": "application/json",
      "title": "Metromap STAC"
    },
    {
      "rel": "self",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA",
      "type": "application/json"
    }
  ],
  "stac_extensions": [],
  "title": "WA",
  "extent": {
    "spatial": {
      "bbox": [
        [
          113.6024649559999,
          -35.108343849006694,
          128.305571713999,
          -17.68590233599982
        ]
      ]
    },
    "temporal": {
      "interval": [
        [
          "2015-10-08T00:00:00Z",
          "2022-04-07T23:59:59.999999Z"
        ]
      ]
    }
  },
  "license": "proprietary"
}

MetroMap Stac Data

Collection Items

/stac/{api_key}/collections/{collection_id}/items?bbox={BBOX}&datetime={datetime_range}&bbox-crs={BBOX-CRS}&offset={offset}&limit={limit}

Parameter	Note	Example
{api_key}	User’s access	ca3cb673073c406087a43670d615160b
{collection_id}	collection_id indicates a state in Australia (shown in the collections response as id
{BBOX}	4 coordinates joined by comma (',') with this order: xmax, ymax, xmin, ymin	115.80267254482251,-32.03978539483905,115.88480289082395,-31.973911680278654
{datetime_range}	1. two dates join with a slash	1. 2020-1-1/2022-1-1
{datetime_range}	2. if only input one date, it assumes this date is the end date	2. 2020-1-1
{datetime_range}	3. Open intervals are accepted with .. before/after the slash	3. 2018-02-12/...or ../2018-03-18
{BBOX-CRS}	the bounding box CRS, currently it only support 4326	epsg:4326
{offset}	The number of results to skip forward of the search	0
{limit}	The amount of results for your search	10

(star(*) indicates the parameter is mandatory)

Example
http://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA/items?bbox=115.80267254482251,-32.03978539483905,115.88480289082395,-31.973911680278654&bbox-crs=epsg:4326&offset=0&limit=10&datetime=2020-1-1/2022-1-1
Response:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "stac_version": "1.0.0",
            "id": "2448",
            "properties": {
                "title": "WA Perth Centre CIR 2021-11-24",
                "layername": "Perth_2021_39_GM_CIR",
                "datetime": "2021-11-24T00:00:00Z"
            },
            "geometry": {
                "type": "MultiPolygon",
                "coordinates": [...]
            },
            "links": [
                {
                    "rel": "collection",
                    "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA",
                    "type": "application/json",
                    "title": "WA"
                }
            ],
            "assets": {
                "xyz": {
                    "href": "https://api-v3.metromap.com.au/tiles/xyz/2448/{z}/{y}/{x}?key={API-KEY}",
                    "title": "WA Perth Centre CIR 2021-11-24 XYZ tiles",
                    "eo:bands": [
                        {
                            "name": "band1",
                            "common_name": "nir"
                        },
                        {
                            "name": "band2",
                            "common_name": "red"
                        },
                        {
                            "name": "band3",
                            "common_name": "green"
                        }
                    ]
                }
            },
            "bbox": [
                115.721903045,
                -32.142877407,
                115.9790781,
                -31.845267598
            ],
            "stac_extensions": [],
            "collection": "WA"
        },
        ... ...
    ],
    "timeStamp": "2022-06-03T05:57:57.734380",
    "numberMatched": 19,
    "links": [
        {
            "rel": "next",
            "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA/items?datetime=2020-1-1%2F2022-1-1&offset=1&limit=1&bbox=115.80267254482251%2C-32.03978539483905%2C115.88480289082395%2C-31.973911680278654",
            "title": "Next page"
        }
    ]
}

Fetch Single Item in a Collection

http://api-v3.metromap.com.au/stac/{api_key}/collections/{collection_id }/items/{feature_id}

Parameter	Note	Example
api_key	User’s access	`ca3cb673073c406087a43670d615160b`
collection_id	states in Australia	`WA`
feature_id	layer id	`2448`

Example

http://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA/items/2448

Response:

{
  "type": "Feature",
  "stac_version": "1.0.0",
  "id": "2448",
  "properties": {
    "title": "WA Perth Centre CIR 2021-11-24",
    "layername": "Perth_2021_39_GM_CIR",
    "datetime": "2021-11-24T00:00:00Z"
  },
  "geometry": { 
      ... ...
  },
  "links": [
    {
      "rel": "collection",
      "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA",
      "type": "application/json",
      "title": "WA"
    }
  ],
  "assets": {
    "xyz": {
      "href": "https://api-v3.metromap.com.au/tiles/xyz/2448/{z}/{y}/{x}?key={API-KEY}",
      "title": "WA Perth Centre CIR 2021-11-24 XYZ tiles",
      "eo:bands": [
        {
          "name": "band1",
          "common_name": "nir"
        },
        {
          "name": "band2",
          "common_name": "red"
        },
        {
          "name": "band3",
          "common_name": "green"
        }
      ]
    },
    "COG": {
      "href": "WA/2021/M0125_Perth_Centre_60mm_RGBI_UCEM2f210_MGA2020z50_24-Nov-2021_b4125/M0125_Perth_Centre_60mm_RGBI_UCEM2f210_MGA2020z50_24-Nov-2021_b4125.tif",
      "title": "WA Perth Centre CIR 2021-11-24 COG path"
    }
  },
  "bbox": [
    115.721903045,
    -32.142877407,
    115.9790781,
    -31.845267598
  ],
  "stac_extensions": [],
  "collection": "WA"
}

MetroMap Stac Search

Perform a search on the STAC collections and items

/stac/{api_key}/search?bbox={BBOX}&datetime={datetime}&ids={ids}&collections={collections}&offset={offset}&limit={limit}

Parameter	Note	Example
{api_key}	User’s access	ca3cb673073c406087a43670d615160b
BBOX	4 coordinates joined by comma (',') with this order: xmax, ymax, xmin, ymin	115.80267254482251,-32.03978539483905,115.88480289082395,-31.973911680278654
datetime	1. two dates join with a slash 2. if only input one date, it asssumes this date is the end date 3. Open intervals are accepted with .. before/after the slash	1. 2020-1-1/2022-1-1 2. 2020-1-1 3. 2018-02-12/.. or ../2018-03-18
ids	layer ids joined by comma ,	295,294
collections	states joined by comma ,	WA,NT
offset	The number of results to skip forward of the search	0
limit	The amount of results for your search	10

Example

http://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/search?bbox=115.80267254482251,-32.03978539483905,115.88480289082395,-31.973911680278654&datetime=2020-1-1/2022-1-1&ids=2448&collections=WA,SA&offset=0&limit=10

Response:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "stac_version": "1.0.0",
      "id": "2448",
      "properties": {
        "title": "WA Perth Centre CIR 2021-11-24",
        "layername": "Perth_2021_39_GM_CIR",
        "datetime": "2021-11-24T00:00:00Z"
      },
      "geometry": {
        ... ...
      },
      "links": [
        {
          "rel": "collection",
          "href": "https://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/collections/WA",
          "type": "application/json",
          "title": "WA"
        }
      ],
      "assets": {
        "xyz": {
          "href": "https://api-v3.metromap.com.au/tiles/xyz/2448/{z}/{y}/{x}?key={API-KEY}",
          "title": "WA Perth Centre CIR 2021-11-24 XYZ tiles",
          "eo:bands": [
            {
              "name": "band1",
              "common_name": "nir"
            },
            {
              "name": "band2",
              "common_name": "red"
            },
            {
              "name": "band3",
              "common_name": "green"
            }
          ]
        },
        "COG": {
          "href": "WA/2021/M0125_Perth_Centre_60mm_RGBI_UCEM2f210_MGA2020z50_24-Nov-2021_b4125/M0125_Perth_Centre_60mm_RGBI_UCEM2f210_MGA2020z50_24-Nov-2021_b4125.tif",
          "title": "WA Perth Centre CIR 2021-11-24 COG path"
        }
      },
      "bbox": [
        115.721903045,
        -32.142877407,
        115.9790781,
        -31.845267598
      ],
      "stac_extensions": [],
      "collection": "WA"
    }
  ],
  "timeStamp": "2022-06-06T06:04:13.188587",
  "numberMatched": 1,
  "links": []
}

Search STAC items with full-featured filtering

/stac/{api_key}/search

Request body:

{
  "bbox": [
    0
  ],
  "datetime": [
    "string"
  ],
  "ids": [
    "string"
  ],
  "collections": [
    "string"
  ],
  "offset": 0,
  "limit": 10
}

Example
Path:

http://api-v3.metromap.com.au/stac/ca3cb673073c406087a43670d615160b/search

Request body:

 {
  "bbox": [
    115.80267254482251,-32.03978539483905,115.88480289082395,-31.973911680278654
  ],
  "datetime": [
    "2020-1-1","2022-1-1"
  ],
  "ids": [
    "2448"
  ],
  "collections": [
    "WA"
  ],
  "offset": 0,
  "limit": 10
}

What's Next

Table of contents

SpatioTemporal Asset Catalog (STAC)