---
title: "OverscaledTileID | JavaScript maps SDK"
description: "Documentation for MapTiler SDK"
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Class OverscaledTileID

An overscaled tile identifier

##### Index

### Constructors[](#constructors)

[constructor](#constructor)

### Properties[](#properties)

[canonical](#canonical) [key](#key) [overscaledZ](#overscaledz) [terrainRttPosMatrix32f](#terrainrttposmatrix32f) [wrap](#wrap)

### Methods[](#methods)

[calculateScaledKey](#calculatescaledkey) [children](#children) [clone](#clone) [equals](#equals) [getTilePoint](#gettilepoint) [isChildOf](#ischildof) [isLessThan](#islessthan) [isOverscaled](#isoverscaled) [normalizeCoordinates](#normalizecoordinates) [overscaleFactor](#overscalefactor) [scaledTo](#scaledto) [toString](#tostring) [toUnwrapped](#tounwrapped) [unwrapTo](#unwrapto) [wrapped](#wrapped)

## Constructors[](#constructors-1)

### constructor[](#constructor)

-   new OverscaledTileID(  
        overscaledZ: number,  
        wrap: number,  
        z: number,  
        x: number,  
        y: number,  
    ): OverscaledTileID[](#constructoroverscaledtileid)
    
    #### Parameters
    
    -   overscaledZ: number
    -   wrap: number
    -   z: number
    -   x: number
    -   y: number
    
    #### Returns OverscaledTileID
    

## Properties[](#properties-1)

### canonical[](#canonical)

canonical: [CanonicalTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.CanonicalTileID/)

### key[](#key)

key: string

### overscaledZ[](#overscaledz)

overscaledZ: number

### terrainRttPosMatrix32f[](#terrainrttposmatrix32f)

terrainRttPosMatrix32f: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/) | null

This matrix is used during terrain's render-to-texture stage only. If the render-to-texture stage is active, this matrix will be present and should be used, otherwise this matrix will be null. The matrix should be float32 in order to avoid slow WebGL calls in Chrome.

### wrap[](#wrap)

wrap: number

## Methods[](#methods-1)

### calculateScaledKey[](#calculatescaledkey)

-   calculateScaledKey(targetZ: number, withWrap: boolean): string[](#calculatescaledkey-1)
    
    #### Parameters
    
    -   targetZ: number
    -   withWrap: boolean
    
    #### Returns string
    

### children[](#children)

-   children(sourceMaxZoom: number): OverscaledTileID\[\][](#children-1)
    
    #### Parameters
    
    -   sourceMaxZoom: number
    
    #### Returns OverscaledTileID\[\]
    

### clone[](#clone)

-   clone(): OverscaledTileID[](#clone-1)
    
    #### Returns OverscaledTileID
    

### equals[](#equals)

-   equals(id: OverscaledTileID): boolean[](#equals-1)
    
    #### Parameters
    
    -   id: OverscaledTileID
    
    #### Returns boolean
    

### getTilePoint[](#gettilepoint)

-   getTilePoint(coord: [MercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.MercatorCoordinate/)): [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)[](#gettilepoint-1)
    
    #### Parameters
    
    -   coord: [MercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.MercatorCoordinate/)
    
    #### Returns [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)
    

### isChildOf[](#ischildof)

-   isChildOf(parent: OverscaledTileID): boolean[](#ischildof-1)
    
    #### Parameters
    
    -   parent: OverscaledTileID
    
    #### Returns boolean
    

### isLessThan[](#islessthan)

-   isLessThan(rhs: OverscaledTileID): boolean[](#islessthan-1)
    
    #### Parameters
    
    -   rhs: OverscaledTileID
    
    #### Returns boolean
    

### isOverscaled[](#isoverscaled)

-   isOverscaled(): boolean[](#isoverscaled-1)
    
    #### Returns boolean
    

### normalizeCoordinates[](#normalizecoordinates)

-   normalizeCoordinates(  
        x: number,  
        y: number,  
        extent?: number,  
    ): { tileID: OverscaledTileID; x: number; y: number } | null[](#normalizecoordinates-1)
    
    Maps tile-local coordinates that may fall outside the `[0, extent)` range to the correct neighbor tile and the corresponding in-tile position.
    
    Coordinates can exceed tile bounds when geometry (e.g. symbol labels along lines) extends across tile edges. This method resolves such coordinates to the appropriate adjacent tile, wrapping horizontally across world boundaries and returning `null` when the target falls beyond the polar tile-grid limits.
    
    When the coordinates are already in bounds, the original tile ID is returned.
    
    #### Parameters
    
    -   x: number
        
        x coordinate relative to this tile, may be outside `[0, extent)`
        
    -   y: number
        
        y coordinate relative to this tile, may be outside `[0, extent)`
        
    -   `Optional`extent: number
        
        tile coordinate extent, default [EXTENT](https://docs.maptiler.com/sdk-js/api-reference/variables/EXTENT/)
        
    
    #### Returns { tileID: OverscaledTileID; x: number; y: number } | null
    
    the resolved tile ID and in-tile coordinates, or `null` if the target is beyond the tile grid (e.g. past the poles)
    

### overscaleFactor[](#overscalefactor)

-   overscaleFactor(): number[](#overscalefactor-1)
    
    #### Returns number
    

### scaledTo[](#scaledto)

-   scaledTo(targetZ: number): OverscaledTileID[](#scaledto-1)
    
    Returns a new `OverscaledTileID` representing the tile at the target zoom level. When targetZ is greater than the current canonical z, the canonical coordinates are unchanged. When targetZ is less than the current canonical z, the canonical coordinates are updated.
    
    #### Parameters
    
    -   targetZ: number
        
        the zoom level to scale to. Must be less than or equal to this.overscaledZ
        
    
    #### Returns OverscaledTileID
    
    a new OverscaledTileID representing the tile at the target zoom level
    
    #### Throws[](#throws)
    
    if targetZ is greater than this.overscaledZ
    

### toString[](#tostring)

-   toString(): string[](#tostring-1)
    
    #### Returns string
    

### toUnwrapped[](#tounwrapped)

-   toUnwrapped(): [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/)[](#tounwrapped-1)
    
    #### Returns [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/)
    

### unwrapTo[](#unwrapto)

-   unwrapTo(wrap: number): OverscaledTileID[](#unwrapto-1)
    
    #### Parameters
    
    -   wrap: number
    
    #### Returns OverscaledTileID
    

### wrapped[](#wrapped)

-   wrapped(): OverscaledTileID[](#wrapped-1)
    
    #### Returns OverscaledTileID