Table of Contents

Point

A Point geometry object, which has x and y properties representing screen coordinates in pixels.

Type: Object

Examples

var point = new mapboxgl.Point(-77, 38);

PointLike

A Point or an array of two numbers representing x and y screen coordinates in pixels.

Type: (Point | Array<number>)

Examples

var p1 = new mapboxgl.Point(-77, 38); // a PointLike which is a Point
var p2 = [-77, 38]; // a PointLike which is an array of two numbers

EdgeInsets

An EdgeInset object represents screen space padding applied to the edges of the viewport. This shifts the apprent center or the vanishing point of the map. This is useful for adding floating UI elements on top of the map and having the vanishing point shift as UI elements resize.

Parameters

  • top number (optional, default 0)
  • bottom number (optional, default 0)
  • left number (optional, default 0)
  • right number (optional, default 0)

interpolate

Interpolates the inset in-place. This maintains the current inset value for any inset not present in target.

Parameters

Returns EdgeInsets

getCenter

Utility method that computes the new apprent center or vanishing point after applying insets. This is in pixels and with the top left being (0.0) and +y being downwards.

Parameters

Returns Point

toJSON

Returns the current sdtate as json, useful when you want to have a read-only representation of the inset.

Returns PaddingOptions

LngLat

A LngLat object represents a given longitude and latitude coordinate, measured in degrees. These coordinates are based on the WGS84 (EPSG:4326) standard.

Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the GeoJSON specification.

Note that any Mapbox GL method that accepts a LngLat object as an argument or option can also accept an Array of two numbers and will perform an implicit conversion. This flexible type is documented as LngLatLike.

Parameters

  • lng number Longitude, measured in degrees.
  • lat number Latitude, measured in degrees.

Examples

var ll = new mapboxgl.LngLat(-123.9749, 40.7736);
ll.lng; // = -123.9749

wrap

Returns a new LngLat object whose longitude is wrapped to the range (-180, 180).

Examples

var ll = new mapboxgl.LngLat(286.0251, 40.7736);
var wrapped = ll.wrap();
wrapped.lng; // = -73.9749

Returns LngLat The wrapped LngLat object.

toArray

Returns the coordinates represented as an array of two numbers.

Examples

var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
ll.toArray(); // = [-73.9749, 40.7736]

Returns Array<number> The coordinates represeted as an array of longitude and latitude.

toString

Returns the coordinates represent as a string.

Examples

var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
ll.toString(); // = "LngLat(-73.9749, 40.7736)"

Returns string The coordinates represented as a string of the format 'LngLat(lng, lat)'.

distanceTo

Returns the approximate distance between a pair of coordinates in meters Uses the Haversine Formula (from R.W. Sinnott, “Virtues of the Haversine”, Sky and Telescope, vol. 68, no. 2, 1984, p. 159)

Parameters

  • lngLat LngLat coordinates to compute the distance to

Examples

var new_york = new mapboxgl.LngLat(-74.0060, 40.7128);
var los_angeles = new mapboxgl.LngLat(-118.2437, 34.0522);
new_york.distanceTo(los_angeles); // = 3935751.690893987, "true distance" using a non-spherical approximation is ~3966km

Returns number Distance in meters between the two coordinates.

toBounds

Returns a LngLatBounds from the coordinates extended by a given radius. The returned LngLatBounds completely contains the radius.

Parameters

  • radius number Distance in meters from the coordinates to extend the bounds. (optional, default 0)

Examples

var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
ll.toBounds(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]

Returns LngLatBounds A new LngLatBounds object representing the coordinates extended by the radius.

convert

Converts an array of two numbers or an object with lng and lat or lon and lat properties to a LngLat object.

If a LngLat object is passed in, the function returns it unchanged.

Parameters

  • input LngLatLike An array of two numbers or object to convert, or a LngLat object to return.

Examples

var arr = [-73.9749, 40.7736];
var ll = mapboxgl.LngLat.convert(arr);
ll;   // = LngLat {lng: -73.9749, lat: 40.7736}

Returns LngLat A new LngLat object, if a conversion occurred, or the original LngLat object.

LngLatLike

A LngLat object, an array of two numbers representing longitude and latitude, or an object with lng and lat or lon and lat properties.

Type: (LngLat {lng: number, lat: number} {lon: number, lat: number} [number, number])

Examples

var v1 = new mapboxgl.LngLat(-122.420679, 37.772537);
var v2 = [-122.420679, 37.772537];
var v3 = {lon: -122.420679, lat: 37.772537};

LngLatBounds

A LngLatBounds object represents a geographical bounding box, defined by its southwest and northeast points in longitude and latitude.

If no arguments are provided to the constructor, a null bounding box is created.

Note that any Mapbox GL method that accepts a LngLatBounds object as an argument or option can also accept an Array of two LngLatLike constructs and will perform an implicit conversion. This flexible type is documented as LngLatBoundsLike.

Parameters

  • sw LngLatLike? The southwest corner of the bounding box.
  • ne LngLatLike? The northeast corner of the bounding box.

Examples

var sw = new mapboxgl.LngLat(-73.9876, 40.7661);
var ne = new mapboxgl.LngLat(-73.9397, 40.8002);
var llb = new mapboxgl.LngLatBounds(sw, ne);

setNorthEast

Set the northeast corner of the bounding box

Parameters

Returns LngLatBounds this

setSouthWest

Set the southwest corner of the bounding box

Parameters

Returns LngLatBounds this

extend

Extend the bounds to include a given LngLatLike or LngLatBoundsLike.

Parameters

Returns LngLatBounds this

getCenter

Returns the geographical coordinate equidistant from the bounding box’s corners.

Examples

var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.getCenter(); // = LngLat {lng: -73.96365, lat: 40.78315}

Returns LngLat The bounding box’s center.

getSouthWest

Returns the southwest corner of the bounding box.

Returns LngLat The southwest corner of the bounding box.

getNorthEast

Returns the northeast corner of the bounding box.

Returns LngLat The northeast corner of the bounding box.

getNorthWest

Returns the northwest corner of the bounding box.

Returns LngLat The northwest corner of the bounding box.

getSouthEast

Returns the southeast corner of the bounding box.

Returns LngLat The southeast corner of the bounding box.

getWest

Returns the west edge of the bounding box.

Returns number The west edge of the bounding box.

getSouth

Returns the south edge of the bounding box.

Returns number The south edge of the bounding box.

getEast

Returns the east edge of the bounding box.

Returns number The east edge of the bounding box.

getNorth

Returns the north edge of the bounding box.

Returns number The north edge of the bounding box.

toArray

Returns the bounding box represented as an array.

Examples

var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toArray(); // = [[-73.9876, 40.7661], [-73.9397, 40.8002]]

Returns Array<Array<number» The bounding box represented as an array, consisting of the southwest and northeast coordinates of the bounding represented as arrays of numbers.

toString

Return the bounding box represented as a string.

Examples

var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toString(); // = "LngLatBounds(LngLat(-73.9876, 40.7661), LngLat(-73.9397, 40.8002))"

Returns string The bounding box represents as a string of the format 'LngLatBounds(LngLat(lng, lat), LngLat(lng, lat))'.

isEmpty

Check if the bounding box is an empty/null-type box.

Returns boolean True if bounds have been defined, otherwise false.

contains

Check if the point is within the bounding box.

Parameters

  • lnglat LngLatLike geographic point to check against.

Examples

var llb = new mapboxgl.LngLatBounds(
  new mapboxgl.LngLat(-73.9876, 40.7661),
  new mapboxgl.LngLat(-73.9397, 40.8002)
);

var ll = new mapboxgl.LngLat(-73.9567, 40.7789);

console.log(llb.contains(ll)); // = true

Returns boolean True if the point is within the bounding box.

convert

Converts an array to a LngLatBounds object.

If a LngLatBounds object is passed in, the function returns it unchanged.

Internally, the function calls LngLat#convert to convert arrays to LngLat values.

Parameters

  • input LngLatBoundsLike An array of two coordinates to convert, or a LngLatBounds object to return.

Examples

var arr = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
var llb = mapboxgl.LngLatBounds.convert(arr);
llb;   // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}

Returns LngLatBounds A new LngLatBounds object, if a conversion occurred, or the original LngLatBounds object.

LngLatBoundsLike

A LngLatBounds object, an array of LngLatLike objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order.

Type: (LngLatBounds [LngLatLike, LngLatLike] [number, number, number, number])

Examples

var v1 = new mapboxgl.LngLatBounds(
  new mapboxgl.LngLat(-73.9876, 40.7661),
  new mapboxgl.LngLat(-73.9397, 40.8002)
);
var v2 = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
var v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];

MercatorCoordinate

A MercatorCoordinate object represents a projected three dimensional position.

MercatorCoordinate uses the web mercator projection (EPSG: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 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.

Parameters

  • x number The x component of the position.
  • y number The y component of the position.
  • z number The z component of the position. (optional, default 0)

Examples

var nullIsland = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);

toLngLat

Returns the LngLat for the coordinate.

Examples

var coord = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);
var lngLat = coord.toLngLat(); // LngLat(0, 0)

Returns LngLat The LngLat object.

toAltitude

Returns the altitude in meters of the coordinate.

Examples

var coord = new mapboxgl.MercatorCoordinate(0, 0, 0.02);
coord.toAltitude(); // 6914.281956295339

Returns number The altitude in meters.

meterInMercatorCoordinateUnits

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 MercatorCoordinates.

Returns number Distance of 1 meter in MercatorCoordinate units.

fromLngLat

Project a LngLat to a MercatorCoordinate.

Parameters

  • lngLatLike LngLatLike The location to project.
  • altitude number The altitude in meters of the position. (optional, default 0)

Examples

var coord = mapboxgl.MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
coord; // MercatorCoordinate(0.5, 0.5, 0)

Returns MercatorCoordinate The projected mercator coordinate.