TURF

Measurement

npm install @turf/along

along

Takes a line and returns a point at a specified distance along the line.

Arguments

Argument Type Description
line Feature<LineString> input line
distance number distance along the line
units [string] (default kilometers) can be degrees, radians, miles, or kilometers

Returns

Feature<Point>: Point distance units along the line

Example

var line = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [-77.031669, 38.878605],
      [-77.029609, 38.881946],
      [-77.020339, 38.884084],
      [-77.025661, 38.885821],
      [-77.021884, 38.889563],
      [-77.019824, 38.892368]
    ]
  }
};

var along = turf.along(line, 1, 'miles');
//=along

npm install @turf/area

area

Takes one or more features and returns their area in square meters.

Arguments

Argument Type Description
geojson (FeatureCollection | Feature<any>) input GeoJSON feature(s)

Returns

number: area in square meters

Example

var polygon = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [125, -15],
        [113, -22],
        [117, -37],
        [130, -33],
        [148, -39],
        [154, -27],
        [144, -15],
        [125, -15]
      ]
    ]
  }
}
var area = turf.area(polygon);
//=area => square meters
//=polygon

npm install @turf/bbox

bbox

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Arguments

Argument Type Description
geojson (Feature | FeatureCollection) input features

Returns

Array<number>: bbox extent in [minX, minY, maxX, maxY] order

Example

var pt1 = turf.point([114.175329, 22.2524])
var pt2 = turf.point([114.170007, 22.267969])
var pt3 = turf.point([114.200649, 22.274641])
var pt4 = turf.point([114.200649, 22.274641])
var pt5 = turf.point([114.186744, 22.265745])
var features = turf.featureCollection([pt1, pt2, pt3, pt4, pt5])

var bbox = turf.bbox(features);

var bboxPolygon = turf.bboxPolygon(bbox);

//=bbox

//=bboxPolygon

npm install @turf/bbox-polygon

bboxPolygon

Takes a bbox and returns an equivalent polygon.

Arguments

Argument Type Description
bbox Array<number> extent in [minX, minY, maxX, maxY] order

Returns

Feature<Polygon>: a Polygon representation of the bounding box

Example

var bbox = [0, 0, 10, 10];

var poly = turf.bboxPolygon(bbox);

//=poly

npm install @turf/bearing

bearing

Takes two points and finds the geographic bearing between them.

Arguments

Argument Type Description
start Feature<Point> starting Point
end Feature<Point> ending Point
final [boolean] (default false) calculates the final bearing if true

Returns

number: bearing in decimal degrees

Example

var point1 = {
  "type": "Feature",
  "properties": {
    "marker-color": '#f00'
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-75.343, 39.984]
  }
};
var point2 = {
  "type": "Feature",
  "properties": {
    "marker-color": '#0f0'
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-75.534, 39.123]
  }
};

var bearing = turf.bearing(point1, point2);
point1.properties.bearing = bearing
//=bearing

npm install @turf/center

center

Takes a Feature or FeatureCollection and returns the absolute center point of all features.

Arguments

Argument Type Description
layer (Feature | FeatureCollection) input features

Returns

Feature<Point>: a Point feature at the absolute center point of all input features

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.522259, 35.4691]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.502754, 35.463455]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.508269, 35.463245]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.516809, 35.465779]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.515372, 35.467072]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.509363, 35.463053]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.511123, 35.466601]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.518547, 35.469327]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.519706, 35.469659]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.517839, 35.466998]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.508678, 35.464942]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-97.514914, 35.463453]
      }
    }
  ]
};

var centerPt = turf.center(features);
centerPt.properties['marker-size'] = 'large';
centerPt.properties['marker-color'] = '#000';

var resultFeatures = features.features.concat(centerPt);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

npm install @turf/center-of-mass

centerOfMass

Takes a feature or a featureCollection and returns its center of mass using this formula: Centroid of Polygon.

Arguments

Argument Type Description
fc (FeatureCollection | Feature) the feature collection or feature

Returns

Feature<Point>: the center of mass

Example

var feature = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          4.854240417480469,
          45.77258200374433
        ],
        [
          4.8445844650268555,
          45.777431068484894
        ],
        [
          4.845442771911621,
          45.778658234059755
        ],
        [
          4.845914840698242,
          45.779376562352425
        ],
        [
          4.846644401550292,
          45.78021460033108
        ],
        [
          4.847245216369629,
          45.78078326178593
        ],
        [
          4.848060607910156,
          45.78138184652523
        ],
        [
          4.8487043380737305,
          45.78186070968964
        ],
        [
          4.849562644958495,
          45.78248921135124
        ],
        [
          4.850893020629883,
          45.78302792142197
        ],
        [
          4.852008819580077,
          45.78374619341895
        ],
        [
          4.852995872497559,
          45.784075398324866
        ],
        [
          4.853854179382324,
          45.78443452873236
        ],
        [
          4.8549699783325195,
          45.78470387501975
        ],
        [
          4.85569953918457,
          45.784793656826345
        ],
        [
          4.857330322265624,
          45.784853511283764
        ],
        [
          4.858231544494629,
          45.78494329284938
        ],
        [
          4.859304428100585,
          45.784883438488365
        ],
        [
          4.858360290527344,
          45.77294120818474
        ],
        [
          4.854240417480469,
          45.77258200374433
        ]
      ]
    ]
  }
};

var centerOfMass = turf.centerOfMass(feature);

//=centerOfMass

npm install @turf/centroid

centroid

Takes one or more features and calculates the centroid using the mean of all vertices. This lessens the effect of small islands and artifacts when calculating the centroid of a set of polygons.

Arguments

Argument Type Description
features (Feature | FeatureCollection) input features

Returns

Feature<Point>: the centroid of the input features

Example

var poly = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [105.818939,21.004714],
      [105.818939,21.061754],
      [105.890007,21.061754],
      [105.890007,21.004714],
      [105.818939,21.004714]
    ]]
  }
};

var centroidPt = turf.centroid(poly);

var result = {
  "type": "FeatureCollection",
  "features": [poly, centroidPt]
};

//=result

npm install @turf/destination

destination

Takes a Point and calculates the location of a destination point given a distance in degrees, radians, miles, or kilometers; and bearing in degrees. This uses the Haversine formula to account for global curvature.

Arguments

Argument Type Description
from Feature<Point> starting point
distance number distance from the starting point
bearing number ranging from -180 to 180
units [string] (default kilometers) miles, kilometers, degrees, or radians

Returns

Feature<Point>: destination point

Example

var point = {
  "type": "Feature",
  "properties": {
    "marker-color": "#0f0"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-75.343, 39.984]
  }
};
var distance = 50;
var bearing = 90;
var units = 'miles';

var destination = turf.destination(point, distance, bearing, units);
destination.properties['marker-color'] = '#f00';

var result = {
  "type": "FeatureCollection",
  "features": [point, destination]
};

//=result

npm install @turf/distance

distance

Calculates the distance between two points in degrees, radians, miles, or kilometers. This uses the Haversine formula to account for global curvature.

Arguments

Argument Type Description
from Feature<Point> origin point
to Feature<Point> destination point
units [string] (default kilometers) can be degrees, radians, miles, or kilometers

Returns

number: distance between the two points

Example

var from = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-75.343, 39.984]
  }
};
var to = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-75.534, 39.123]
  }
};
var units = "miles";

var points = {
  "type": "FeatureCollection",
  "features": [from, to]
};

//=points

var distance = turf.distance(from, to, units);

//=distance

npm install @turf/envelope

envelope

Takes any number of features and returns a rectangular Polygon that encompasses all vertices.

Arguments

Argument Type Description
features (Feature | FeatureCollection) input features

Returns

Feature<Polygon>: a rectangular Polygon feature that encompasses all vertices

Example

var fc = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Location A"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-75.343, 39.984]
      }
    }, {
      "type": "Feature",
      "properties": {
        "name": "Location B"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-75.833, 39.284]
      }
    }, {
      "type": "Feature",
      "properties": {
        "name": "Location C"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-75.534, 39.123]
      }
    }
  ]
};

var enveloped = turf.envelope(fc);

var resultFeatures = fc.features.concat(enveloped);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

npm install @turf/line-distance

lineDistance

Takes a LineString or Polygon and measures its length in the specified units.

Arguments

Argument Type Description
geojson (Feature<(LineString | Polygon)> | FeatureCollection<(LineString | Polygon)>) feature to measure
units [string] (default kilometers) can be degrees, radians, miles, or kilometers

Returns

number: length feature

Example

var line = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [-77.031669, 38.878605],
      [-77.029609, 38.881946],
      [-77.020339, 38.884084],
      [-77.025661, 38.885821],
      [-77.021884, 38.889563],
      [-77.019824, 38.892368]
    ]
  }
};

var length = turf.lineDistance(line, 'miles');

//=line

//=length

npm install @turf/midpoint

midpoint

Takes two points and returns a point midway between them. The midpoint is calculated geodesically, meaning the curvature of the earth is taken into account.

Arguments

Argument Type Description
from Feature<Point> first point
to Feature<Point> second point

Returns

Feature<Point>: a point midway between pt1 and pt2

Example

var pt1 = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [144.834823, -37.771257]
  }
};
var pt2 = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [145.14244, -37.830937]
  }
};

var midpointed = turf.midpoint(pt1, pt2);
midpointed.properties['marker-color'] = '#f00';


var result = {
  "type": "FeatureCollection",
  "features": [pt1, pt2, midpointed]
};

//=result

npm install @turf/point-on-surface

pointOnSurface

Takes a feature and returns a Point guaranteed to be on the surface of the feature.

  • Given a Polygon, the point will be in the area of the polygon
  • Given a LineString, the point will be along the string
  • Given a Point, the point will the same as the input

Arguments

Argument Type Description
fc (Feature | FeatureCollection) any feature or set of features

Returns

Feature: a point on the surface of input

Example

// create a random polygon
var polygon = turf.random('polygon');

//=polygon

var pointOnPolygon = turf.pointOnSurface(polygon);

var resultFeatures = polygon.features.concat(pointOnPolygon);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

npm install @turf/square

square

Takes a bounding box and calculates the minimum square bounding box that would contain the input.

Arguments

Argument Type Description
bbox Array<number> extent in [west, south, east, north] order

Returns

Array<number>: a square surrounding bbox

Example

var bbox = [-20,-20,-15,0];

var squared = turf.square(bbox);

var features = {
  "type": "FeatureCollection",
  "features": [
    turf.bboxPolygon(bbox),
    turf.bboxPolygon(squared)
  ]
};

//=features

npm install @turf/great-circle

greatCircle

Calculate great circles routes as LineString

Arguments

Argument Type Description
start Feature<Point> source point feature
end Feature<Point> destination point feature
properties [Any] (default {}) line feature properties
npoints [number] (default 100) number of points
offset [number] (default 10) offset controls the likelyhood that lines will be split which cross the dateline. The higher the number the more likely.

Returns

Feature<LineString>: great circle line feature

Example

var start = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-122, 48]
  }
}
var end = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-77, 39]
  }
}
var line = turf.greatCircle(start, end, {'name': 'Seattle to DC'});
//=line

Transformation

npm install @turf/bezier

bezier

Takes a line and returns a curved version by applying a Bezier spline algorithm.

The bezier spline implementation is by Leszek Rybicki.

Arguments

Argument Type Description
line Feature<LineString> input LineString
resolution [number] (default 10000) time in milliseconds between points
sharpness [number] (default 0.85) a measure of how curvy the path should be between splines

Returns

Feature<LineString>: curved line

Example

var line = {
  "type": "Feature",
  "properties": {
    "stroke": "#f00"
  },
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [-76.091308, 18.427501],
      [-76.695556, 18.729501],
      [-76.552734, 19.40443],
      [-74.61914, 19.134789],
      [-73.652343, 20.07657],
      [-73.157958, 20.210656]
    ]
  }
};

var curved = turf.bezier(line);
curved.properties = { stroke: '#0f0' };

//=curved

npm install @turf/buffer

buffer

Calculates a buffer for input features for a given radius. Units supported are miles, kilometers, and degrees.

Arguments

Argument Type Description
feature (Feature | FeatureCollection) input to be buffered
radius number distance to draw the buffer
units string any of the options supported by turf units

Returns

(FeatureCollection<Polygon> | FeatureCollection<MultiPolygon> | Polygon | MultiPolygon): buffered features

Example

var pt = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-90.548630, 14.616599]
  }
};
var unit = 'miles';

var buffered = turf.buffer(pt, 500, unit);

//=buffered

npm install @turf/circle

circle

Takes a Point and calculates the circle polygon given a radius in degrees, radians, miles, or kilometers; and steps for precision.

Arguments

Argument Type Description
center Feature<Point> center point
radius number radius of the circle
steps [number] (default 64) number of steps
units [string] (default kilometers) miles, kilometers, degrees, or radians

Returns

Feature<Polygon>: circle polygon

Example

var center = turf.point([-75.343, 39.984]);
var radius = 5;
var steps = 10;
var units = 'kilometers';

var circle = turf.circle(center, radius, steps, units);

//=circle

npm install @turf/concave

concave

Takes a set of points and returns a concave hull polygon.

Internally, this uses turf-tin to generate geometries.

Arguments

Argument Type Description
points FeatureCollection<Point> input points
maxEdge number the size of an edge necessary for part of the hull to become concave (in miles)
units [string] (default kilometers) can be degrees, radians, miles, or kilometers

Returns

Feature<Polygon>: a concave hull

Throws

Error: if maxEdge parameter is missing or unable to compute hull

Example

var points = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-63.601226, 44.642643]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-63.591442, 44.651436]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-63.580799, 44.648749]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-63.573589, 44.641788]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-63.587665, 44.64533]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-63.595218, 44.64765]
      }
    }
  ]
};

var hull = turf.concave(points, 1, 'miles');

var resultFeatures = points.features.concat(hull);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

npm install @turf/convex

convex

Takes a Feature or a FeatureCollection and returns a convex hull Polygon.

Internally this uses the convex-hull module that implements a monotone chain hull.

Arguments

Argument Type Description
feature (Feature | FeatureCollection) input Feature or FeatureCollection

Returns

Feature<Polygon>: a convex hull

Example

var points = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [10.195312, 43.755225]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [10.404052, 43.8424511]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [10.579833, 43.659924]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [10.360107, 43.516688]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [10.14038, 43.588348]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [10.195312, 43.755225]
      }
    }
  ]
};

var hull = turf.convex(points);

var resultFeatures = points.features.concat(hull);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

npm install @turf/difference

difference

Finds the difference between two polygons by clipping the second polygon from the first.

Arguments

Argument Type Description
p1 Feature<Polygon> input Polygon feature
p2 Feature<Polygon> Polygon feature to difference from p1

Returns

Feature<(Polygon | MultiPolygon)>: a Polygon or MultiPolygon feature showing the area of p1 excluding the area of p2

Example

var poly1 = {
  "type": "Feature",
  "properties": {
    "fill": "#0f0"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-46.738586, -23.596711],
      [-46.738586, -23.458207],
      [-46.560058, -23.458207],
      [-46.560058, -23.596711],
      [-46.738586, -23.596711]
    ]]
  }
};
var poly2 = {
  "type": "Feature",
  "properties": {
    "fill": "#00f"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-46.650009, -23.631314],
      [-46.650009, -23.5237],
      [-46.509246, -23.5237],
      [-46.509246, -23.631314],
      [-46.650009, -23.631314]
    ]]
  }
};

var differenced = turf.difference(poly1, poly2);
differenced.properties.fill = '#f00';

var polygons = {
  "type": "FeatureCollection",
  "features": [poly1, poly2]
};

//=polygons

//=differenced

npm install @turf/dissolve

dissolve

Dissolves a FeatureCollection of polygons based on a property. Note that multipart features within the collection are not supported

Arguments

Argument Type Description
featureCollection FeatureCollection<Polygon> input feature collection to be dissolved
propertyName [string] property name on which to dissolve features

Returns

FeatureCollection<Polygon>: a FeatureCollection containing the dissolved polygons

Example

var features = {
"type": "FeatureCollection",
"features": [
  {
    "type": "Feature",
    "properties": {
      "combine": "yes"
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]]
    }
  },
  {
    "type": "Feature",
    "properties": {
      "combine": "yes"
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[0, -1], [0, 0], [1, 0], [1, -1], [0,-1]]]
    }
  },
  {
    "type": "Feature",
    "properties": {
      "combine": "no"
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[1,-1],[1, 0], [2, 0], [2, -1], [1, -1]]]
    }
  }
 ]
}

var dissolved = turf.dissolve(features, 'combine');

//=dissolved

npm install @turf/intersect

intersect

Takes two polygons and finds their intersection. If they share a border, returns the border; if they don't intersect, returns undefined.

Arguments

Argument Type Description
poly1 Feature<Polygon> the first polygon
poly2 Feature<Polygon> the second polygon

Returns

(Feature | undefined): returns a feature representing the point(s) they share (in case of a Point or MultiPoint ), the borders they share (in case of a LineString or a MultiLineString ), the area they share (in case of Polygon or MultiPolygon ). If they do not share any point, returns undefined .

Example

var poly1 = turf.polygon([[
  [-122.801742, 45.48565],
  [-122.801742, 45.60491],
  [-122.584762, 45.60491],
  [-122.584762, 45.48565],
  [-122.801742, 45.48565]
]]);

var poly2 = turf.polygon([[
  [-122.520217, 45.535693],
  [-122.64038, 45.553967],
  [-122.720031, 45.526554],
  [-122.669906, 45.507309],
  [-122.723464, 45.446643],
  [-122.532577, 45.408574],
  [-122.487258, 45.477466],
  [-122.520217, 45.535693]
]]);

var intersection = turf.intersect(poly1, poly2);

//=intersection

npm install @turf/simplify

simplify

Takes a LineString or Polygon and returns a simplified version. Internally uses simplify-js to perform simplification.

Arguments

Argument Type Description
feature (Feature<(LineString | Polygon | MultiLineString | MultiPolygon)> | FeatureCollection | GeometryCollection) feature to be simplified
tolerance [number] (default 1) simplification tolerance
highQuality [boolean] (default false) whether or not to spend more time to create a higher-quality simplification with a different algorithm

Returns

(Feature<(LineString | Polygon | MultiLineString | MultiPolygon)> | FeatureCollection | GeometryCollection): a simplified feature

Example

var feature = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-70.603637, -33.399918],
      [-70.614624, -33.395332],
      [-70.639343, -33.392466],
      [-70.659942, -33.394759],
      [-70.683975, -33.404504],
      [-70.697021, -33.419406],
      [-70.701141, -33.434306],
      [-70.700454, -33.446339],
      [-70.694274, -33.458369],
      [-70.682601, -33.465816],
      [-70.668869, -33.472117],
      [-70.646209, -33.473835],
      [-70.624923, -33.472117],
      [-70.609817, -33.468107],
      [-70.595397, -33.458369],
      [-70.587158, -33.442901],
      [-70.587158, -33.426283],
      [-70.590591, -33.414248],
      [-70.594711, -33.406224],
      [-70.603637, -33.399918]
    ]]
  }
};

var tolerance = 0.01;

var simplified = turf.simplify(
 feature, tolerance, false);

//=feature

//=simplified

npm install @turf/tesselate

tesselate

Tesselates a Feature<Polygon> into a FeatureCollection<Polygon> of triangles using earcut.

Arguments

Argument Type Description
poly Feature<Polygon> the polygon to tesselate

Returns

FeatureCollection<Polygon>: a geometrycollection feature

Example

var poly = turf.random('polygon').features[0];

var triangles = turf.tesselate(poly);

//=triangles

npm install @turf/union

union

Takes two or more polygons and returns a combined polygon. If the input polygons are not contiguous, this function returns a MultiPolygon feature.

Arguments

Argument Type Description
A ...Feature<Polygon> polygon to combine

Returns

Feature<(Polygon | MultiPolygon)>: a combined Polygon or MultiPolygon feature

Example

var poly1 = {
  "type": "Feature",
  "properties": {
    "fill": "#0f0"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-82.574787, 35.594087],
      [-82.574787, 35.615581],
      [-82.545261, 35.615581],
      [-82.545261, 35.594087],
      [-82.574787, 35.594087]
    ]]
  }
};
var poly2 = {
  "type": "Feature",
  "properties": {
    "fill": "#00f"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-82.560024, 35.585153],
      [-82.560024, 35.602602],
      [-82.52964, 35.602602],
      [-82.52964, 35.585153],
      [-82.560024, 35.585153]
    ]]
  }
};
var polygons = {
  "type": "FeatureCollection",
  "features": [poly1, poly2]
};

var union = turf.union(poly1, poly2);

//=polygons

//=union

Misc

npm install @turf/combine

combine

Combines a FeatureCollection of Point, LineString, or Polygon features into MultiPoint, MultiLineString, or MultiPolygon features.

Arguments

Argument Type Description
fc FeatureCollection<(Point | LineString | Polygon)> a FeatureCollection of any type

Returns

FeatureCollection<(MultiPoint | MultiLineString | MultiPolygon)>: a FeatureCollection of corresponding type to input

Example

var fc = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [19.026432, 47.49134]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [19.074497, 47.509548]
      }
    }
  ]
};

var combined = turf.combine(fc);

//=combined

npm install @turf/explode

explode

Takes a feature or set of features and returns all positions as points.

Arguments

Argument Type Description
geojson (Feature | FeatureCollection) input features

Returns

FeatureCollection<point>: points representing the exploded input features

Throws

Error: if it encounters an unknown geometry type

Example

var poly = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [177.434692, -17.77517],
      [177.402076, -17.779093],
      [177.38079, -17.803937],
      [177.40242, -17.826164],
      [177.438468, -17.824857],
      [177.454948, -17.796746],
      [177.434692, -17.77517]
    ]]
  }
};

var points = turf.explode(poly);

//=poly

//=points

npm install @turf/flatten

flatten

Flattens any GeoJSON to a FeatureCollection inspired by geojson-flatten.

Arguments

Argument Type Description
geojson Feature any valid GeoJSON with multi-geometry Feature s

Returns

FeatureCollection: a flattened FeatureCollection

Example

var geometry = {
  "type": "MultiPolygon",
  "coordinates": [
    [[[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]]],
     [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]],
     [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]]]
   ]
 };

var flattened = turf.flatten(geometry);

//=flattened

npm install @turf/flip

flip

Takes input features and flips all of their coordinates from [x, y] to [y, x].

Arguments

Argument Type Description
input (Feature | FeatureCollection) input features

Returns

(Feature | FeatureCollection): a feature or set of features of the same type as input with flipped coordinates

Example

var serbia = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [20.566406, 43.421008]
  }
};

//=serbia

var saudiArabia = turf.flip(serbia);

//=saudiArabia

npm install @turf/kinks

kinks

Takes a linestring, multi-linestring, multi-polygon, or polygon and returns points at all self-intersections.

Arguments

Argument Type Description
featureIn Feature<(LineString | MultiLineString | MultiPolygon | Polygon)> input feature

Returns

FeatureCollection<Point>: self-intersections

Example

var poly = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-12.034835, 8.901183],
      [-12.060413, 8.899826],
      [-12.03638, 8.873199],
      [-12.059383, 8.871418],
      [-12.034835, 8.901183]
    ]]
  }
};

var kinks = turf.kinks(poly);

var resultFeatures = kinks.features.concat(poly);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

npm install @turf/line-chunk

lineChunk

Divides a LineString into chunks of a specified length. If the line is shorter than the segment length then the original line is returned.

Arguments

Argument Type Description
featureIn (FeatureCollection | Feature<(LineString | MultiLineString)>) the lines to split
segmentLength number how long to make each segment
units [string] (default 'kilometers') units can be degrees, radians, miles, or kilometers
reverse [boolean] (default false) reverses coordinates to start the first chunked segment at the end

Returns

FeatureCollection<LineString>: collection of line segments

Example

var line = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [-95, 40],
      [-93, 45],
      [-85, 50]
    ]
  }
};
var result = turf.lineChunk(line, 15, 'miles');
//=result

npm install @turf/line-intersect

lineIntersect

Takes any LineString or Polygon GeoJSON and returns the intersecting point(s).

Arguments

Argument Type Description
line1 (FeatureCollection | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) any LineString or Polygon
line2 (FeatureCollection | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) any LineString or Polygon

Returns

FeatureCollection<Point>: point(s) that intersect both

Example

var line1 = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [126, -11],
      [129, -21]
    ]
  }
};
var line2 = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [123, -18],
      [131, -14]
    ]
  }
};
var points = turf.lineIntersect(line1, line2);
//= points

npm install @turf/line-slice

lineSlice

Takes a line, a start Point, and a stop point and returns a subsection of the line in-between those points. The start & stop points don't need to fall exactly on the line.

This can be useful for extracting only the part of a route between waypoints.

Arguments

Argument Type Description
startPt Feature<Point> starting point
stopPt Feature<Point> stopping point
line (Feature<LineString> | LineString) line to slice

Returns

Feature<LineString>: sliced line

Example

var line = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [-77.031669, 38.878605],
      [-77.029609, 38.881946],
      [-77.020339, 38.884084],
      [-77.025661, 38.885821],
      [-77.021884, 38.889563],
      [-77.019824, 38.892368]
    ]
  }
};
var start = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-77.029609, 38.881946]
  }
};
var stop = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-77.021884, 38.889563]
  }
};

var sliced = turf.lineSlice(start, stop, line);

//=line

//=sliced

npm install @turf/line-slice-along

lineSliceAlong

Takes a line, a specified distance along the line to a start Point, and a specified distance along the line to a stop point and returns a subsection of the line in-between those points.

This can be useful for extracting only the part of a route between two distances.

Arguments

Argument Type Description
line (Feature<LineString> | LineString) input line
startDist number distance along the line to starting point
stopDist number distance along the line to ending point
units [string] (default kilometers) can be degrees, radians, miles, or kilometers

Returns

Feature<LineString>: sliced line

Example

var line = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [ 7.66845703125, 45.058001435398296 ],
      [ 9.20654296875, 45.460130637921004 ],
      [ 11.348876953125, 44.48866833139467 ],
      [ 12.1728515625, 45.43700828867389 ],
      [ 12.535400390625, 43.98491011404692 ],
      [ 12.425537109375, 41.86956082699455 ],
      [ 14.2437744140625, 40.83874913796459 ],
      [ 14.765625, 40.681679458715635 ]
    ]
  }
};
var start = 12.5;

var stop = 25;

var units = 'miles';

var sliced = turf.lineSliceAlong(line, start, stop, units);

//=line

//=sliced

npm install @turf/line-segment

lineSegment

Creates a FeatureCollection of 2-vertex LineString segments from a LineString, MultiLineString, MultiPolygon or Polygon.

Arguments

Argument Type Description
geojson Feature<(LineString | MultiLineString | MultiPolygon | Polygon)> input GeoJSON Feature

Returns

FeatureCollection<LineString>: 2-vertex line segments

Example

var polygon = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[-50, 5], [-40, -10], [-50, -10], [-40, 5], [-50, 5]]]
  }
}
var segments = turf.lineSegment(polygon);
//=segments

npm install @turf/mask

mask

Takes any type of polygon and an optional mask and returns a polygon exterior ring with holes.

Arguments

Argument Type Description
polygon (FeatureCollection | Feature<(Polygon | MultiPolygon)>) GeoJSON Polygon used as interior rings or holes.
mask [Feature<Polygon>] GeoJSON Polygon used as the exterior ring (if undefined, the world extent is used)

Returns

Feature<Polygon>: Masked Polygon (exterior ring with holes).

Example

var polygon = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[112, -21], [116, -36], [146, -39], [153, -24], [133, -10], [112, -21]]]
  }
}
var mask = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[90, -55], [170, -55], [170, 10], [90, 10], [90, -55]]]
  }
}
var masked = turf.mask(polygon, mask);
//=masked

npm install @turf/point-on-line

pointOnLine

Takes a Point and a LineString and calculates the closest Point on the LineString.

Arguments

Argument Type Description
line Feature<LineString> line to snap to
pt Feature<Point> point to snap from
units [string] (default kilometers) can be degrees, radians, miles, or kilometers

Returns

Feature<Point>: closest point on the line to point . The properties object will contain three values: index : closest point was found on nth line part, dist : distance between pt and the closest point, location : distance along the line between start and the closest point.

Example

var line = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [-77.031669, 38.878605],
      [-77.029609, 38.881946],
      [-77.020339, 38.884084],
      [-77.025661, 38.885821],
      [-77.021884, 38.889563],
      [-77.019824, 38.892368]
    ]
  }
};
var pt = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-77.037076, 38.884017]
  }
};

var snapped = turf.pointOnLine(line, pt, 'miles');
snapped.properties['marker-color'] = '#00f'

var result = {
  "type": "FeatureCollection",
  "features": [line, pt, snapped]
};

//=result

npm install @turf/truncate

truncate

Takes a GeoJSON Feature or FeatureCollection and truncates the precision of the geometry.

Arguments

Argument Type Description
layer (Feature | FeatureCollection) any GeoJSON Feature or FeatureCollection
precision [number] (default 6) coordinate decimal precision
coordinates [number] (default 2) maximum number of coordinates (primarly used to remove z coordinates)

Returns

(Feature | FeatureCollection): layer with truncated geometry

Example

var point = {
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            70.46923055566859,
            58.11088890802906,
            1508
        ]
    },
    "properties": {}
};
var pointTrunc = turf.truncate(point);
//= pointTrunc

npm install @turf/unkink-polygon

unkinkPolygon

Takes a kinked polygon and returns a feature collection of polygons that have no kinks. Uses simplepolygon internally.

Arguments

Argument Type Description
geojson (FeatureCollection | Feature<(Polygon | MultiPolygon)>) GeoJSON Polygon or MultiPolygon

Returns

FeatureCollection<Polygon>: Unkinked polygons

Example

var poly = {
   'type': 'Feature',
     'geometry': {
        'type': 'Polygon',
       'coordinates': [[[0, 0], [2, 0], [0, 2], [2, 2], [0, 0]]]
      }
};

var result = turf.unkinkPolygon(poly);

//=result

Helper

npm install @turf/helpers

featureCollection

Takes one or more Features and creates a FeatureCollection.

Note: featureCollection is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the featureCollection method.

Arguments

Argument Type Description
features Array<Feature> input features

Returns

FeatureCollection: a FeatureCollection of input features

Example

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

var fc = turf.featureCollection(features);

//=fc

npm install @turf/helpers

feature

Wraps a GeoJSON Geometry in a GeoJSON Feature.

Note: feature is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the feature method.

Arguments

Argument Type Description
geometry Geometry input geometry
properties Object properties

Returns

FeatureCollection: a FeatureCollection of input features

Example

var geometry = {
     "type": "Point",
     "coordinates": [
       67.5,
       32.84267363195431
     ]
   }

var feature = turf.feature(geometry);

//=feature

npm install @turf/helpers

geometryCollection

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

Note: geometryCollection is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the geometryCollection method.

Arguments

Argument Type Description
geometries Array<{Geometry}> an array of GeoJSON Geometries
properties [Object] an Object of key-value pairs to add as properties

Returns

Feature<GeometryCollection>: a GeoJSON GeometryCollection Feature

Example

var pt = {
    "type": "Point",
      "coordinates": [100, 0]
    };
var line = {
    "type": "LineString",
    "coordinates": [ [101, 0], [102, 1] ]
  };
var collection = turf.geometryCollection([pt, line]);

//=collection

npm install @turf/helpers

lineString

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

Note: lineString is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the lineString method.

Arguments

Argument Type Description
coordinates Array<Array<number>> an array of Positions
properties [Object] an Object of key-value pairs to add as properties

Returns

Feature<LineString>: a LineString feature

Throws

Error: if no coordinates are passed

Example

var linestring1 = turf.lineString([
  [-21.964416, 64.148203],
  [-21.956176, 64.141316],
  [-21.93901, 64.135924],
  [-21.927337, 64.136673]
]);
var linestring2 = turf.lineString([
  [-21.929054, 64.127985],
  [-21.912918, 64.134726],
  [-21.916007, 64.141016],
  [-21.930084, 64.14446]
], {name: 'line 1', distance: 145});

//=linestring1

//=linestring2

npm install @turf/helpers

multiLineString

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

Note: multiLineString is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the multiLineString method.

Arguments

Argument Type Description
coordinates Array<Array<Array<number>>> an array of LineStrings
properties [Object] an Object of key-value pairs to add as properties

Returns

Feature<MultiLineString>: a MultiLineString feature

Throws

Error: if no coordinates are passed

Example

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

//=multiLine

npm install @turf/helpers

multiPoint

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

Note: multiPoint is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the multiPoint method.

Arguments

Argument Type Description
coordinates Array<Array<number>> an array of Positions
properties [Object] an Object of key-value pairs to add as properties

Returns

Feature<MultiPoint>: a MultiPoint feature

Throws

Error: if no coordinates are passed

Example

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

//=multiPt

npm install @turf/helpers

multiPolygon

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

Note: multiPolygon is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the multiPolygon method.

Arguments

Argument Type Description
coordinates Array<Array<Array<Array<number>>>> an array of Polygons
properties [Object] an Object of key-value pairs to add as properties

Returns

Feature<MultiPolygon>: a multipolygon feature

Throws

Error: if no coordinates are passed

Example

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

//=multiPoly

npm install @turf/helpers

point

Takes coordinates and properties (optional) and returns a new Point feature.

Note: point is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the point method.

Arguments

Argument Type Description
coordinates Array<number> longitude, latitude position (each in decimal degrees)
properties [Object] an Object that is used as the Feature 's properties

Returns

Feature<Point>: a Point feature

Example

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

//=pt1

npm install @turf/helpers

polygon

Takes an array of LinearRings and optionally an Object with properties and returns a Polygon feature.

Note: polygon is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the polygon method.

Arguments

Argument Type Description
coordinates Array<Array<Array<number>>> an array of LinearRings
properties [Object] a properties object

Returns

Feature<Polygon>: a Polygon feature

Throws

Error: throw an error if a LinearRing of the polygon has too few positions or if a LinearRing of the Polygon does not have matching Positions at the beginning & end.

Example

var polygon = turf.polygon([[
 [-2.275543, 53.464547],
 [-2.275543, 53.489271],
 [-2.215118, 53.489271],
 [-2.215118, 53.464547],
 [-2.275543, 53.464547]
]], { name: 'poly1', population: 400});

//=polygon

Data

npm install @turf/random

random

Generates random GeoJSON data, including Points and Polygons, for testing and experimentation.

Arguments

Argument Type Description
type [string] (default 'point') type of features desired: 'points' or 'polygons'
count [number] (default 1) how many geometries should be generated.
options Object options relevant to the feature desired. Can include:

Returns

FeatureCollection: generated random features

Example

var points = turf.random('points', 100, {
  bbox: [-70, 40, -60, 60]
});

//=points

var polygons = turf.random('polygons', 4, {
  bbox: [-70, 40, -60, 60]
});

//=polygons

npm install @turf/sample

sample

Takes a FeatureCollection and returns a FeatureCollection with given number of features at random.

Arguments

Argument Type Description
featurecollection FeatureCollection set of input features
num number number of features to select

Returns

FeatureCollection: a FeatureCollection with n features

Example

var points = turf.random('points', 1000);

//=points

var sample = turf.sample(points, 10);

//=sample

Interpolation

npm install @turf/isolines

isolines

Takes points with z-values and an array of value breaks and generates isolines.

Arguments

Argument Type Description
points FeatureCollection<Point> input points
z string the property name in points from which z-values will be pulled
resolution number resolution of the underlying grid
breaks Array<number> where to draw contours

Returns

FeatureCollection<LineString>: isolines

Example

// create random points with random
// z-values in their properties
var points = turf.random('point', 100, {
  bbox: [0, 30, 20, 50]
});
for (var i = 0; i < points.features.length; i++) {
  points.features[i].properties.z = Math.random() * 10;
}
var breaks = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
var isolined = turf.isolines(points, 'z', 15, breaks);
//=isolined

npm install @turf/planepoint

planepoint

Takes a triangular plane as a Polygon and a Point within that triangle and returns the z-value at that point. The Polygon needs to have properties a, b, and c that define the values at its three corners.

Arguments

Argument Type Description
point Feature<Point> the Point for which a z-value will be calculated
triangle Feature<Polygon> a Polygon feature with three vertices

Returns

number: the z-value for interpolatedPoint

Example

var point = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-75.3221, 39.529]
  }
};
var point = turf.point([-75.3221, 39.529]);
// triangle is a polygon with "a", "b",
// and "c" values representing
// the values of the coordinates in order.
var triangle = {
  "type": "Feature",
  "properties": {
    "a": 11,
    "b": 122,
    "c": 44
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-75.1221, 39.57],
      [-75.58, 39.18],
      [-75.97, 39.86],
      [-75.1221, 39.57]
    ]]
  }
};

var features = {
  "type": "FeatureCollection",
  "features": [triangle, point]
};

var zValue = turf.planepoint(point, triangle);

//=features

//=zValue

npm install @turf/tin

tin

Takes a set of points and the name of a z-value property and creates a Triangulated Irregular Network, or a TIN for short, returned as a collection of Polygons. These are often used for developing elevation contour maps or stepped heat visualizations.

This triangulates the points, as well as adds properties called a, b, and c representing the value of the given propertyName at each of the points that represent the corners of the triangle.

Arguments

Argument Type Description
points FeatureCollection<Point> input points
z [String] name of the property from which to pull z values This is optional: if not given, then there will be no extra data added to the derived triangles.

Returns

FeatureCollection<Polygon>: TIN output

Example

// generate some random point data
var points = turf.random('points', 30, {
  bbox: [50, 30, 70, 50]
});
//=points
// add a random property to each point between 0 and 9
for (var i = 0; i < points.features.length; i++) {
  points.features[i].properties.z = ~~(Math.random() * 9);
}
var tin = turf.tin(points, 'z')
for (var i = 0; i < tin.features.length; i++) {
  var properties  = tin.features[i].properties;
  // roughly turn the properties of each
  // triangle into a fill color
  // so we can visualize the result
  properties.fill = '#' + properties.a +
    properties.b + properties.c;
}
//=tin

npm install @turf/idw

idw

Takes a FeatureCollection of points with known value, a power parameter, a cell depth, a unit of measurement and returns a FeatureCollection of polygons in a square-grid with an interpolated value property "IDW" for each grid cell. It finds application when in need of creating a continuous surface (i.e. rainfall, temperature, chemical dispersion surface...) from a set of spatially scattered points.

Arguments

Argument Type Description
controlPoints FeatureCollection<Point> Sampled points with known value
valueField string GeoJSON field containing the known value to interpolate on
b number Exponent regulating the distance-decay weighting
cellWidth number The distance across each cell
units [string] (default kilometers) used in calculating cellSize, can be degrees, radians, miles, or kilometers

Returns

FeatureCollection<Polygon>: grid A grid of polygons with a property field "IDW"

Joins

npm install @turf/inside

inside

Takes a Point and a Polygon or MultiPolygon and determines if the point resides inside the polygon. The polygon can be convex or concave. The function accounts for holes.

Arguments

Argument Type Description
point Feature<Point> input point
polygon Feature<(Polygon | MultiPolygon)> input polygon or multipolygon

Returns

boolean: true if the Point is inside the Polygon; false if the Point is not inside the Polygon

Example

var pt = turf.point([-77, 44]);
var poly = turf.polygon([[
  [-81, 41],
  [-81, 47],
  [-72, 47],
  [-72, 41],
  [-81, 41]
]]);

var isInside = turf.inside(pt, poly);

//=isInside

npm install @turf/within

within

Takes a set of points and a set of polygons and returns the points that fall within the polygons.

Arguments

Argument Type Description
points FeatureCollection<Point> input points
polygons FeatureCollection<Polygon> input polygons

Returns

FeatureCollection<Point>: points that land within at least one polygon

Example

var searchWithin = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-46.653,-23.543],
          [-46.634,-23.5346],
          [-46.613,-23.543],
          [-46.614,-23.559],
          [-46.631,-23.567],
          [-46.653,-23.560],
          [-46.653,-23.543]
        ]]
      }
    }
  ]
};
var points = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-46.6318, -23.5523]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-46.6246, -23.5325]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-46.6062, -23.5513]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-46.663, -23.554]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [-46.643, -23.557]
      }
    }
  ]
};

var ptsWithin = turf.within(points, searchWithin);

//=points

//=searchWithin

//=ptsWithin

npm install @turf/tag

tag

Takes a set of points and a set of polygons and performs a spatial join.

Arguments

Argument Type Description
points FeatureCollection<Point> input points
polygons FeatureCollection<Polygon> input polygons
field string property in polygons to add to joined { } features
outField string property in points in which to store joined property from polygons

Returns

FeatureCollection<Point>: points with containingPolyId property containing values from polyId

Example

var pt1 = turf.point([-77, 44]);
var pt2 = turf.point([-77, 38]);
var poly1 = turf.polygon([[
  [-81, 41],
  [-81, 47],
  [-72, 47],
  [-72, 41],
  [-81, 41]
]], {pop: 3000});
var poly2 = turf.polygon([[
  [-81, 35],
  [-81, 41],
  [-72, 41],
  [-72, 35],
  [-81, 35]
]], {pop: 1000});

var points = turf.featureCollection([pt1, pt2]);
var polygons = turf.featureCollection([poly1, poly2]);

var tagged = turf.tag(points, polygons,
                      'pop', 'population');

//=tagged

Grids

npm install @turf/hex-grid

hexGrid

Takes a bounding box and a cell size in degrees and returns a FeatureCollection of flat-topped hexagons (Polygon features) aligned in an "odd-q" vertical grid as described in Hexagonal Grids.

Arguments

Argument Type Description
bbox Array<number> extent in [minX, minY, maxX, maxY] order
cellSize number dimension of cell in specified units
units [string] (default kilometers) used in calculating cellSize, can be degrees, radians, miles, or kilometers
triangles [boolean] (default false) whether to return as triangles instead of hexagons

Returns

FeatureCollection<Polygon>: a hexagonal grid

Example

var bbox = [-96,31,-84,40];
var cellSize = 50;
var units = 'miles';

var hexgrid = turf.hexGrid(bbox, cellSize, units);

//=hexgrid

npm install @turf/point-grid

pointGrid

Creates a Point grid from a bounding box, FeatureCollection or Feature.

Arguments

Argument Type Description
bbox (Array<number> | FeatureCollection | Feature<any>) extent in [minX, minY, maxX, maxY] order
cellSize number the distance across each cell
units [string] (default kilometers) used in calculating cellSize, can be degrees, radians, miles, or kilometers

Returns

FeatureCollection<Point>: grid of points

Example

var extent = [-70.823364, -33.553984, -70.473175, -33.302986];
var cellSize = 3;
var units = 'miles';

var grid = turf.pointGrid(extent, cellSize, units);

//=grid

npm install @turf/square-grid

squareGrid

Creates a square grid from a bounding box, Feature or FeatureCollection.

Arguments

Argument Type Description
bbox (Array<number> | FeatureCollection | Feature<any>) extent in [minX, minY, maxX, maxY] order
cellSize number width of each cell
units [string] (default kilometers) used in calculating cellSize, can be degrees, radians, miles, or kilometers
completelyWithin [boolean] (default false) adjust width & height cellSize to fit exactly within bbox

Returns

FeatureCollection<Polygon>: grid a grid of polygons

Example

var bbox = [-95, 30 ,-85, 40];
var cellSize = 50;
var units = 'miles';

var squareGrid = turf.squareGrid(bbox, cellSize, units);
//=squareGrid

npm install @turf/triangle-grid

triangleGrid

Takes a bounding box and a cell depth and returns a set of triangular polygons in a grid.

Arguments

Argument Type Description
bbox Array<number> extent in [minX, minY, maxX, maxY] order
cellSize number dimension of each cell
units [string] (default kilometers) used in calculating cellSize, can be degrees, radians, miles, or kilometers

Returns

FeatureCollection<Polygon>: grid of polygons

Example

var bbox = [-96,31,-84,40]
var cellSize = 10;
var units = 'miles';

var triangleGrid = turf.triangleGrid(bbox, cellSize, units);

//=triangleGrid

Classification

npm install @turf/nearest

nearest

Takes a reference point and a FeatureCollection of Features with Point geometries and returns the point from the FeatureCollection closest to the reference. This calculation is geodesic.

Arguments

Argument Type Description
targetPoint Feature<Point> the reference point
points FeatureCollection<Point> against input point set

Returns

Feature<Point>: the closest point in the set to the reference point

Example

var point = {
  "type": "Feature",
  "properties": {
    "marker-color": "#0f0"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [28.965797, 41.010086]
  }
};
var against = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [28.973865, 41.011122]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [28.948459, 41.024204]
      }
    }, {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [28.938674, 41.013324]
      }
    }
  ]
};

var nearest = turf.nearest(point, against);
nearest.properties['marker-color'] = '#f00';

var resultFeatures = against.features.concat(point);
var result = {
  "type": "FeatureCollection",
  "features": resultFeatures
};

//=result

Meta

npm install @turf/meta

coordAll

Get all coordinates from any GeoJSON object.

Note: coordAll is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordAll method.

Arguments

Argument Type Description
layer Object any GeoJSON object

Returns

Array<Array<number>>: coordinate position array

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
var coords = turf.coordAll(features);
//=coords

npm install @turf/meta

coordEach

Iterate over coordinates in any GeoJSON object, similar to Array.forEach()

Note: coordEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordEach method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (currentCoords, currentIndex)
excludeWrapCoord [boolean] (default false) whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration.

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.coordEach(features, function (currentCoords, currentIndex) {
  //=currentCoords
  //=currentIndex
});

npm install @turf/meta

coordReduce

Reduce coordinates in any GeoJSON object, similar to Array.reduce()

Note: coordReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordReduce method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (previousValue, currentCoords, currentIndex)
initialValue [Any] Value to use as the first argument to the first call of the callback.
excludeWrapCoord [boolean] (default false) whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration.

Returns

Any: The value that results from the reduction.

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.coordReduce(features, function (previousValue, currentCoords, currentIndex) {
  //=previousValue
  //=currentCoords
  //=currentIndex
  return currentCoords;
});

npm install @turf/meta

featureEach

Iterate over features in any GeoJSON object, similar to Array.forEach.

Note: featureEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the featureEach method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (currentFeature, currentIndex)

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.featureEach(features, function (currentFeature, currentIndex) {
  //=currentFeature
  //=currentIndex
});

npm install @turf/meta

featureReduce

Reduce features in any GeoJSON object, similar to Array.reduce().

Note: featureReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the featureReduce method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (previousValue, currentFeature, currentIndex)
initialValue [Any] Value to use as the first argument to the first call of the callback.

Returns

Any: The value that results from the reduction.

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"foo": "bar"},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {"hello": "world"},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.featureReduce(features, function (previousValue, currentFeature, currentIndex) {
  //=previousValue
  //=currentFeature
  //=currentIndex
  return currentFeature
});

npm install @turf/meta

geomEach

Iterate over each geometry in any GeoJSON object, similar to Array.forEach()

Note: geomEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the geomEach method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (currentGeometry, currentIndex)

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.geomEach(features, function (currentGeometry, currentIndex) {
  //=currentGeometry
  //=currentIndex
});

npm install @turf/meta

geomReduce

Reduce geometry in any GeoJSON object, similar to Array.reduce().

Note: geomReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the geomReduce method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (previousValue, currentGeometry, currentIndex)
initialValue [Any] Value to use as the first argument to the first call of the callback.

Returns

Any: The value that results from the reduction.

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"foo": "bar"},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {"hello": "world"},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.geomReduce(features, function (previousValue, currentGeometry, currentIndex) {
  //=previousValue
  //=currentGeometry
  //=currentIndex
  return currentGeometry
});

npm install @turf/meta

propEach

Iterate over properties in any GeoJSON object, similar to Array.forEach()

Note: propEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the propEach method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (currentProperties, currentIndex)

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"foo": "bar"},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {"hello": "world"},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.propEach(features, function (currentProperties, currentIndex) {
  //=currentProperties
  //=currentIndex
});

npm install @turf/meta

propReduce

Reduce properties in any GeoJSON object into a single value, similar to how Array.reduce works. However, in this case we lazily run the reduction, so an array of all properties is unnecessary.

Note: propReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the propReduce method.

Arguments

Argument Type Description
layer Object any GeoJSON object
callback Function a method that takes (previousValue, currentProperties, currentIndex)
initialValue [Any] Value to use as the first argument to the first call of the callback.

Returns

Any: The value that results from the reduction.

Example

var features = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"foo": "bar"},
      "geometry": {
        "type": "Point",
        "coordinates": [26, 37]
      }
    },
    {
      "type": "Feature",
      "properties": {"hello": "world"},
      "geometry": {
        "type": "Point",
        "coordinates": [36, 53]
      }
    }
  ]
};
turf.propReduce(features, function (previousValue, currentProperties, currentIndex) {
  //=previousValue
  //=currentProperties
  //=currentIndex
  return currentProperties
});

Assertions

npm install @turf/invariant

collectionOf

Enforce expectations about types of FeatureCollection inputs for Turf. Internally this uses geojsonType to judge geometry types.

Note: collectionOf is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the collectionOf method.

Arguments

Argument Type Description
featureCollection FeatureCollection a FeatureCollection for which features will be judged
type string expected GeoJSON type
name string name of calling function

Throws

Error: if value is not the expected type.

npm install @turf/invariant

geojsonType

Enforce expectations about types of GeoJSON objects for Turf.

Note: geojsonType is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the geojsonType method.

Arguments

Argument Type Description
value GeoJSON any GeoJSON object
type string expected GeoJSON type
name string name of calling function

Throws

Error: if value is not the expected type.

npm install @turf/invariant

getCoord

Unwrap a coordinate from a Point Feature, Geometry or a single coordinate.

Note: getCoord is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the getCoord method.

Arguments

Argument Type Description
obj (Array<any> | Geometry | Feature<Point>) any value

Returns

Array<number>: coordinates

npm install @turf/invariant

getCoords

Unwrap coordinates from a Feature, Geometry Object or an Array of numbers

Note: getCoords is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the getCoords method.

Arguments

Argument Type Description
obj (Array<any> | Geometry | Feature<any>) any value

Returns

Array<any>: coordinates

npm install @turf/invariant

featureOf

Enforce expectations about types of Feature inputs for Turf. Internally this uses geojsonType to judge geometry types.

Note: featureOf is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the featureOf method.

Arguments

Argument Type Description
feature Feature a feature with an expected geometry type
type string expected GeoJSON type
name string name of calling function

Throws

Error: error if value is not the expected type.

Aggregation

npm install @turf/collect

collect

Merges a specified property from a FeatureCollection of points into a FeatureCollection of polygons. Given an inProperty on points and an outProperty for polygons, this finds every point that lies within each polygon, collects the inProperty values from those points, and adds them as an array to outProperty on the polygon.

Arguments

Argument Type Description
polygons FeatureCollection<Polygon> polygons with values on which to aggregate
points FeatureCollection<Point> points to be aggregated
inProperty string property to be nested from
outProperty string property to be nested into

Returns

FeatureCollection<Polygon>: polygons with properties listed based on outField

Example

var poly1 = turf.polygon([[[0,0],[10,0],[10,10],[0,10],[0,0]]]);
var poly2 = turf.polygon([[[10,0],[20,10],[20,20],[20,0],[10,0]]]);
var polyFC = turf.featureCollection([poly1, poly2]);
var pt1 = turf.point([5,5], {population: 200});
var pt2 = turf.point([1,3], {population: 600});
var pt3 = turf.point([14,2], {population: 100});
var pt4 = turf.point([13,1], {population: 200});
var pt5 = turf.point([19,7], {population: 300});
var pointFC = turf.featureCollection([pt1, pt2, pt3, pt4, pt5]);
var collected = turf.collect(polyFC, pointFC, 'population', 'values');
var values = collected.features[0].properties.values
//=values => [200, 600]
//=pointFC
//=collected

npm install @turf/unkink-polygon

simplepolygon

Takes a complex (i.e. self-intersecting) geojson polygon, and breaks it down into its composite simple, non-self-intersecting one-ring polygons.

Arguments

Argument Type Description
feature Feature Input polygon. This polygon may be unconform the Simple Features standard in the sense that it's inner and outer rings may cross-intersect or self-intersect, that the outer ring must not contain the optional inner rings and that the winding number must not be positive for the outer and negative for the inner rings.

Returns

FeatureCollection: Feature collection containing the simple, non-self-intersecting one-ring polygon features that the complex polygon is composed of. These simple polygons have properties such as their parent polygon, winding number and net winding number.

Example

var poly = {
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[0,0],[2,0],[0,2],[2,2],[0,0]]]
  }
};

var result = simplepolygon(poly);

// =result
// which will be a featureCollection of two polygons, one with coordinates [[[0,0],[2,0],[1,1],[0,0]]], parent -1, winding 1 and net winding 1, and one with coordinates [[[1,1],[0,2],[2,2],[1,1]]], parent -1, winding -1 and net winding -1