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).

1import greatCircle from '@turf/great-circle';
2import { point } from '@turf/helpers';

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.