@turf/helpers
Advanced tools
The @turf/helpers package is part of the Turf.js library, which is a modular geospatial engine written in JavaScript. It provides functions to create various simple geometrical features such as points, lines, and polygons, and to manipulate these geometries in various ways. This package is particularly useful for developers working with geographic information systems (GIS) and spatial analysis in web applications.
Creating Points
This function creates a GeoJSON Point feature using the provided coordinates. It is useful for representing locations on a map.
const point = turf.point([5, 10]);Creating LineStrings
This function creates a GeoJSON LineString feature from an array of positions. It is useful for mapping routes or paths.
const line = turf.lineString([[5, 10], [20, 40]]);Creating Polygons
This function creates a GeoJSON Polygon feature from an array of linear rings. It is used to represent areas such as city boundaries or lakes.
const polygon = turf.polygon([[[5, 10], [20, 40], [40, 0], [5, 10]]]);Leaflet is a leading open-source JavaScript library for mobile-friendly interactive maps. While Leaflet itself focuses more on map interactions and overlays, it can be used in conjunction with other tools for creating and manipulating geographic data, similar to @turf/helpers.
OpenLayers is another powerful open-source JavaScript library that handles various map-related tasks. It provides more comprehensive features for handling complex spatial operations compared to @turf/helpers, which is more focused on creating and manipulating simple geometrical features.
Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
Units of measurement factors based on 1 meter.
Area of measurement factors based on 1 square meter.
Wraps a GeoJSON Geometry in a GeoJSON Feature.
Parameters
geometry Geometry input geometryproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};
var feature = turf.feature(geometry);
//=feature
Returns Feature a GeoJSON Feature
Creates a GeoJSON Geometry from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection
Parameters
type string Geometry Typecoordinates Array<number> Coordinatesoptions Object Optional Parameters (optional, default {})
Examples
var type = 'Point';
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
//=geometry
Returns Geometry a GeoJSON Geometry
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 {})
Examples
var point = turf.point([-75.343, 39.984]);
//=point
Returns Feature<Point> a Point feature
Creates a Point FeatureCollection from an Array of Point coordinates.
Parameters
coordinates Array<Array<number>> an array of Pointsproperties Object Translate these properties to each Feature (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);
//=points
Returns FeatureCollection<Point> Point Feature
Creates a Polygon Feature from an Array of LinearRings.
Parameters
coordinates Array<Array<Array<number>>> an array of LinearRingsproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });
//=polygon
Returns Feature<Polygon> Polygon Feature
Creates a Polygon FeatureCollection from an Array of Polygon coordinates.
Parameters
coordinates Array<Array<Array<Array<number>>>> an array of Polygon coordinatesproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
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]]],
]);
//=polygons
Returns FeatureCollection<Polygon> Polygon FeatureCollection
Creates a LineString Feature from an Array of Positions.
Parameters
coordinates Array<Array<number>> an array of Positionsproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
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'});
//=linestring1
//=linestring2
Returns Feature<LineString> LineString Feature
Creates a LineString FeatureCollection from an Array of LineString coordinates.
Parameters
coordinates Array<Array<number>> an array of LinearRingsproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var linestrings = turf.lineStrings([
[[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
[[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
]);
//=linestrings
Returns FeatureCollection<LineString> LineString 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
]);
//=collection
Returns FeatureCollection FeatureCollection of Features
Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.
Parameters
coordinates Array<Array<Array<number>>> an array of LineStringsproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var multiLine = turf.multiLineString([[[0,0],[10,10]]]);
//=multiLine
Returns Feature<MultiLineString> a MultiLineString feature
Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.
Parameters
coordinates Array<Array<number>> an array of Positionsproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var multiPt = turf.multiPoint([[0,0],[10,10]]);
//=multiPt
Returns Feature<MultiPoint> a MultiPoint feature
Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.
Parameters
coordinates Array<Array<Array<Array<number>>>> an array of Polygonsproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
//=multiPoly
Returns Feature<MultiPolygon> a multipolygon feature
Creates a Feature<GeometryCollection> based on a coordinate array. Properties can be added optionally.
Parameters
geometries Array<Geometry> an array of GeoJSON Geometriesproperties Object an Object of key-value pairs to add as properties (optional, default {})options Object Optional Parameters (optional, default {})
Examples
var pt = {
"type": "Point",
"coordinates": [100, 0]
};
var line = {
"type": "LineString",
"coordinates": [ [101, 0], [102, 1] ]
};
var collection = turf.geometryCollection([pt, line]);
//=collection
Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature
Round number to precision
Parameters
Examples
turf.round(120.4321)
//=120
turf.round(120.4321, 2)
//=120.43
Returns number 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
Parameters
radians number in radians across the sphereunits string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default 'kilometers')Returns number 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
Parameters
distance number in real unitsunits string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default 'kilometers')Returns number 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
Parameters
distance number in real unitsunits string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default 'kilometers')Returns number 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
Parameters
bearing number angle, between -180 and +180 degreesReturns number angle between 0 and 360 degrees
Converts an angle in radians to degrees
Parameters
radians number angle in radiansReturns number degrees between 0 and 360 degrees
Converts an angle in degrees to radians
Parameters
degrees number angle between 0 and 360 degreesReturns number angle in radians
Converts a length to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
Parameters
length number to be convertedoriginalUnit string of the lengthfinalUnit string returned unit (optional, default 'kilometers')Returns number the converted length
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 string of the distance (optional, default 'meters')finalUnit string returned unit (optional, default 'kilometers')Returns number the converted distance
isNumber
Parameters
num any Number to validateExamples
turf.isNumber(123)
//=true
turf.isNumber('foo')
//=false
Returns boolean true/false
isObject
Parameters
input any variable to validateExamples
turf.isObject({elevation: 10})
//=true
turf.isObject('foo')
//=false
Returns boolean true/false
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 module individually:
$ npm install @turf/helpers
Or install the Turf module that includes it as a function:
$ npm install @turf/turf
6.4.0
@turf/boolean-point-on-line Added an epislon option to help in floating point comparison.
(PR https://github.com/Turfjs/turf/pull/2051 - Author @okcoker)@turf/line-slice-along Fixed a bug where the offset distance equal to the length of the line
(PR https://github.com/Turfjs/turf/pull/2030 - Author @EricPKerr)
@turf/helpers Fixed the conversion ratio for converting meters to yards and vice-versa
(PR https://github.com/Turfjs/turf/pull/2046 - Author @anotherhale)
@turf/center-median Fixed a missing TS type import
(PR https://github.com/Turfjs/turf/pull/2044 - Author @Seairth)
`@turf/bezier-spline Fix a bug ensuring the spline result reaches the end of the input (PR https://github.com/Turfjs/turf/pull/2090 - Author @the-nemz)
@turf/transform-rotate and @turf/ellipse) Improve documentation for angle parameter
(PR https://github.com/Turfjs/turf/pull/2016 - Author @pasieronen)
@turf/line-chunk Fix an invalid anchor
(PR https://github.com/Turfjs/turf/pull/2071 - Author @GraxMonzo)
@turf/distance Enhance distance doco so supported inputs are clearer
(PR https://github.com/Turfjs/turf/pull/2032 - Author @rowanwins)
@turf/concave Replace deprecated topojson dependency
(PR https://github.com/Turfjs/turf/pull/2037 - Author @elliots)
Work towards enabling TS Strict Mode (PR https://github.com/Turfjs/turf/pull/2053 - Author @mfedderly)
FAQs
turf helpers module
The npm package @turf/helpers receives a total of 2,401,400 weekly downloads. As such, @turf/helpers popularity was classified as popular.
We found that @turf/helpers demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.