Endpoints Factories

TiTiler's endpoints factories are helper functions that let users create a FastAPI router (fastapi.APIRouter) with a minimal set of endpoints.

Important

Most of tiler Factories are built around rio_tiler.io.BaseReader, which defines basic methods to access datasets (e.g COG or STAC). The default reader is Reader for TilerFactory and MosaicBackend for MosaicTilerFactory.

Factories classes use dependencies injection to define most of the endpoint options.

titiler.core

BaseFactory

class: titiler.core.factory.BaseFactory

Most Factories are built from this abstract based class which is used to define commons attributes and utility functions shared between all factories.

Attributes

• router: FastAPI router. Defaults to fastapi.APIRouter.
• router_prefix: Set prefix to all factory's endpoint. Defaults to "".
• route_dependencies: Additional routes dependencies to add after routes creations. Defaults to [].
• extension: TiTiler extensions to register after endpoints creations. Defaults to [].
• name: Name of the Endpoints group. Defaults to None.
• operation_prefix (private): Endpoint's operationId prefix. Defined by self.name or self.router_prefix.replace("/", ".").
• conforms_to: Set of conformance classes the Factory implement

Methods

• register_routes: Abstract method which needs to be define by each factories.
• url_for: Method to construct endpoint URL
• add_route_dependencies: Add dependencies to routes.

TilerFactory

class: titiler.core.factory.TilerFactory

Factory meant to create endpoints for single dataset using rio-tiler's Reader.

Attributes

• reader: Dataset Reader required.
• reader_dependency: Dependency to control options passed to the reader instance init. Defaults to titiler.core.dependencies.DefaultDependency
• path_dependency: Dependency to use to define the dataset url. Defaults to titiler.core.dependencies.DatasetPathParams.
• layer_dependency: Dependency to define band indexes or expression. Defaults to titiler.core.dependencies.BidxExprParams.
• dataset_dependency: Dependency to overwrite nodata value, apply rescaling and change the I/O or Warp resamplings. Defaults to titiler.core.dependencies.DatasetParams.
• tile_dependency: Dependency to define buffer and padding to apply at tile creation. Defaults to titiler.core.dependencies.TileParams.
• stats_dependency: Dependency to define options for rio-tiler's statistics method used in /statistics endpoints. Defaults to titiler.core.dependencies.StatisticsParams.
• histogram_dependency: Dependency to define numpy's histogram options used in /statistics endpoints. Defaults to titiler.core.dependencies.HistogramParams.
• img_preview_dependency: Dependency to define image size for /preview and /statistics endpoints. Defaults to titiler.core.dependencies.PreviewParams.
• img_part_dependency: Dependency to define image size for /bbox and /feature endpoints. Defaults to titiler.core.dependencies.PartFeatureParams.
• process_dependency: Dependency to control which algorithm to apply to the data. Defaults to titiler.core.algorithm.algorithms.dependency.
• colormap_dependency: Dependency to define the Colormap options. Defaults to titiler.core.dependencies.ColorMapParams
• render_dependency: Dependency to control output image rendering options. Defaults to titiler.core.dependencies.ImageRenderingParams
• environment_dependency: Dependency to define GDAL environment at runtime. Default to lambda: {}.
• supported_tms: List of available TileMatrixSets. Defaults to morecantile.tms.
• templates: Jinja2 templates to use in endpoints. Defaults to titiler.core.factory.DEFAULT_TEMPLATES.
• render_func: Image rendering method. Defaults to titiler.core.utils.render_image.
• add_preview: Add /preview endpoint to the router. Defaults to True.
• add_part: Add /bbox and /feature endpoints to the router. Defaults to True.
• add_viewer: Add /{TileMatrixSetId}/map.html endpoints to the router. Defaults to True.
• add_ogc_maps: Add /map endoint (OGC Maps API) to the router. Defaults to False.

Endpoints

from fastapi import FastAPI

from titiler.core.factory import TilerFactory

# Create FastAPI application
app = FastAPI()

# Create router and register set of endpoints
cog = TilerFactory(
    add_preview=True,
    add_part=True,
    add_viewer=True,
    add_ogc_maps=True,
)

# add router endpoint to the main application
app.include_router(cog.router)

Method	URL	Output	Description
GET	/bounds	JSON (Bounds)	return dataset's bounds
GET	/info	JSON (Info)	return dataset's basic info
GET	/info.geojson	GeoJSON (InfoGeoJSON)	return dataset's basic info as a GeoJSON feature
GET	/statistics	JSON (Statistics)	return dataset's statistics
POST	/statistics	GeoJSON (Statistics)	return dataset's statistics for a GeoJSON
GET	/tiles	JSON	List of OGC Tilesets available
GET	/tiles/{tileMatrixSetId}	JSON	OGC Tileset metadata
GET	/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]	image/bin	create a web map tile image from a dataset
GET	/{tileMatrixSetId}/map.html	HTML	return a simple map viewer Optional
GET	/{tileMatrixSetId}/tilejson.json	JSON (TileJSON)	return a Mapbox TileJSON document
GET	/{tileMatrixSetId}/WMTSCapabilities.xml	XML	return OGC WMTS Get Capabilities
GET	/point/{lon},{lat}	JSON (Point)	return pixel values from a dataset
GET	/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}	image/bin	create an image from part of a dataset Optional
POST	/feature[/{width}x{height}][.{format}]	image/bin	create an image from a GeoJSON feature Optional
GET	/preview[/{width}x{height}][.{format}]	image/bin	create a preview image from a dataset Optional
GET	/maps	image/bin	create maps from a dataset Optional

MultiBaseTilerFactory

class: titiler.core.factory.MultiBaseTilerFactory

Custom TilerFactory to be used with rio_tiler.io.MultiBaseReader type readers (e.g rio_tiler.io.STACReader).

Attributes

• reader: rio_tiler.io.base.MultiBaseReader Dataset Reader required.
• layer_dependency: Dependency to define assets or expression. Defaults to titiler.core.dependencies.AssetsBidxExprParams.
• assets_dependency: Dependency to define assets to be used. Defaults to titiler.core.dependencies.AssetsParams.

Endpoints

from fastapi import FastAPI

from rio_tiler.io import STACReader  # STACReader is a MultiBaseReader

from titiler.core.factory import MultiBaseTilerFactory

app = FastAPI()
stac = MultiBaseTilerFactory(
    reader=STACReader,
    add_preview=True,
    add_part=True,
    add_viewer=True,
    add_ogc_maps=True,
)
app.include_router(stac.router)

Method	URL	Output	Description
GET	/bounds	JSON (Bounds)	return dataset's bounds
GET	/assets	JSON	return the list of available assets
GET	/info	JSON (Info)	return assets basic info
GET	/info.geojson	GeoJSON (InfoGeoJSON)	return assets basic info as a GeoJSON feature
GET	/asset_statistics	JSON (Statistics)	return per asset statistics
GET	/statistics	JSON (Statistics)	return assets statistics (merged)
POST	/statistics	GeoJSON (Statistics)	return assets statistics for a GeoJSON (merged)
GET	/tiles	JSON	List of OGC Tilesets available
GET	/tiles/{tileMatrixSetId}	JSON	OGC Tileset metadata
GET	/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]	image/bin	create a web map tile image from assets
GET	/{tileMatrixSetId}/map.html	HTML	return a simple map viewer Optional
GET	/{tileMatrixSetId}/tilejson.json	JSON (TileJSON)	return a Mapbox TileJSON document
GET	/{tileMatrixSetId}/WMTSCapabilities.xml	XML	return OGC WMTS Get Capabilities
GET	/point/{lon},{lat}	JSON (Point)	return pixel values from assets
GET	/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}	image/bin	create an image from part of assets Optional
POST	/feature[/{width}x{height}][.{format}]	image/bin	create an image from a geojson feature intersecting assets Optional
GET	/preview[/{width}x{height}][.{format}]	image/bin	create a preview image from assets Optional
GET	/map	image/bin	create maps from a dataset Optional

MultiBandTilerFactory

class: titiler.core.factory.MultiBandTilerFactory

Custom TilerFactory to be used with rio_tiler.io.MultiBandReader type readers.

Attributes

• reader: rio_tiler.io.base.MultiBandReader Dataset Reader required.
• layer_dependency: Dependency to define assets or expression. Defaults to titiler.core.dependencies.BandsExprParams.
• bands_dependency: Dependency to define bands to be used. Defaults to titiler.core.dependencies.BandsParams.

Endpoints

from fastapi import FastAPI, Query


from rio_tiler_pds.landsat.aws import LandsatC2Reader  # LandsatC2Reader is a MultiBandReader
from titiler.core.factory import MultiBandTilerFactory


def SceneIDParams(
    sceneid: Annotated[
        str,
        Query(description="Landsat Scene ID")
    ]
) -> str:
    """Use `sceneid` in query instead of url."""
    return sceneid


app = FastAPI()
landsat = MultiBandTilerFactory(reader=LandsatC2Reader, path_dependency=SceneIDParams)
app.include_router(landsat.router)

Method	URL	Output	Description
GET	/bounds	JSON (Bounds)	return dataset's bounds
GET	/bands	JSON	return the list of available bands
GET	/info	JSON (Info)	return basic info for a dataset
GET	/info.geojson	GeoJSON (InfoGeoJSON)	return basic info for a dataset as a GeoJSON feature
GET	/statistics	JSON (Statistics)	return info and statistics for a dataset
POST	/statistics	GeoJSON (Statistics)	return info and statistics for a dataset
GET	/tiles	JSON	List of OGC Tilesets available
GET	/tiles/{tileMatrixSetId}	JSON	OGC Tileset metadata
GET	/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]	image/bin	create a web map tile image from a dataset
GET	/{tileMatrixSetId}/map.html	HTML	return a simple map viewer Optional
GET	/{tileMatrixSetId}/tilejson.json	JSON (TileJSON)	return a Mapbox TileJSON document
GET	/{tileMatrixSetId}/WMTSCapabilities.xml	XML	return OGC WMTS Get Capabilities
GET	/point/{lon},{lat}	JSON (Point)	return pixel value from a dataset
GET	/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}	image/bin	create an image from part of a dataset Optional
POST	/feature[/{width}x{height}][.{format}]	image/bin	create an image from a geojson feature Optional
GET	/preview[/{width}x{height}][.{format}]	image/bin	create a preview image from a dataset Optional
GET	/map	image/bin	create maps from a dataset Optional

TMSFactory

class: titiler.core.factory.TMSFactory

Endpoints factory for OGC TileMatrixSets.

Attributes

• supported_tms: List of available TileMatrixSets. Defaults to morecantile.tms.

from fastapi import FastAPI

from titiler.core.factory import TMSFactory

app = FastAPI()
tms = TMSFactory()
app.include_router(tms.router)

Endpoints

Method	URL	Output	Description
GET	/tileMatrixSets	JSON (TileMatrixSetList)	retrieve the list of available tiling schemes (tile matrix sets)
GET	/tileMatrixSets/{tileMatrixSetId}	JSON (TileMatrixSet)	retrieve the definition of the specified tiling scheme (tile matrix set)

AlgorithmFactory

class: titiler.core.factory.AlgorithmFactory

Endpoints factory for custom algorithms.

Attributes

• supported_algorithm: List of available Algorithm. Defaults to titiler.core.algorithm.algorithms.

from fastapi import FastAPI

from titiler.core.factory import AlgorithmFactory

app = FastAPI()
algo = AlgorithmFactory()
app.include_router(algo.router)

Endpoints

Method	URL	Output	Description
GET	/algorithms	JSON (Dict of Algorithm Metadata)	retrieve the list of available Algorithms
GET	/algorithms/{algorithmId}	JSON (Algorithm Metadata)	retrieve the metadata of the specified algorithm.

ColorMapFactory

class: titiler.core.factory.ColorMapFactory

Endpoints factory for colorMaps metadata.

Attributes

• supported_colormaps: List of available ColorMaps. Defaults to rio_tiler.colormap.cmap.

from fastapi import FastAPI

from titiler.core.factory import ColorMapFactory

app = FastAPI()
colormap = ColorMapFactory()
app.include_router(colormap.router)

Endpoints

Method	URL	Output	Description
GET	/colorMaps	JSON (colorMapList)	retrieve the list of available colorMaps
GET	/colorMaps/{colorMapId}	JSON (colorMap)	retrieve the metadata or image of the specified colorMap.

titiler.mosaic

MosaicTilerFactory

class: titiler.mosaic.factory.MosaicTilerFactory

Endpoints factory for mosaics, built on top of MosaicJSON.

Attributes

• backend: cogeo_mosaic.backends.BaseBackend Mosaic backend. Defaults to cogeo_mosaic.backend.MosaicBackend.
• backend_dependency: Dependency to control options passed to the backend instance init. Defaults to titiler.core.dependencies.DefaultDependency
• dataset_reader: Dataset Reader. Defaults to rio_tiler.io.Reader
• reader_dependency: Dependency to control options passed to the reader instance init. Defaults to titiler.core.dependencies.DefaultDependency
• path_dependency: Dependency to use to define the dataset url. Defaults to titiler.mosaic.factory.DatasetPathParams.
• assets_accessor_dependency: Dependency to define options to be forwarded to the backend get_assets method. Defaults to titiler.core.dependencies.DefaultDependency.
• layer_dependency: Dependency to define band indexes or expression. Defaults to titiler.core.dependencies.BidxExprParams.
• dataset_dependency: Dependency to overwrite nodata value, apply rescaling and change the I/O or Warp resamplings. Defaults to titiler.core.dependencies.DatasetParams.
• tile_dependency: Dependency to define buffer and padding to apply at tile creation. Defaults to titiler.core.dependencies.TileParams.
• process_dependency: Dependency to control which algorithm to apply to the data. Defaults to titiler.core.algorithm.algorithms.dependency.
• colormap_dependency: Dependency to define the Colormap options. Defaults to titiler.core.dependencies.ColorMapParams
• render_dependency: Dependency to control output image rendering options. Defaults to titiler.core.dependencies.ImageRenderingParams
• pixel_selection_dependency: Dependency to select the pixel_selection method. Defaults to titiler.mosaic.factory.PixelSelectionParams.
• environment_dependency: Dependency to define GDAL environment at runtime. Default to lambda: {}.
• supported_tms: List of available TileMatrixSets. Defaults to morecantile.tms.
• supported_tms: List of available TileMatrixSets. Defaults to morecantile.tms.
• templates: Jinja2 templates to use in endpoints. Defaults to titiler.core.factory.DEFAULT_TEMPLATES.
• optional_headers: List of OptionalHeader which endpoints could add (if implemented). Defaults to [].
• add_viewer: Add /{TileMatrixSetId}/map.html endpoints to the router. Defaults to True.

Endpoints

Method	URL	Output	Description
GET	/	JSON MosaicJSON	return a MosaicJSON document
GET	/bounds	JSON (Bounds)	return mosaic's bounds
GET	/info	JSON (Info)	return mosaic's basic info
GET	/info.geojson	GeoJSON (InfoGeoJSON)	return mosaic's basic info as a GeoJSON feature
GET	/tiles	JSON	List of OGC Tilesets available
GET	/tiles/{tileMatrixSetId}	JSON	OGC Tileset metadata
GET	/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]	image/bin	create a web map tile image from a MosaicJSON
GET	/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets	JSON	return list of assets intersecting a XYZ tile
GET	/{tileMatrixSetId}/map.html	HTML	return a simple map viewer Optional
GET	/{tileMatrixSetId}/tilejson.json	JSON (TileJSON)	return a Mapbox TileJSON document
GET	/{tileMatrixSetId}/WMTSCapabilities.xml	XML	return OGC WMTS Get Capabilities
GET	/point/{lon},{lat}	JSON (Point)	return pixel value from a MosaicJSON dataset
GET	/point/{lon},{lat}/assets	JSON	return list of assets intersecting a point
GET	/bbox/{minx},{miny},{maxx},{maxy}/assets	JSON	return list of assets intersecting a bounding box

titiler.xarray

TilerFactory

class: titiler.xarray.factory.TilerFactory

Attributes

• reader: Dataset Reader required.
• path_dependency: Dependency to use to define the dataset url. Defaults to titiler.core.dependencies.DatasetPathParams.
• reader_dependency: Dependency to control options passed to the reader instance init. Defaults to titiler.xarray.dependencies.XarrayParams
• layer_dependency: Dependency to define band indexes or expression. Defaults to titiler.core.dependencies.BidxParams.
• dataset_dependency: Dependency to overwrite nodata value and change the Warp resamplings. Defaults to titiler.xarray.dependencies.DatasetParams.
• tile_dependency: Dependency for tile creation options. Defaults to titiler.core.dependencies.DefaultDependency.
• stats_dependency: Dependency to define options for rio-tiler's statistics method used in /statistics endpoints. Defaults to titiler.core.dependencies.StatisticsParams.
• histogram_dependency: Dependency to define numpy's histogram options used in /statistics endpoints. Defaults to titiler.core.dependencies.HistogramParams.
• img_part_dependency: Dependency to define image size for /bbox and /feature endpoints. Defaults to titiler.xarray.dependencies.PartFeatureParams.
• process_dependency: Dependency to control which algorithm to apply to the data. Defaults to titiler.core.algorithm.algorithms.dependency.
• colormap_dependency: Dependency to define the Colormap options. Defaults to titiler.core.dependencies.ColorMapParams
• render_dependency: Dependency to control output image rendering options. Defaults to titiler.core.dependencies.ImageRenderingParams
• environment_dependency: Dependency to define GDAL environment at runtime. Default to lambda: {}.
• supported_tms: List of available TileMatrixSets. Defaults to morecantile.tms.
• templates: Jinja2 templates to use in endpoints. Defaults to titiler.core.factory.DEFAULT_TEMPLATES.
• add_part: Add /bbox and /feature endpoints to the router. Defaults to True.
• add_viewer: Add /{TileMatrixSetId}/map.html endpoints to the router. Defaults to True.
• add_ogc_maps: Add /map endpoints to the router. Default to False.
• add_preview: Add /preview endpoints to the router. Default to False.

from fastapi import FastAPI

from titiler.xarray.factory import TilerFactory

# Create FastAPI application
app = FastAPI()

# Create router and register set of endpoints
md = TilerFactory(
    add_part=True,     # default to True
    add_viewer=True,   # default to True
    add_preview=True,  # default to False
)

# add router endpoint to the main application
app.include_router(md.router)

Endpoints

Method	URL	Output	Description
GET	/bounds	JSON (Bounds)	return dataset's bounds
GET	/info	JSON (Info)	return dataset's basic info
GET	/info.geojson	GeoJSON (InfoGeoJSON)	return dataset's basic info as a GeoJSON feature
POST	/statistics	GeoJSON (Statistics)	return dataset's statistics for a GeoJSON
GET	/tiles	JSON	List of OGC Tilesets available
GET	/tiles/{tileMatrixSetId}	JSON	OGC Tileset metadata
GET	/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]	image/bin	create a web map tile image from a dataset
GET	/{tileMatrixSetId}/map.html	HTML	return a simple map viewer Optional
GET	/{tileMatrixSetId}/tilejson.json	JSON (TileJSON)	return a Mapbox TileJSON document
GET	/{tileMatrixSetId}/WMTSCapabilities.xml	XML	return OGC WMTS Get Capabilities
GET	/point/{lon},{lat}	JSON (Point)	return pixel values from a dataset
GET	/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}	image/bin	create an image from part of a dataset Optional
POST	/feature[/{width}x{height}][.{format}]	image/bin	create an image from a GeoJSON feature Optional
GET	/preview[/{width}x{height}][.{format}]	image/bin	create a preview image from a dataset Optional