turf.greatCircle

What is turf.greatCircle?

turf.greatCircle returns a LineString (or MultiLineString when the path crosses the antimeridian) densified along the great-circle arc between two Point features. This is the canonical way to draw flight-path-style curves on a Mercator-projected web map.

turf.greatCircle(start, end, options?) → Feature<LineString | MultiLineString>

Options include:

• properties — object assigned to the output feature's properties
• npoints — number of vertices along the arc (default 100)
• offset — controls when to split at the antimeridian

When would you use turf.greatCircle?

Use turf.greatCircle for rendering long-haul flight paths, submarine-cable maps, or migration routes — any case where the straight line between two points on a Mercator map would be visually misleading. It produces a smooth, curved polyline you can load into a MapLibre or Mapbox GeoJSON source.

In Node.js, use it to pre-generate route geometries for static datasets or to compute intermediate waypoints for further analysis (e.g. intersect the arc with country polygons for overflight detection).

undefined

FAQs

Why is the result sometimes a MultiLineString?

When the great-circle arc crosses the antimeridian (+/-180°), Turf splits it into two LineString parts so renderers do not draw a misleading straight line across the whole map. Adjust the offset option if you want to control where the split happens.

How many vertices should I use?

The default of 100 works for most intercontinental arcs. Increase to 200–500 for ultra-smooth rendering at high zoom, or reduce for short domestic routes. More points means slightly larger GeoJSON.

How do I install just greatCircle?

npm install @turf/great-circle. It depends on @turf/invariant and @turf/helpers.

Is this different from turf.lineArc?

Yes. turf.greatCircle draws a geodesic path between two points. turf.lineArc draws an arc on a circle of a given radius and bearing range around a centre point — useful for sectors and radii rather than routes.