Getting Started with TiTiler: A Beginner's Tutorial

Anvita Shrivastava
15 minutes ago
4 min read

Geographical information continues to grow at an explosive rate and become increasingly complex; therefore, a growing issue has arisen: how to serve raster datasets efficiently over the web. Traditional GIS servers need to build out their infrastructure, configure and obtain enough storage space for raster images, and streamline image data pre-processing workflows before images can be visualized within web applications.

TiTiler, or Tile Server for Cloud Optimized GeoTIFFs or MrSID, provides a cloud-native, lightweight, on-demand, and scalable solution for generating map tiles dynamically from COGs, MrSID, and other raster sources. TiTiler is built with current programming technologies in Python and allows developers to create scalable geospatial APIs without needing to maintain large tile cache servers or complex GIS infrastructure.

What Is TiTiler?

TiTiler is an open-source dynamic tile server built by the geospatial community on:

FastAPI
Rio-Tiler
Rasterio
GDAL

TiTiler has a REST API that allows for the dynamic serving of:

XYZ map tiles
Web Mercator raster images
Raster statistics
Metadata
TileJSON
WMTS-compliant endpoints

Unlike conventional tile servers that require pre-generated tiles, TiTiler will generate tiles on an as-needed basis directly from Cloud Optimized GeoTIFF images.

This architecture provides major improvements in the following areas:

Reducing storage space
Streamlining tile generation workflows
Reducing infrastructure costs
Eliminating duplication of data

Why Use TiTiler?

Dynamic Tile Generation

Without using a tile cache, TiTiler builds and serves tiles on the fly from source image data.

Advantages

Speedy deployment
Lower storage cost
Easy updating
Simplified workflow
Cloud Native Architecture

Cloud-Native Architecture

TiTiler is designed to work with cloud object storage services such as:

Amazon S3
Google Cloud Storage
Azure Blob Storage

Raster data can reside in cloud storage while TiTiler accesses only the necessary file portions.

Cloud Optimized GeoTIFF Support

TiTiler utilizes Cloud Optimized GeoTIFF (COT) technology to perform efficient HTTP range requests.

The advantages of this include:

Less bandwidth usage
Faster tile render time
Greater ability to scale
Enhanced user experience
Flexible API Endpoints

Through simple REST requests, developers can access:

Tile information
Statistics
Histograms
Bounding box information
Metadata
Pixel value information

MrSID Support

TiTiler can access MrSID imagery through GDAL-supported environments, enabling organizations to leverage existing MrSID datasets while transitioning to modern cloud-native geospatial workflows.

TiTiler Architecture Overview

A standard TiTiler installation has four (4) levels:

Data level

Holds raster data in:

Cloud Optimized GeoTIFFs
STAC Assets
GeoTIFFs
Mosaic Datasets

Processing Level

Rio-Tiler reads raster data and performs:

Windowed Reads
Reprojection
Band Selection
Color Mapping

API Level

FastAPI exposes several endpoints as follows:

/tilejson.json
/tiles/{z}/{x}/{y}
/statistics
/info
/point

Client Level

Applications can access imagery using:

Leaflet
OpenLayers
MapLibre GL JS
Cesium
ArcGIS JavaScript SDK

Prerequisites

To install TiTiler, you must have:

Python 3.10 or later
Pip Package Manager Installed
Docker (optional)
Basic understanding of GIS concepts
Familiarity with RESTful API's

Validate Installation:

python --version

pip --version

Installing TiTiler

Method 1: Install via pip

Create a virtual environment:

python -m venv venv

Activate it:

Windows

venv\Scripts\activate

macOS/Linux

source venv/bin/activate

Install TiTiler:

pip install titiler.application

Verify installation:

python -m titiler.application.main

Running TiTiler Locally

Launch the development server:

uvicorn titiler.application.main: app --reload

By default:

http://localhost:8000

API documentation becomes available at:

http://localhost:8000/docs

The Swagger UI provides an interactive interface for testing endpoints.

Exploring Core API Endpoints

Metadata Endpoint

Retrieve dataset metadata:

GET /cog/info

Example:

http://localhost:8000/cog/info?url=https://example.com/image.tif

Response includes:

CRS
Width
Height
Band information
Bounds

Statistics Endpoint

Get raster statistics:

GET /cog/statistics

Example output:

{
  "min": 0,
  "max": 255,
  "mean": 122.4,
  "std": 35.7
}

Useful for:

Image analysis
Visualization tuning
Data quality checks

Point Query Endpoint

Query pixel values at coordinates:

GET /cog/point/{lon},{lat}

Example:

/cog/point/-122.42,37.77

Response:

{
  "values": [128]
}

Tile Endpoint

Generate map tiles dynamically:

GET /cog/tiles/{z}/{x}/{y}

Example:

/cog/tiles/10/163/395.png

The endpoint returns a PNG tile ready for mapping applications.

Visualizing TiTiler Data with Leaflet

Create a simple web map:

<!DOCTYPE html>
<html>
<head>
  <link rel=" stylesheet."
  href="https://unpkg.com/leaflet/dist/leaflet.css">
</head>
<body>

<div id="map" style="height:100vh;"></div>

<script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>

<script>
var map = L.map('map').setView([37.77,-122.42],10);

L.tileLayer(
'http://localhost:8000/cog/tiles/{z}/{x}/{y}.png?url=https://example.com/image.tif',
{
  maxZoom: 18
}
).addTo(map);

</script>

</body>
</html>

This example streams tiles directly from TiTiler into Leaflet.

Working with Cloud Optimized GeoTIFFs

COGs are fundamental to TiTiler's performance.

Characteristics include:

Internal tiling
Multi-resolution overviews
HTTP range request support
Efficient cloud access

Create a COG using GDAL:

gdal_translate input.tif output_cog.tif \
-of COG

Validate:

gdalinfo output_cog.tif

Using properly optimized COGs dramatically improves rendering speed.

Deploying TiTiler with Docker

Pull the official image:

docker pull ghcr.io/developmentseed/titiler

Run a container:

docker run -p 8000:8000 \
ghcr.io/developmentseed/titiler

Access:

http://localhost:8000/docs

Docker simplifies deployment across:

AWS
Azure
Google Cloud
Kubernetes
On-premises environments

TiTiler has rapidly ascended to being an essential component of today's geospatial ecosystem. Thanks to the convergence of FastAPI, Rio-Tiler, and Cloud Optimized GeoTIFFs into a single tool, developers can now serve raster images to users more efficiently, without having to rely on traditional tile-generation pipelines.

When creating satellite imagery portals, environmental monitoring systems, agricultural dashboards, or cloud-native GIS applications, TiTiler provides the perfect scalable and developer-friendly platform to deliver high-performance geospatial services.

When you begin with a local deployment of TiTiler, become familiar with the core APIs and follow the best practices for Cloud Optimized GeoTIFFs, you will be set up for success when building production-ready geospatial applications using TiTiler.

For more information or any questions regarding the LizardTech suite of products, please don't hesitate to contact us at:

Email: info@geowgs84.com

USA (HQ): (720) 702–4849

LizardTech.com

(A GeoWGS84 Corp Company)

https://www.lizardtech.com

https://www.geowgs84.com

Get LizardTech GeoExpress — Start Optimizing Your Imagery

What Is TiTiler?

Why Use TiTiler?

Dynamic Tile Generation

Cloud-Native Architecture

Cloud Optimized GeoTIFF Support

MrSID Support

TiTiler Architecture Overview

Data level

Processing Level

API Level

Client Level

Prerequisites

Installing TiTiler

Method 1: Install via pip

Windows

macOS/Linux

Running TiTiler Locally

Exploring Core API Endpoints

Metadata Endpoint

Statistics Endpoint

Point Query Endpoint

Tile Endpoint

Visualizing TiTiler Data with Leaflet

Working with Cloud Optimized GeoTIFFs

Deploying TiTiler with Docker