Tiles API

The Tiles API provides access to map tiles, styles, static map images, and 3D tilesets for creating custom map visualizations.

Overview

The Tiles API includes:

Map Styles - Access various pre-designed map styles
Vector Tiles - Get raw vector tile data
Static Maps - Generate static map images
Font Glyphs - Access map font resources
3D Tilesets - 3D terrain and building data

Get Styles

Retrieve a list of all available map styles.

Basic Usage

const styles = await client.tiles.getStyles();

Response Example

{
    status: "OK",
    styles: [
        {
            name: "default-light-standard",
            displayName: "Default Light Standard",
            category: "default",
            theme: "light"
        },
        {
            name: "default-dark-standard",
            displayName: "Default Dark Standard",
            category: "default",
            theme: "dark"
        },
        {
            name: "eclipse-light-standard",
            displayName: "Eclipse Light Standard",
            category: "eclipse",
            theme: "light"
        }
    ]
}

Get Style Detail

Get detailed information about a specific map style.

Basic Usage

const styleDetail = await client.tiles.getStyleDetail('default-light-standard');

Response Example

Returns the complete MapLibre GL style specification JSON:

{
    version: 8,
    name: "Default Light Standard",
    sources: {
        "olamaps": {
            type: "vector",
            tiles: [
                "https://api.olamaps.io/tiles/vector/v1/data/{z}/{x}/{y}.pbf"
            ],
            minzoom: 0,
            maxzoom: 22
        }
    },
    layers: [
        {
            id: "background",
            type: "background",
            paint: {
                "background-color": "#f8f4f0"
            }
        },
        // ... more layers
    ],
    sprite: "https://api.olamaps.io/tiles/vector/v1/sprites/default-light-standard",
    glyphs: "https://api.olamaps.io/tiles/vector/v1/fonts/{fontstack}/{range}.pbf"
}

Use Case: Custom Style Modification

async function getModifiedStyle(baseStyleName) {
    const style = await client.tiles.getStyleDetail(baseStyleName);
    
    // Modify background color
    const backgroundLayer = style.layers.find(l => l.id === 'background');
    if (backgroundLayer) {
        backgroundLayer.paint['background-color'] = '#ffffff';
    }
    
    return style;
}

Get Data TileJSON

Get TileJSON metadata for a vector tile dataset.

Basic Usage

const tileJSON = await client.tiles.getDataTileJSON('planet');

Response Example

{
    tilejson: "2.2.0",
    name: "Planet",
    description: "Global vector tile dataset",
    version: "1.0.0",
    attribution: "© Ola Maps",
    scheme: "xyz",
    tiles: [
        "https://api.olamaps.io/tiles/vector/v1/data/planet/{z}/{x}/{y}.pbf"
    ],
    minzoom: 0,
    maxzoom: 22,
    bounds: [-180, -85.0511, 180, 85.0511],
    center: [0, 0, 0]
}

Get PBF File

Download raw vector tile data in Protocol Buffer format.

Basic Usage

const pbfData = await client.tiles.getPBFFile('planet', 14, 110, 1010);

Parameters

Parameter	Type	Required	Description
`datasetName`	string	Yes	Dataset name (e.g., 'planet')
`z`	number	Yes	Zoom level (0-22)
`x`	number	Yes	Tile X coordinate
`y`	number	Yes	Tile Y coordinate

Processing PBF Data

async function processVectorTile(z, x, y) {
    const pbfData = await client.tiles.getPBFFile('planet', z, x, y);
    
    // Convert ArrayBuffer to Uint8Array
    const uint8Array = new Uint8Array(pbfData);
    
    // Use a PBF decoder library (e.g., pbf, vector-tile)
    // const tile = new VectorTile(new Protobuf(uint8Array));
    
    return uint8Array;
}

Get Font Glyphs

Access font glyph data for map label rendering.

Basic Usage

const glyphs = await client.tiles.getFontGlyphs('Noto Sans Bold', 0, 255);

Parameters

Parameter	Type	Required	Description
`fontstack`	string	Yes	Font name (e.g., 'Noto Sans Bold')
`start`	number	Yes	Starting Unicode code point
`end`	number	Yes	Ending Unicode code point

Response

Returns binary PBF data containing font glyph information for the specified Unicode range.

Static Map Images

Generate static map images for various use cases.

Get Static Map by Center

Create a static map centered on a specific location.

Basic Usage

const imageBuffer = await client.tiles.getStaticMapByCenter(
    'default-light-standard',  // style
    77.61,                       // longitude
    12.93,                       // latitude
    15,                          // zoom
    800,                         // width
    600,                         // height
    'png'                        // format
);

With Markers

const imageBuffer = await client.tiles.getStaticMapByCenter(
    'default-light-standard',
    77.61,
    12.93,
    15,
    800,
    600,
    'png',
    {
        marker: '77.61,12.93|red'  // Add red marker at location
    }
);

With Path

const imageBuffer = await client.tiles.getStaticMapByCenter(
    'default-light-standard',
    77.61,
    12.93,
    15,
    800,
    600,
    'png',
    {
        path: '77.60,12.92|77.61,12.93|77.62,12.94|blue'
    }
);

Parameters

Parameter	Type	Required	Description
`styleName`	string	Yes	Map style name
`lon`	number	Yes	Center longitude
`lat`	number	Yes	Center latitude
`zoom`	number	Yes	Zoom level (0-23)
`width`	number	Yes	Image width (1-2048 pixels)
`height`	number	Yes	Image height (1-2048 pixels)
`format`	string	Yes	Image format: `png` or `jpg`
`options.marker`	string	No	Marker specification
`options.path`	string	No	Path/polyline specification

Get Static Map by Bounding Box

Create a static map for a specific geographic area.

Basic Usage

const imageBuffer = await client.tiles.getStaticMapByBBox(
    'default-light-standard',
    {
        minx: 77.5,
        miny: 12.9,
        maxx: 77.7,
        maxy: 13.0
    },
    800,   // width
    600,   // height
    'png'  // format
);

With Markers

const imageBuffer = await client.tiles.getStaticMapByBBox(
    'default-light-standard',
    {
        minx: 77.5,
        miny: 12.9,
        maxx: 77.7,
        maxy: 13.0
    },
    800,
    600,
    'png',
    {
        marker: '77.61,12.93|green'
    }
);

Get Static Map Auto

Automatically fit markers or paths within the view.

Basic Usage

const imageBuffer = await client.tiles.getStaticMapAuto(
    'default-light-standard',
    800,   // width
    600,   // height
    'png'  // format
);

With Multiple Markers

const imageBuffer = await client.tiles.getStaticMapAuto(
    'default-light-standard',
    800,
    600,
    'png',
    {
        marker: '77.61,12.93|red|77.62,12.94|blue|77.63,12.95|green'
    }
);

3D Tileset

Get 3D terrain and building tileset data.

Basic Usage

const tileset3d = await client.tiles.get3DTileset();

Response Example

{
    asset: {
        version: "1.0"
    },
    geometricError: 24000,
    root: {
        boundingVolume: {
            region: [-Math.PI, -Math.PI/2, Math.PI, Math.PI/2, 0, 8848]
        },
        geometricError: 12000,
        refine: "ADD",
        children: [
            {
                boundingVolume: { /* ... */ },
                content: {
                    uri: "tiles/0/0/0.pbf"
                }
            }
        ]
    }
}

Real-World Examples

Generate Location Map for Website

async function generateBusinessMap(businessLocation, businessName) {
    const imageBuffer = await client.tiles.getStaticMapByCenter(
        'default-light-standard',
        businessLocation.lng,
        businessLocation.lat,
        16,  // High zoom for detail
        600,
        400,
        'png',
        {
            marker: `${businessLocation.lng},${businessLocation.lat}|red`
        }
    );
    
    // Save to file or send as response
    const base64Image = Buffer.from(imageBuffer).toString('base64');
    return `data:image/png;base64,${base64Image}`;
}

// Usage
const businessLoc = { lat: 12.9716, lng: 77.5946, name: 'My Store' };
generateBusinessMap(businessLoc)
    .then(mapImage => console.log('Map image generated'))
    .catch(console.error);

Create Delivery Route Visualization

async function createRouteMap(deliveryStops) {
    // Build path string
    const pathString = deliveryStops
        .map(stop => `${stop.lng},${stop.lat}`)
        .join('|');
    
    // Calculate center point
    const centerLat = deliveryStops.reduce((sum, s) => sum + s.lat, 0) / deliveryStops.length;
    const centerLng = deliveryStops.reduce((sum, s) => sum + s.lng, 0) / deliveryStops.length;
    
    const imageBuffer = await client.tiles.getStaticMapByCenter(
        'default-light-standard',
        centerLng,
        centerLat,
        13,
        800,
        600,
        'png',
        {
            path: `${pathString}|blue|5`,  // Blue path, 5px width
            marker: `${deliveryStops[0].lng},${deliveryStops[0].lat}|green|${deliveryStops[deliveryStops.length - 1].lng},${deliveryStops[deliveryStops.length - 1].lat}|red`
        }
    );
    
    return Buffer.from(imageBuffer);
}

// Usage
const stops = [
    { lat: 12.93, lng: 77.61 },
    { lat: 12.94, lng: 77.62 },
    { lat: 12.95, lng: 77.63 }
];

createRouteMap(stops)
    .then(routeImage => console.log('Route map created'))
    .catch(console.error);

Batch Generate Location Cards

async function generateLocationCards(locations) {
    const cards = await Promise.all(
        locations.map(async (location) => {
            try {
                const imageBuffer = await client.tiles.getStaticMapByCenter(
                    'default-light-standard',
                    location.lng,
                    location.lat,
                    14,
                    400,
                    300,
                    'png',
                    {
                        marker: `${location.lng},${location.lat}|red`
                    }
                );
                
                return {
                    name: location.name,
                    address: location.address,
                    mapImage: Buffer.from(imageBuffer),
                    success: true
                };
            } catch (error) {
                return {
                    name: location.name,
                    error: error.message,
                    success: false
                };
            }
        })
    );
    
    return cards;
}

// Usage
const locations = [
    { name: 'Office', address: 'Bangalore', lat: 12.9716, lng: 77.5946 },
    { name: 'Warehouse', address: 'Mysore', lat: 12.2958, lng: 76.6394 }
];

generateLocationCards(locations)
    .then(cards => console.log('Generated cards:', cards))
    .catch(console.error);

Compare Different Map Styles

async function compareStyles(location) {
    const styles = [
        'default-light-standard',
        'default-dark-standard',
        'eclipse-light-standard',
        'vintage-light'
    ];
    
    const images = await Promise.all(
        styles.map(async (style) => {
            const buffer = await client.tiles.getStaticMapByCenter(
                style,
                location.lng,
                location.lat,
                14,
                600,
                400,
                'png'
            );
            
            return {
                style: style,
                image: Buffer.from(buffer)
            };
        })
    );
    
    return images;
}

Map Styles Reference

Default Light Styles

default-light-lite - Minimalist light style
default-light-standard - Standard light style
default-ultra-light-standard - Ultra-light variant
default-light-full - Detailed light style

Plus language variants for Hindi, Tamil, Telugu, etc.

Default Dark Styles

default-dark-lite - Minimalist dark style
default-dark-standard - Standard dark style
default-dark-full - Detailed dark style
default-dark-standard-satellite - Dark satellite view

Eclipse Styles

eclipse-light-lite - Light eclipse theme
eclipse-light-standard - Standard eclipse
eclipse-light-full - Full eclipse details
eclipse-dark-lite - Dark eclipse variant
eclipse-dark-standard - Standard dark eclipse
eclipse-dark-full - Full dark eclipse

Bolt Styles

bolt-light - High-contrast light theme
bolt-dark - High-contrast dark theme

Vintage Styles

vintage-light - Retro light map style
vintage-dark - Retro dark map style

Earth Styles

default-earth-lite - Natural earth colors
default-earth-standard - Standard earth palette
default-earth-full - Detailed earth view

OSM Styles

positron - Light grayscale
osm-bright - Bright OpenStreetMap style
osm-basic - Basic OSM appearance
dark-matter - Dark minimalist
fiord-color - Colorful dark theme
silver-osm - Silver-toned OSM

Best Practices

1. Optimize Image Size

// ✅ Good - Appropriate size for web display
const webImage = await client.tiles.getStaticMapByCenter(
    style, lon, lat, zoom, 600, 400, 'jpg'
);

// ❌ Avoid - Unnecessarily large
const hugeImage = await client.tiles.getStaticMapByCenter(
    style, lon, lat, zoom, 2048, 2048, 'png'
);

2. Use JPEG for Photos

// Better for photos/smaller file size
const photoFormat = await client.tiles.getStaticMapByCenter(
    style, lon, lat, zoom, width, height, 'jpg'
);

// Use PNG for graphics with transparency
const transparentFormat = await client.tiles.getStaticMapByCenter(
    style, lon, lat, zoom, width, height, 'png'
);

3. Cache Static Maps

const mapCache = new Map();

async function getCachedMap(style, lon, lat, zoom, width, height) {
    const key = `${style}_${lon}_${lat}_${zoom}_${width}x${height}`;
    
    if (mapCache.has(key)) {
        return mapCache.get(key);
    }
    
    const imageBuffer = await client.tiles.getStaticMapByCenter(
        style, lon, lat, zoom, width, height, 'jpg'
    );
    
    mapCache.set(key, imageBuffer);
    
    // Cache for 1 hour
    setTimeout(() => mapCache.delete(key), 3600000);
    
    return imageBuffer;
}

4. Validate Parameters

function validateStaticMapParams(width, height, zoom) {
    if (width < 1 || width > 2048) {
        throw new Error('Width must be between 1 and 2048');
    }
    if (height < 1 || height > 2048) {
        throw new Error('Height must be between 1 and 2048');
    }
    if (zoom < 0 || zoom > 23) {
        throw new Error('Zoom must be between 0 and 23');
    }
}

Limitations

Image Dimensions: Maximum 2048 × 2048 pixels
Zoom Levels: 0-23 (depending on location)
Rate Limits: Subject to your API plan
PBF Tiles: Requires client-side decoding

Next Steps

Learn about Map Display for interactive maps
Explore Examples for more visualization use cases
Check out MapLibre GL integration

Tiles API

On this page