@turf/helpers

helpers

Units

Linear measurement units.

⚠️ Warning. Be aware of the implications of using radian or degree units to
measure distance. The distance represented by a degree of longitude varies
depending on latitude.

See [https://www.thoughtco.com/degree-of-latitude-and-longitude-distance-4070616][1]
for an illustration of this behaviour.

Type: ("meters" | "metres" | "millimeters" | "millimetres" | "centimeters" | "centimetres" | "kilometers" | "kilometres" | "miles" | "nauticalmiles" | "inches" | "yards" | "feet" | "radians" | "degrees")

AreaUnits

Area measurement units.

Type: (Exclude<[Units][2], ("radians" | "degrees")> | "acres" | "hectares")

Grid

Grid types.

Type: ("point" | "square" | "hex" | "triangle")

Corners

Shorthand corner identifiers.

Type: ("sw" | "se" | "nw" | "ne" | "center" | "centroid")

Lines

Geometries made up of lines i.e. lines and polygons.

Type: ([LineString][3] | [MultiLineString][4] | [Polygon][5] | [MultiPolygon][6])

AllGeoJSON

Convenience type for all possible GeoJSON.

Type: ([Feature][7] | [FeatureCollection][8] | [Geometry][9] | [GeometryCollection][10])

earthRadius

The Earth radius in meters. Used by Turf modules that model the Earth as a sphere. The [mean radius][11] was selected because it is [recommended ][12] by the Haversine formula (used by turf/distance) to reduce error.

Type: [number][13]

factors

Unit of measurement factors based on earthRadius.

Keys are the name of the unit, values are the number of that unit in a single radian

Type: Record<[Units][2], [number][13]>

areaFactors

Area of measurement factors based on 1 square meter.

Type: Record<[AreaUnits][14], [number][13]>

feature

Wraps a GeoJSON [Geometry][9] in a GeoJSON [Feature][7].

$3

* geom (G | null)
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature
* geometry [GeometryObject][9] input geometry

$3

``javascript
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};

var feature = turf.feature(geometry);

//=feature
`

Returns [Feature][7]<[GeometryObject][9], [GeoJsonProperties][7]> a GeoJSON Feature

geometry

Creates a GeoJSON [Geometry][9] from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection

$3

* type ("Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon") Geometry Type
* coordinates [Array][17]\ Coordinates
* _options Record<[string][18], never> (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

$3

`javascript
var type = "Point";
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
// => geometry
`

Returns [Geometry][9] a GeoJSON Geometry

point

Creates a [Point][19] [Feature][7] from a Position.

$3

* coordinates [Position][20] longitude, latitude position (each in decimal degrees)
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var point = turf.point([-75.343, 39.984]);

//=point
`

Returns [Feature][7]<[Point][19], [GeoJsonProperties][7]> a Point feature

points

Creates a [Point][19] [FeatureCollection][8] from an Array of Point coordinates.

$3

* coordinates [Array][17]<[Position][20]> an array of Points
* properties [GeoJsonProperties][7] Translate these properties to each Feature (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north]
associated with the FeatureCollection
* options.id Id? Identifier associated with the FeatureCollection

$3

`javascript
var points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);

//=points
`

Returns [FeatureCollection][8]<[Point][19]> Point Feature

polygon

Creates a [Polygon][5] [Feature][7] from an Array of LinearRings.

$3

* coordinates [Array][17]<[Array][17]<[Position][20]>>
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });

//=polygon
`

Returns [Feature][7]<[Polygon][5], [GeoJsonProperties][7]> Polygon Feature

polygons

Creates a [Polygon][5] [FeatureCollection][8] from an Array of Polygon coordinates.

$3

* coordinates [Array][17]<[Array][17]<[Array][17]<[Position][20]>>>
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the FeatureCollection

$3

`javascript
var polygons = turf.polygons([
[[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]],
[[[-15, 42], [-14, 46], [-12, 41], [-17, 44], [-15, 42]]],
]);

//=polygons
`

Returns [FeatureCollection][8]<[Polygon][5], [GeoJsonProperties][7]> Polygon FeatureCollection

lineString

Creates a [LineString][3] [Feature][7] from an Array of Positions.

$3

* coordinates [Array][17]<[Position][20]> an array of Positions
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var linestring1 = turf.lineString([[-24, 63], [-23, 60], [-25, 65], [-20, 69]], {name: 'line 1'});
var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], {name: 'line 2'});

//=linestring1
//=linestring2
`

Returns [Feature][7]<[LineString][3], [GeoJsonProperties][7]> LineString Feature

lineStrings

Creates a [LineString][3] [FeatureCollection][8] from an Array of LineString coordinates.

$3

* coordinates [Array][17]<[Array][17]<[Position][20]>>
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north]
associated with the FeatureCollection
* options.id Id? Identifier associated with the FeatureCollection

$3

`javascript
var linestrings = turf.lineStrings([
[[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
[[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
]);

//=linestrings
`

Returns [FeatureCollection][8]<[LineString][3], [GeoJsonProperties][7]> LineString FeatureCollection

featureCollection

Takes one or more [Features][7] and creates a [FeatureCollection][8].

$3

* features [Array][17]<[Feature][7]<[GeometryObject][9], [GeoJsonProperties][7]>> input features
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var locationA = turf.point([-75.343, 39.984], {name: 'Location A'});
var locationB = turf.point([-75.833, 39.284], {name: 'Location B'});
var locationC = turf.point([-75.534, 39.123], {name: 'Location C'});

var collection = turf.featureCollection([
locationA,
locationB,
locationC
]);

//=collection
`

Returns [FeatureCollection][8]<[GeometryObject][9], [GeoJsonProperties][7]> FeatureCollection of Features

multiLineString

Creates a [Feature][7]<[MultiLineString][4]> based on a
coordinate array. Properties can be added optionally.

$3

* coordinates [Array][17]<[Array][17]<[Position][20]>>
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var multiLine = turf.multiLineString([[[0,0],[10,10]]]);

//=multiLine
`

* Throws [Error][21] if no coordinates are passed

Returns [Feature][7]<[MultiLineString][4], [GeoJsonProperties][7]> a MultiLineString feature

multiPoint

Creates a [Feature][7]<[MultiPoint][22]> based on a
coordinate array. Properties can be added optionally.

$3

* coordinates [Array][17]<[Position][20]> an array of Positions
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var multiPt = turf.multiPoint([[0,0],[10,10]]);

//=multiPt
`

* Throws [Error][21] if no coordinates are passed

Returns [Feature][7]<[MultiPoint][22], [GeoJsonProperties][7]> a MultiPoint feature

multiPolygon

Creates a [Feature][7]<[MultiPolygon][6]> based on a
coordinate array. Properties can be added optionally.

$3

* coordinates [Array][17]<[Array][17]<[Array][17]<[Position][20]>>>
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);

//=multiPoly
`

* Throws [Error][21] if no coordinates are passed

Returns [Feature][7]<[MultiPolygon][6], [GeoJsonProperties][7]> a multipolygon feature

geometryCollection

Creates a Feature based on a
coordinate array. Properties can be added optionally.

$3

* geometries [Array][17]<([Point][19] | [LineString][3] | [Polygon][5] | [MultiPoint][22] | [MultiLineString][4] | [MultiPolygon][6])> an array of GeoJSON Geometries
* properties [GeoJsonProperties][7] an Object of key-value pairs to add as properties (optional, default {})
* options [Object][15] Optional Parameters (optional, default {})

* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Feature
* options.id Id? Identifier associated with the Feature

$3

`javascript
var pt = turf.geometry("Point", [100, 0]);
var line = turf.geometry("LineString", [[101, 0], [102, 1]]);
var collection = turf.geometryCollection([pt, line]);

// => collection
`

Returns [Feature][7]<[GeometryCollection][10], [GeoJsonProperties][7]> a GeoJSON GeometryCollection Feature

round

Round number to precision

$3

* num [number][13] Number
* precision [number][13] Precision (optional, default 0)

$3

`javascript
turf.round(120.4321)
//=120

turf.round(120.4321, 2)
//=120.43
`

Returns [number][13] rounded number

radiansToLength

Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit.
Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

$3

* radians [number][13] in radians across the sphere
* units [Units][2] can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")

Returns [number][13] distance

lengthToRadians

Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians
Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

$3

* distance [number][13] in real units
* units [Units][2] can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")

Returns [number][13] radians

lengthToDegrees

Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees
Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet

$3

* distance [number][13] in real units
* units [Units][2] can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")

Returns [number][13] degrees

bearingToAzimuth

Converts any bearing angle from the north line direction (positive clockwise)
and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line

$3

* bearing [number][13] angle, between -180 and +180 degrees

Returns [number][13] angle between 0 and 360 degrees

azimuthToBearing

Converts any azimuth angle from the north line direction (positive clockwise)
and returns an angle between -180 and +180 degrees (positive clockwise), 0 being the north line

$3

* angle [number][13] between 0 and 360 degrees

Returns [number][13] bearing between -180 and +180 degrees

radiansToDegrees

Converts an angle in radians to degrees

$3

* radians [number][13] angle in radians

Returns [number][13] degrees between 0 and 360 degrees

degreesToRadians

Converts an angle in degrees to radians

$3

* degrees [number][13] angle between 0 and 360 degrees

Returns [number][13] angle in radians

convertLength

Converts a length from one unit to another.

$3

* length [number][13] Length to be converted
* originalUnit [Units][2] Input length unit (optional, default "kilometers")
* finalUnit [Units][2] Returned length unit (optional, default "kilometers")

Returns [number][13] The converted length

convertArea

Converts an area from one unit to another.

$3

* area [number][13] Area to be converted
* originalUnit [AreaUnits][14] Input area unit (optional, default "meters")
* finalUnit [AreaUnits][14] Returned area unit (optional, default "kilometers")

Returns [number][13] The converted length

isNumber

isNumber

$3

* num any Number to validate

$3

`javascript
turf.isNumber(123)
//=true
turf.isNumber('foo')
//=false
`

Returns [boolean][23] true/false

isObject

isObject

$3

* input any variable to validate

$3

`javascript
turf.isObject({elevation: 10})
//=true
turf.isObject('foo')
//=false
`

Returns [boolean][23] true/false, including false for Arrays and Functions

[1]: https://www.thoughtco.com/degree-of-latitude-and-longitude-distance-4070616

[2]: #units

[3]: https://tools.ietf.org/html/rfc7946#section-3.1.4

[4]: https://tools.ietf.org/html/rfc7946#section-3.1.5

[5]: https://tools.ietf.org/html/rfc7946#section-3.1.6

[6]: https://tools.ietf.org/html/rfc7946#section-3.1.7

[7]: https://tools.ietf.org/html/rfc7946#section-3.2

[8]: https://tools.ietf.org/html/rfc7946#section-3.3

[9]: https://tools.ietf.org/html/rfc7946#section-3.1

[10]: https://tools.ietf.org/html/rfc7946#section-3.1.8

[11]: https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius

[12]: https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended

[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[14]: #areaunits

[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[16]: https://tools.ietf.org/html/rfc7946#section-5

[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[19]: https://tools.ietf.org/html/rfc7946#section-3.1.2

[20]: https://developer.mozilla.org/docs/Web/API/Position

[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error

[22]: https://tools.ietf.org/html/rfc7946#section-3.1.3

[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

---

This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

$3

Install this single module individually:

`sh
$ npm install @turf/helpers
`

Or install the all-encompassing @turf/turf module that includes all modules as functions:

`sh
$ npm install @turf/turf
``