Turf.js is a library for spatial analysis: a large family of tasks like ‘calculating area and distance’ and ‘joining points to polygons’ that enable people to see new facets of their data. Spatial analysis is used in every industry: to find the nearest coffee shop, calculate travel time, and show regional statistics for utility usage. It’s also a huge part of GIS, where many problems are solved with spatial analysis.
The map below is a classic example of spatial analysis, created by physician John Snow during the 1854 cholera outbreak in London. Snow plotted cholera cases in the Soho area of London around Broad Street and noticed a cluster around the water pump. This led to improved sanitation facilities and also the discovery that cholera infection was water-borne rather than airborne.
John Snow Cholera Map
Today, spatial analysis is used in epidemiology, biology, statistics, economics, commerce and business, urban planning, geology, oil and gas, and in many other industries. With Turf.js, we can now bring these analyses to the browser and show results quickly and seamlessly.
Data in Turf.js
Almost every function in Turf.js takes GeoJSON data as its input and returns GeoJSON data as its output. GeoJSON is a popular format for storing features that make up map overlays.
Let’s take a look at some of the most common Turf.js functions in action to see how they’re used.
Turf-buffer in action
One of the most common functions is turf-buffer, which takes a GeoJSON feature of any type and returns a buffer zone of a specified distance around it as a Polygon feature.
Some functions return numbers, arrays, or boolean (true/false) values, depending on their context. For example, turf-inside takes a Point feature and a Polygon feature and returns true if the point is inside the polygon.
Turf.js also has some functions that allow you to create GeoJSON Features and FeatureCollections quickly. This saves you the trouble of typing lots of curly braces and commas (where typos can often occur). An important note: these constructors are exactly the same as using regular GeoJSON primitives, and you do not need to convert your GeoJSON to these constructors to use Turf.js functions.
Creating a GeoJSON Feature or FeatureCollection with the Turf.js constructors is no different than creating them with the traditional GeoJSON format, and all turf functions that take GeoJSON as parameters can also take the Turf.js constructors as parameters.
With Turf, you can do almost any kind of spatial analysis operation that you can think of. The functions are organized into groups to make them easier to find, although some are more widely-used than others.
Aggregation methods can run statistical operations on a set of points within a set of polygons. Want to compare average size of elementary schools across counties in Massachusetts? You can do that with turf-average!
Measurement methods can measure distances, create features, and calculate sizes. With measurement methods, you can figure out not only the exact center point of the city of Austin (with turf-centroid, but you can also measure the distance between that point and city hall (with turf-distance.
Transformation methods can solve spatial problems. If you want to buy a house that is both within one mile of a park and one mile of a bus stop, you can figure out where those areas overlap with turf-intersect, a transformation method.
Data methods can filter data by certain properties or create data for testing. For example, you can use turf-filter to toggle 311 calls by call-type.
Interpolation methods can estimate or average data and visualize the result. An example of this is creating contour lines (or isobands) from a set of points containing elevation information with turf-isobands.
Join methods can determine spatial relationships between features. If you want to know which burglaries happened in a specific neighborhood, you can use a join method like turf-within to figure it out.
Finally, classification methods can (yup, you guessed it) classify data into discrete groups. If you want to change the “color” property of a series of features from individual colors to simply “blue” or “not blue,” you can use the turf-reclass method.
Ready for more? We recommend you move onto our next Turf.js guide, where we will dive into using Turf.js with Mapbox.js to solve real-world problems. There are also examples in the documentation on the Turf website!