Get Started

What is Tiler?

Tiler helps you to quickly set up a tile server for your GeoTIFFs. It can be easily integrated as a component in GIS workflows, providing the tiling services needed for frontend applications, web mapping solutions and other geospatial projects.

TIP

Soon, the Examples section will provide practical examples on how to use Tiler with various mapping libraries and frameworks, such as NextJS and React Leaflet.

INFO

Tiler is built on top of the excellent rio-tiler package. ❤️

Installation

Recommended: Docker

Since Tiler is meant to be run as a service, the recommended way is to set it up using Docker. This allows you to run Tiler in a containerized environment, making it easy to deploy and manage.

Ensure you have Docker installed on your machine. You can follow the official Docker installation guide for your operating system.

Clone the Repository

First, clone the repository:

git clone https://github.com/JakobKlotz/tiler-api.git
cd tiler-api

Build and Run Tiler

Next, build and run the Docker container with a single command:

docker compose up -d --build

That's it. Tiler is now up and running! You can access the API at http://localhost:8001. 🎉

Alternative: For Development and Customization

If you prefer not to use Docker, you can install Tiler using the Python package manager uv. This approach is recommended if you want to tinker with the code or extend Tiler's functionality.

Install uv

To install uv, follow the instructions for your operating system from the uv documentation.

Clone the Repository

git clone https://github.com/JakobKlotz/tiler-api.git
cd tiler-api

Install Dependencies

To install the required dependencies, run:

uv sync

Run Tiler

Finally, start the Tiler server:

uv run uvicorn main:app

API Documentation

You can find the API documentation at http://localhost:8001/docs. This documentation provides information about the available endpoints, request parameters, and response formats. Within the API documentation, you can also test the endpoints directly.

An alternative documentation is available at http://localhost:8001/redoc.

First Usage

To use Tiler, you can send HTTP requests to the API endpoints. Here is a first example using the GeoTIFF (data/sample.tif) provided in the repository. Following request returns a list of available tiles for the given file.

curl -X 'GET' \
  'http://localhost:8001/list?tif=data%2Fsample.tif' \
  -H 'accept: application/json'

NOTE

The tif parameter is a local file path. URL encoding is necessary to ensure that the path is correctly interpreted by the server.

The request results in the following response:

[
  {
    "x": 8712,
    "y": 5756,
    "z": 14
  },
  {
    "x": 8713,
    "y": 5756,
    "z": 14
  },
  {
    "x": 8712,
    "y": 5757,
    "z": 14
  },
  {
    "x": 8713,
    "y": 5757,
    "z": 14
  }
]

For this specific GeoTIFF, we have four tiles available at the minimum zoom level of 14. You can use the x, y, and z values to request the actual tile images. More information on the usage of the API can be found in Usage.