Intro

TiTiler.PgSTAC is a TiTiler extension, which create dynamic tiler connected to PgSTAC databases.

By default the main application (titiler.pgstac.main.app) provides two sets of endpoints:

/mosaic/{searchid}: Dynamic mosaic tiler based on STAC Search Queries
/collections/{collection_id}/items/{item_id}: Dynamic tiler for single STAC item (stored in PgSTAC)

Mosaic¶

The goal of the mosaic endpoints is to use any search query to create tiles. titiler-pgstac provides a set of endpoint to register and list the search queries.

Register a `Search` request¶

Important

In TiTiler.PgSTAC a STAC Search Query is equivalent to a Mosaic.

Before being able to create Map Tiles, the user needs to register a Search Query within the PgSTAC database (in the searches table). By default, TiTiler.PgSTAC has a /mosaic/register (POST) endpoint which will:

validate the search query (based on the STAC API specification item-search)
send the search query to the postgres database using the search_query PgSTAC function
return a searchid (might be also called mosaicid).

Example

curl -X 'POST' 'http://127.0.0.1:8081/mosaic/register' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"collections":["landsat-c2l2-sr"], "bbox":[-123.75,34.30714385628804,-118.125,38.82259097617712], "filter-lang": "cql-json"}' | jq

>> {
  "searchid": "5a1b82d38d53a5d200273cbada886bd7",
  "links": [
    {
      "rel": "metadata",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/5a1b82d38d53a5d200273cbada886bd7/info"
    },
    {
      "rel": "tilejson",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/5a1b82d38d53a5d200273cbada886bd7/tilejson.json"
    }
  ]
}

# Or using CQL-2
curl -X 'POST' 'http://127.0.0.1:8081/mosaic/register' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"filter": {"op": "and", "args": [{"op": "=", "args": [{"property": "collection"}, "landsat-c2l2-sr"]}, {"op": "s_intersects", "args": [{"property": "geometry"}, {"coordinates": [[[-123.75, 34.30714385628804], [-123.75, 38.82259097617712], [-118.125, 38.82259097617712], [-118.125, 34.30714385628804], [-123.75, 34.30714385628804]]], "type": "Polygon"}]}]}}' | jq

>> {
  "searchid": "5063721f06957d6b2320326d82e90d1e",
  "links": [
    {
      "rel": "metadata",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/5063721f06957d6b2320326d82e90d1e/info"
    },
    {
      "rel": "tilejson",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/5063721f06957d6b2320326d82e90d1e/tilejson.json"
    }
  ]
}

Mosaic metadata¶

curl http://127.0.0.1:8081/mosaic/5063721f06957d6b2320326d82e90d1e/info | jq

>> {
  "search": {
    "hash": "5063721f06957d6b2320326d82e90d1e",  # <-- this is the search/mosaic ID
    "search": {  # <-- Summary of the search request
      "filter": {  # <-- this is CQL2 filter associated with the search
        "op": "and",
        "args": [
          {
            "op": "=",
            "args": [
              {
                "property": "collection"
              },
              "landsat-c2l2-sr"
            ]
          },
          {
            "op": "s_intersects",
            "args": [
              {
                "property": "geometry"
              },
              {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -123.75,
                      34.30714385628804
                    ],
                    [
                      -123.75,
                      38.82259097617712
                    ],
                    [
                      -118.125,
                      38.82259097617712
                    ],
                    [
                      -118.125,
                      34.30714385628804
                    ],
                    [
                      -123.75,
                      34.30714385628804
                    ]
                  ]
                ]
              }
            ]
          }
        ]
      }
    },
    "_where": "(  ( (collection_id = 'landsat-c2l2-sr') and st_intersects(geometry, '0103000020E610000001000000050000000000000000F05EC055F6687D502741400000000000F05EC02D553EA94A6943400000000000885DC02D553EA94A6943400000000000885DC055F6687D502741400000000000F05EC055F6687D50274140'::geometry) )  )  ",  # <-- internal pgstac WHERE expression
    "orderby": "datetime DESC, id DESC",
    "lastused": "2022-03-03T11:44:55.878504+00:00",  # <-- internal pgstac variable
    "usecount": 2,  # <-- internal pgstac variable
    "metadata": {  # <-- titiler-pgstac Mosaic Metadata
      "type": "mosaic"  # <-- where using the `/mosaic/register` endpoint, titiler-pgstac will add `type=mosaic` to the metadata
    }
  },
  "links": [
    {
      "rel": "self",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/5063721f06957d6b2320326d82e90d1e/info"
    },
    {
      "rel": "tilejson",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/5063721f06957d6b2320326d82e90d1e/tilejson.json"
    }
  ]
}

Note: In addition to the search query, a user can pass metadata, which will be saved in the postgres table.

curl -X 'POST' 'http://127.0.0.1:8081/mosaic/register' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"collections":["landsat-c2l2-sr"], "bbox":[-123.75,34.30714385628804,-118.125,38.82259097617712], "filter-lang": "cql-json", "metadata": {"minzoom": 8, "maxzoom": 13, "assets": ["B04", "B03", "B02"], "defaults": {"true_color": {"assets": ["B04", "B03", "B02"], "color_formula": "Gamma RGB 3.5 Saturation 1.7 Sigmoidal RGB 15 0.35"}}}}' | jq

>> {
  "searchid": "f31d7de8a5ddfa3a80b9a9dd06378db1",
  "links": [
    {
      "rel": "metadata",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/f31d7de8a5ddfa3a80b9a9dd06378db1/info"
    },
    {
      "rel": "tilejson",
      "type": "application/json",
      "href": "http://127.0.0.1:8081/mosaic/f31d7de8a5ddfa3a80b9a9dd06378db1/tilejson.json"
    }
  ]
}

curl http://127.0.0.1:8081/mosaic/f31d7de8a5ddfa3a80b9a9dd06378db1/info | jq '.search.metadata'
>> {
  "type": "mosaic",
  "minzoom": 8,
  "maxzoom": 13,
  "assets": [
    "B04",
    "B03",
    "B02"
  ],
  "defaults": {
    "true_color": {
      "assets": [
        "B04",
        "B03",
        "B02"
      ],
      "color_formula": "Gamma RGB 3.5 Saturation 1.7 Sigmoidal RGB 15 0.35"
    }
  }
}

Fetch mosaic `Tiles`¶

When we have a searchid we can now call the dynamic tiler and ask for Map Tiles.

How it works

On each Tile request, the tiler api is going to call the PgSTAC geometrysearch function with the searchid and the Tile geometry to get the list of STAC items (code). Then based on the assets parameter, the tiler will construct the tile image (code).

Important

Because Tiles will be created from STAC items we HAVE TO pass assets={stac asset} option to the tile endpoint.

See full list of options

Example

curl 'http://127.0.0.1:8081/mosaic/f1ed59f0a6ad91ed80ae79b7b52bc707/tiles/8/40/102.png?assets=B01&rescale=0,16000 > 8-40-102.png

Items¶

Set of endpoints created using TiTiler's MultiBaseTilerFactory but with item and collection path parameter (instead of the url= query parameter).

example

curl http://127.0.0.1:8081/collections/landsat-c2l2-sr/items/LC08_L1TP_028004_20171002_20171018_01_A1

See full list of endpoints