---
title: "MercatorCoordinate | 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 MercatorCoordinate

A `MercatorCoordinate` object represents a projected three dimensional position.

`MercatorCoordinate` uses the web mercator projection ([EPSG:3857](https://epsg.io/3857)) with slightly different units:

-   the size of 1 unit is the width of the projected world instead of the "mercator meter"
-   the origin of the coordinate space is at the north-west corner instead of the middle

For example, `MercatorCoordinate(0, 0, 0)` is the north-west corner of the mercator world and `MercatorCoordinate(1, 1, 0)` is the south-east corner. If you are familiar with [vector tiles](https://github.com/mapbox/vector-tile-spec) it may be helpful to think of the coordinate space as the `0/0/0` tile with an extent of `1`.

The `z` dimension of `MercatorCoordinate` is conformal. A cube in the mercator coordinate space would be rendered as a cube.

#### Example[](#example)

```typescript
let nullIsland = new MercatorCoordinate(0.5, 0.5, 0);
```

#### See[](#see)

-   [Add a custom style layer](https://maplibre.org/maplibre-gl-js/docs/examples/add-a-custom-style-layer/)
-   [Add a 3D model using three.js](https://maplibre.org/maplibre-gl-js/docs/examples/add-a-3d-model-using-threejs/)
-   [Add a simple custom layer on a globe](https://maplibre.org/maplibre-gl-js/docs/examples/add-a-simple-custom-layer-on-a-globe/)

#### Implements

-   [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/)

##### Index

### Constructors[](#constructors)

[constructor](#constructor)

### Properties[](#properties)

[x](#x) [y](#y) [z](#z)

### Methods[](#methods)

[meterInMercatorCoordinateUnits](#meterinmercatorcoordinateunits) [toAltitude](#toaltitude) [toLngLat](#tolnglat) [fromLngLat](#fromlnglat)

## Constructors[](#constructors-1)

### constructor[](#constructor)

-   new MercatorCoordinate(x: number, y: number, z?: number): MercatorCoordinate[](#constructormercatorcoordinate)
    
    #### Parameters
    
    -   x: number
        
        The x component of the position.
        
    -   y: number
        
        The y component of the position.
        
    -   `Optional`z: number
        
        The z component of the position.
        
    
    #### Returns MercatorCoordinate
    

## Properties[](#properties-1)

### x[](#x)

x: number

Implementation of [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/).[x](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/#x)

### y[](#y)

y: number

Implementation of [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/).[y](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/#y)

### z[](#z)

z: number

Implementation of [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/).[z](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/#z)

## Methods[](#methods-1)

### meterInMercatorCoordinateUnits[](#meterinmercatorcoordinateunits)

-   meterInMercatorCoordinateUnits(): number[](#meterinmercatorcoordinateunits-1)
    
    Returns the distance of 1 meter in `MercatorCoordinate` units at this latitude.
    
    For coordinates in real world units using meters, this naturally provides the scale to transform into `MercatorCoordinate`s.
    
    #### Returns number
    
    Distance of 1 meter in `MercatorCoordinate` units.
    
    Implementation of [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/).[meterInMercatorCoordinateUnits](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/#meterinmercatorcoordinateunits)
    

### toAltitude[](#toaltitude)

-   toAltitude(): number[](#toaltitude-1)
    
    Returns the altitude in meters of the coordinate.
    
    #### Returns number
    
    The altitude in meters.
    
    #### Example[](#example-1)
    
    ```typescript
    let coord = new MercatorCoordinate(0, 0, 0.02);
    coord.toAltitude(); // 6914.281956295339
    ```
    
    Implementation of [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/).[toAltitude](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/#toaltitude)
    

### toLngLat[](#tolnglat)

-   toLngLat(): [LngLat](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.LngLat/)[](#tolnglat-1)
    
    Returns the `LngLat` for the coordinate.
    
    #### Returns [LngLat](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.LngLat/)
    
    The `LngLat` object.
    
    #### Example[](#example-2)
    
    ```typescript
    let coord = new MercatorCoordinate(0.5, 0.5, 0);
    let lngLat = coord.toLngLat(); // LngLat(0, 0)
    ```
    
    Implementation of [IMercatorCoordinate](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/).[toLngLat](https://docs.maptiler.com/sdk-js/api-reference/interfaces/IMercatorCoordinate/#tolnglat)
    

### `Static`fromLngLat[](#fromlnglat)

-   fromLngLat(lngLatLike: [LngLatLike](https://docs.maptiler.com/sdk-js/api-reference/types/LngLatLike/), altitude?: number): MercatorCoordinate[](#fromlnglat-1)
    
    Project a `LngLat` to a `MercatorCoordinate`.
    
    #### Parameters
    
    -   lngLatLike: [LngLatLike](https://docs.maptiler.com/sdk-js/api-reference/types/LngLatLike/)
        
        The location to project.
        
    -   `Optional`altitude: number
        
        The altitude in meters of the position.
        
    
    #### Returns MercatorCoordinate
    
    The projected mercator coordinate.
    
    #### Example[](#example-3)
    
    ```typescript
    let coord = MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
    coord; // MercatorCoordinate(0.5, 0.5, 0)
    ```