@turf/helpers
helpers
earthRadius
The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The mean radius was selected because it is recommended by the Haversine formula (used by turf/distance) to reduce error.
Type: number
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: Object
areaFactors
Area of measurement factors based on 1 square meter.
Type: Object
feature
Wraps a GeoJSON Geometry in a GeoJSON Feature.
Parameters
-
geometry
Geometry input geometry
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};
var feature = turf.feature(geometry);
Returns Feature a GeoJSON Feature
geometry
Creates a GeoJSON Geometry from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection
Parameters
type
string Geometry Typecoordinates
Array<any> Coordinatesoptions
Object Optional Parameters (optional, default {}
)
Examples
var type = "Point";
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
Returns Geometry a GeoJSON Geometry
point
Creates a Point Feature from a Position.
Parameters
-
coordinates
Array<number> longitude, latitude position (each in decimal degrees)
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var point = turf.point([-75.343, 39.984]);
Returns Feature<Point> a Point feature
points
Creates a Point FeatureCollection from an Array of Point coordinates.
Parameters
-
coordinates
Array<Array<number>> an array of Points
-
properties
Object Translate these properties to each Feature (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north]
associated with the FeatureCollectionoptions.id
(string | number)? Identifier associated with the FeatureCollection
Examples
var points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);
Returns FeatureCollection<Point> Point Feature
polygon
Creates a Polygon Feature from an Array of LinearRings.
Parameters
-
coordinates
Array<Array<Array<number>>> an array of LinearRings
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });
Returns Feature<Polygon> Polygon Feature
polygons
Creates a Polygon FeatureCollection from an Array of Polygon coordinates.
Parameters
-
coordinates
Array<Array<Array<Array<number>>>> an array of Polygon coordinates
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the FeatureCollection
Examples
var polygons = turf.polygons([
[[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]],
[[[-15, 42], [-14, 46], [-12, 41], [-17, 44], [-15, 42]]],
]);
Returns FeatureCollection<Polygon> Polygon FeatureCollection
lineString
Creates a LineString Feature from an Array of Positions.
Parameters
-
coordinates
Array<Array<number>> an array of Positions
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
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'});
Returns Feature<LineString> LineString Feature
lineStrings
Creates a LineString FeatureCollection from an Array of LineString coordinates.
Parameters
-
coordinates
Array<Array<Array<number>>> an array of LinearRings
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north]
associated with the FeatureCollectionoptions.id
(string | number)? Identifier associated with the FeatureCollection
Examples
var linestrings = turf.lineStrings([
[[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
[[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
]);
Returns FeatureCollection<LineString> LineString FeatureCollection
featureCollection
Takes one or more Features and creates a FeatureCollection.
Parameters
Examples
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
]);
Returns FeatureCollection FeatureCollection of Features
multiLineString
Creates a Feature<MultiLineString> based on a
coordinate array. Properties can be added optionally.
Parameters
-
coordinates
Array<Array<Array<number>>> an array of LineStrings
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var multiLine = turf.multiLineString([[[0,0],[10,10]]]);
- Throws Error if no coordinates are passed
Returns Feature<MultiLineString> a MultiLineString feature
multiPoint
Creates a Feature<MultiPoint> based on a
coordinate array. Properties can be added optionally.
Parameters
-
coordinates
Array<Array<number>> an array of Positions
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var multiPt = turf.multiPoint([[0,0],[10,10]]);
- Throws Error if no coordinates are passed
Returns Feature<MultiPoint> a MultiPoint feature
multiPolygon
Creates a Feature<MultiPolygon> based on a
coordinate array. Properties can be added optionally.
Parameters
-
coordinates
Array<Array<Array<Array<number>>>> an array of Polygons
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
- Throws Error if no coordinates are passed
Returns Feature<MultiPolygon> a multipolygon feature
geometryCollection
Creates a Feature<GeometryCollection> based on a
coordinate array. Properties can be added optionally.
Parameters
-
geometries
Array<Geometry> an array of GeoJSON Geometries
-
properties
Object an Object of key-value pairs to add as properties (optional, default {}
)
-
options
Object Optional Parameters (optional, default {}
)
options.bbox
Array<number>? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id
(string | number)? Identifier associated with the Feature
Examples
var pt = turf.geometry("Point", [100, 0]);
var line = turf.geometry("LineString", [[101, 0], [102, 1]]);
var collection = turf.geometryCollection([pt, line]);
Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature
round
Round number to precision
Parameters
num
number Numberprecision
number Precision (optional, default 0
)
Examples
turf.round(120.4321)
turf.round(120.4321, 2)
Returns number 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
Parameters
radians
number in radians across the sphereunits
string can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers"
)
Returns number 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
Parameters
distance
number in real unitsunits
string can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers"
)
Returns number 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
Parameters
distance
number in real unitsunits
string can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers"
)
Returns number 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
Parameters
bearing
number angle, between -180 and +180 degrees
Returns number 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
Parameters
angle
number between 0 and 360 degrees
Returns number bearing between -180 and +180 degrees
radiansToDegrees
Converts an angle in radians to degrees
Parameters
radians
number angle in radians
Returns number degrees between 0 and 360 degrees
degreesToRadians
Converts an angle in degrees to radians
Parameters
degrees
number angle between 0 and 360 degrees
Returns number angle in radians
convertLength
Converts a length to the requested unit.
Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
Parameters
length
number to be convertedoriginalUnit
Units of the length (optional, default "kilometers"
)finalUnit
Units returned unit (optional, default "kilometers"
)
Returns number the converted length
convertArea
Converts a area to the requested unit.
Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares
Parameters
area
number to be convertedoriginalUnit
Units of the distance (optional, default "meters"
)finalUnit
Units returned unit (optional, default "kilometers"
)
Returns number the converted area
isNumber
isNumber
Parameters
num
any Number to validate
Examples
turf.isNumber(123)
turf.isNumber('foo')
Returns boolean true/false
isObject
isObject
Parameters
input
any variable to validate
Examples
turf.isObject({elevation: 10})
turf.isObject('foo')
Returns boolean true/false, including false for Arrays and Functions
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.
Installation
Install this single module individually:
$ npm install @turf/helpers
Or install the all-encompassing @turf/turf module that includes all modules as functions:
$ npm install @turf/turf