TileForge

Offline map tile server - download, cache, and serve satellite map tiles for offline use.

TileForge allows you to download satellite imagery tiles from various sources (ArcGIS, Google, Esri) and serve them locally for mapping applications that need offline functionality.

Features

• Download satellite map tiles from multiple sources
• SQLite-based tile storage (portable single-file database)
• Concurrent download management with rate limiting
• In-memory LRU caching for fast tile serving
• REST API for tile serving and download management
• CLI for command-line usage
• Can be used as a library, CLI tool, or Express middleware

Installation

# Install as a dependency
npm install tileforge

# Or install globally for CLI usage
npm install -g tileforge

Quick Start

CLI Usage

# Start the tile server
tileforge serve --port 3000

# Download tiles for a region
tileforge download \
  --name "My Area" \
  --source arcgis \
  --bounds "40.74,40.76,-73.99,-73.97" \
  --zoom 16-20

# List available sources
tileforge sources

# Estimate download size
tileforge estimate --bounds "40.74,40.76,-73.99,-73.97" --zoom 16-20

# List download jobs
tileforge jobs

# Get job status
tileforge status <jobId>

Programmatic Usage

import { TileForge } from 'tileforge';

const tf = new TileForge({
  dbPath: './tiles.db',
  maxConcurrentDownloads: 4
});

// Download tiles
const job = await tf.download({
  name: 'Manhattan',
  source: 'arcgis',
  bounds: {
    north: 40.7589,
    south: 40.7014,
    east: -73.9389,
    west: -74.0259
  },
  minZoom: 16,
  maxZoom: 20
});

console.log(`Started job: ${job.jobId}`);

// Check progress
const status = tf.getJobStatus(job.jobId);
console.log(`Progress: ${status.progress}%`);

// Get a tile
const tile = tf.getTile('arcgis', 16, 1234, 5678);

// Close when done
tf.close();

Express Middleware

import express from 'express';
import { createRouter } from 'tileforge/router';

const app = express();

// Mount TileForge routes
app.use('/map', createRouter({
  dbPath: './tiles.db'
}));

app.listen(3000);

Standalone Server

import { createServer } from 'tileforge/server';

const server = createServer({
  port: 3000,
  dbPath: './tiles.db'
});

await server.start();

API Reference

TileForge Class

const tf = new TileForge(options);

Options

Option	Type	Default	Description
dbPath	string	'./data/tiles.db'	Path to SQLite database
maxConcurrentDownloads	number	4	Maximum concurrent downloads
cacheSize	number	1000	In-memory tile cache size
rateLimit	number	500	Minimum ms between requests
logLevel	string	'info'	Log level (error/warn/info/debug)

Methods

download(options)

Start downloading tiles for a geographic region.

const job = await tf.download({
  name: 'Area Name',
  source: 'arcgis',         // 'arcgis' | 'google' | 'esri-world-imagery'
  bounds: {
    north: 40.76,
    south: 40.74,
    east: -73.97,
    west: -73.99
  },
  minZoom: 16,
  maxZoom: 20
});

estimate(options)

Estimate download size and time.

const estimate = tf.estimate({
  bounds: { north, south, east, west },
  minZoom: 16,
  maxZoom: 20
});
// Returns: { tileCount, estimatedSizeMB, estimatedTimeMinutes }

extendJob(jobId, options)

Extend zoom levels for an existing job.

await tf.extendJob(jobId, { minZoom: 14, maxZoom: 20 });

getTile(source, z, x, y)

Get a cached tile.

const buffer = tf.getTile('arcgis', 16, 1234, 5678);

hasTile(source, z, x, y)

Check if a tile is cached.

const exists = tf.hasTile('arcgis', 16, 1234, 5678);

getJobStatus(jobId)

Get the status of a download job.

const status = tf.getJobStatus(jobId);
// Returns: { jobId, progress, status, downloadedTiles, totalTiles, ... }

getJobs()

Get all download jobs.

const jobs = tf.getJobs();

cancelJob(jobId)

Cancel a running download job.

tf.cancelJob(jobId);

deleteJob(jobId, deleteTiles)

Delete a job and optionally its tiles.

const result = tf.deleteJob(jobId, true);
// Returns: { deleted: true, tilesDeleted: 1234 }

getSources()

Get available tile sources.

const sources = tf.getSources();
// Returns: [{ id, name, attribution, minZoom, maxZoom }, ...]

close()

Close database connection.

tf.close();

REST API Endpoints

When running the server, the following endpoints are available:

Tiles

Method	Endpoint	Description
GET	/tiles/:source/:z/:x/:y.png	Get a cached tile
GET	/tiles/:source/count	Get tile count for source

Downloads

Method	Endpoint	Description
POST	/api/download	Start new download
GET	/api/download	List all jobs
GET	/api/download/:jobId	Get job status
DELETE	/api/download/:jobId	Delete job
PATCH	/api/download/:jobId/rename	Rename job
PATCH	/api/download/:jobId/extend	Extend zoom levels
POST	/api/download/estimate	Estimate download

Sources

Method	Endpoint	Description
GET	/api/sources	List all sources
GET	/api/sources/:sourceId	Get source details

Server

Method	Endpoint	Description
GET	/	API info
GET	/health	Health check

CLI Commands

tileforge <command> [options]

Command	Description
serve	Start the HTTP server
download	Download tiles for a region
estimate	Estimate download size
jobs	List all download jobs
status <jobId>	Get job status
cancel <jobId>	Cancel a running job
delete <jobId>	Delete a job
sources	List available sources
stats	Show database statistics

Examples

# Start server on port 3001
tileforge serve --port 3001 --db ./my-tiles.db

# Download with custom settings
tileforge download \
  --name "NYC Central Park" \
  --source google \
  --bounds "40.764,40.800,-73.981,-73.949" \
  --zoom 15-19 \
  --concurrent 8

# Estimate before downloading
tileforge estimate --bounds "40.764,40.800,-73.981,-73.949" --zoom 15-19

Available Tile Sources

ID	Name	Max Zoom
arcgis	ArcGIS World Imagery	22
google	Google Satellite	22
esri-world-imagery	Esri World Imagery (High Res)	22

Using with Map Libraries

OpenLayers

import TileLayer from 'ol/layer/Tile';
import XYZ from 'ol/source/XYZ';

const layer = new TileLayer({
  source: new XYZ({
    url: 'http://localhost:3000/tiles/arcgis/{z}/{x}/{y}.png'
  })
});

Leaflet

const layer = L.tileLayer('http://localhost:3000/tiles/arcgis/{z}/{x}/{y}.png', {
  maxZoom: 22
});

License

MIT

Legal Notice

When using tile sources, please respect their Terms of Service:

• ArcGIS/Esri: https://www.esri.com/en-us/legal/terms/full-master-agreement
• Google: https://www.google.com/intl/en_us/help/terms_maps/

This tool is intended for legitimate offline caching purposes. Please ensure your usage complies with the respective provider's terms.