Provides helper functions to create GeoJSON features, like points, lines, or areas on a map.
npm install @turf/helpersLinear 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")
Area measurement units.
Type: (Exclude<[Units][2], ("radians" | "degrees")> | "acres" | "hectares")
Grid types.
Type: ("point" | "square" | "hex" | "triangle")
Shorthand corner identifiers.
Type: ("sw" | "se" | "nw" | "ne" | "center" | "centroid")
Geometries made up of lines i.e. lines and polygons.
Type: ([LineString][3] | [MultiLineString][4] | [Polygon][5] | [MultiPolygon][6])
Convenience type for all possible GeoJSON.
Type: ([Feature][7] | [FeatureCollection][8] | [Geometry][9] | [GeometryCollection][10])
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]
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]>
Area of measurement factors based on 1 square meter.
Type: Record<[AreaUnits][14], [number][13]>
Wraps a GeoJSON [Geometry][9] in a GeoJSON [Feature][7].
* 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
``javascript
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};
var feature = turf.feature(geometry);
//=feature
`
Returns [Feature][7]<[GeometryObject][9], [GeoJsonProperties][7]> a GeoJSON Feature
Creates a GeoJSON [Geometry][9] from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection
* type ("Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon") Geometry Typecoordinates
* [Array][17]\_options
* Record<[string][18], never> (optional, default {})options
* [Object][15] Optional Parameters (optional, default {})
`javascript`
var type = "Point";
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
// => geometry
Returns [Geometry][9] a GeoJSON Geometry
Creates a [Point][19] [Feature][7] from a Position.
* 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 Featureoptions.id
* Id? Identifier associated with the Feature
`javascript
var point = turf.point([-75.343, 39.984]);
//=point
`
Returns [Feature][7]<[Point][19], [GeoJsonProperties][7]> a Point feature
Creates a [Point][19] [FeatureCollection][8] from an Array of Point coordinates.
* coordinates [Array][17]<[Position][20]> an array of Pointsproperties
* [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]options.id
associated with the FeatureCollection
* Id? Identifier associated with the FeatureCollection
`javascript
var points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);
//=points
`
Returns [FeatureCollection][8]<[Point][19]> Point Feature
Creates a [Polygon][5] [Feature][7] from an Array of LinearRings.
* 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 Featureoptions.id
* Id? Identifier associated with the Feature
`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
Creates a [Polygon][5] [FeatureCollection][8] from an Array of Polygon coordinates.
* 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 Featureoptions.id
* Id? Identifier associated with the FeatureCollection
`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
Creates a [LineString][3] [Feature][7] from an Array of Positions.
* coordinates [Array][17]<[Position][20]> an array of Positionsproperties
* [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 Featureoptions.id
* Id? Identifier associated with the Feature
`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
Creates a [LineString][3] [FeatureCollection][8] from an Array of LineString coordinates.
* 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]options.id
associated with the FeatureCollection
* Id? Identifier associated with the FeatureCollection
`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
Takes one or more [Features][7] and creates a [FeatureCollection][8].
* features [Array][17]<[Feature][7]<[GeometryObject][9], [GeoJsonProperties][7]>> input featuresoptions
* [Object][15] Optional Parameters (optional, default {})
* options.bbox [BBox][16]? Bounding Box Array \[west, south, east, north] associated with the Featureoptions.id
* Id? Identifier associated with the Feature
`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
Creates a [Feature][7]<[MultiLineString][4]> based on a
coordinate array. Properties can be added optionally.
* 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 Featureoptions.id
* Id? Identifier associated with the Feature
`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
Creates a [Feature][7]<[MultiPoint][22]> based on a
coordinate array. Properties can be added optionally.
* coordinates [Array][17]<[Position][20]> an array of Positionsproperties
* [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 Featureoptions.id
* Id? Identifier associated with the Feature
`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
Creates a [Feature][7]<[MultiPolygon][6]> based on a
coordinate array. Properties can be added optionally.
* 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 Featureoptions.id
* Id? Identifier associated with the Feature
`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
Creates a Feature
coordinate array. Properties can be added optionally.
* geometries [Array][17]<([Point][19] | [LineString][3] | [Polygon][5] | [MultiPoint][22] | [MultiLineString][4] | [MultiPolygon][6])> an array of GeoJSON Geometriesproperties
* [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 Featureoptions.id
* Id? Identifier associated with the Feature
`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 number to precision
* num [number][13] Numberprecision
* [number][13] Precision (optional, default 0)
`javascript
turf.round(120.4321)
//=120
turf.round(120.4321, 2)
//=120.43
`
Returns [number][13] rounded number
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
* radians [number][13] in radians across the sphereunits
* [Units][2] can be degrees, radians, miles, inches, yards, metres,"kilometers"
meters, kilometres, kilometers. (optional, default )
Returns [number][13] distance
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
* distance [number][13] in real unitsunits
* [Units][2] can be degrees, radians, miles, inches, yards, metres,"kilometers"
meters, kilometres, kilometers. (optional, default )
Returns [number][13] radians
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
* distance [number][13] in real unitsunits
* [Units][2] can be degrees, radians, miles, inches, yards, metres,"kilometers"
meters, kilometres, kilometers. (optional, default )
Returns [number][13] degrees
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
* bearing [number][13] angle, between -180 and +180 degrees
Returns [number][13] angle between 0 and 360 degrees
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
* angle [number][13] between 0 and 360 degrees
Returns [number][13] bearing between -180 and +180 degrees
Converts an angle in radians to degrees
* radians [number][13] angle in radians
Returns [number][13] degrees between 0 and 360 degrees
Converts an angle in degrees to radians
* degrees [number][13] angle between 0 and 360 degrees
Returns [number][13] angle in radians
Converts a length from one unit to another.
* length [number][13] Length to be convertedoriginalUnit
* [Units][2] Input length unit (optional, default "kilometers")finalUnit
* [Units][2] Returned length unit (optional, default "kilometers")
Returns [number][13] The converted length
Converts an area from one unit to another.
* area [number][13] Area to be convertedoriginalUnit
* [AreaUnits][14] Input area unit (optional, default "meters")finalUnit
* [AreaUnits][14] Returned area unit (optional, default "kilometers")
Returns [number][13] The converted length
isNumber
* num any Number to validate
`javascript`
turf.isNumber(123)
//=true
turf.isNumber('foo')
//=false
Returns [boolean][23] true/false
isObject
* input any variable to validate
`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.
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