@turf/helpers

What is @turf/helpers?

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.

What are @turf/helpers's main functionalities?

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]]]);

Other packages similar to @turf/helpers

leaflet

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

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.

README

@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 Feature
  • options.id (string | number)? Identifier associated with the Feature

Examples

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

var feature = turf.feature(geometry);

//=feature

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 Type
• coordinates Array<any> Coordinates
• options 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

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 Feature
  • options.id (string | number)? Identifier associated with the Feature

Examples

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

//=point

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 FeatureCollection
  • options.id (string | number)? Identifier associated with the FeatureCollection

Examples

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

//=points

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 Feature
  • options.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' });

//=polygon

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 Feature
  • options.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]]],
]);

//=polygons

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 Feature
  • options.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'});

//=linestring1
//=linestring2

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 FeatureCollection
  • options.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]]
]);

//=linestrings

Returns FeatureCollection<LineString> LineString FeatureCollection

featureCollection

Takes one or more Features and creates a FeatureCollection.

Parameters

• features Array<Feature> input features

• options Object Optional Parameters (optional, default {})

  • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
  • options.id (string | number)? Identifier associated with the Feature

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

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 Feature
  • options.id (string | number)? Identifier associated with the Feature

Examples

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

//=multiLine

• 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 Feature
  • options.id (string | number)? Identifier associated with the Feature

Examples

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

//=multiPt

• 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 Feature
  • options.id (string | number)? Identifier associated with the Feature

Examples

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

//=multiPoly

• 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 Feature
  • options.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]);

// => collection

Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature

round

Round number to precision

Parameters

• num number Number
• precision number Precision (optional, default 0)

Examples

turf.round(120.4321)
//=120

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

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 sphere
• units 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 units
• units 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 units
• units 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 converted
• originalUnit 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 converted
• originalUnit 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)
//=true
turf.isNumber('foo')
//=false

Returns boolean true/false

isObject

isObject

Parameters

• input any variable to validate

Examples

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

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