@turf/nearest-point-on-line/README.md

Finds the nearest point on a line to a given point

# @turf/nearest-point-on-line

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## nearestPointOnLine

Returns the nearest point on a line to a given point.

If any of the segments in the input line string are antipodal and therefore
have an undefined arc, this function will instead return that the point lies
on the line.

⚠️ We have begun the process of migrating to different return properties for
this function. The new properties we recommend using as of v7.4 are:

*   lineStringIndex - point was found on the nth LineString of an input MultiLineString. Previously `multiFeatureIndex`
*   segmentIndex - point was found on the nth segment of the above LineString. Previously `index`
*   totalDistance - distance from the start of the overall MultiLineString. Previously `location`
*   lineDistance - distance from the start of the relevant LineString
*   segmentDistance - distance from the start of the relevant segment
*   pointDistance - distance between found point is from input reference point. Previously `dist`

multiFeatureIndex, index, location, and dist continue to work as previously
until at least the next major release.

### Parameters

*   `lines` **([Geometry][1] | [Feature][2]<([LineString][3] | [MultiLineString][4])>)** Lines to snap to
*   `inputPoint` **([Geometry][1] | [Feature][2]<[Point][5]> | [Array][6]<[number][7]>)** Point to snap from
*   `options` **[Object][8]** Optional parameters (optional, default `{}`)

    *   `options.units` **Units** Supports all valid Turf [Units][9] (optional, default `'kilometers'`)

### Examples

```javascript
var line = turf.lineString([
    [-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 inputPoint = turf.point([-77.037076, 38.884017]);

var snapped = turf.nearestPointOnLine(line, inputPoint, {units: 'miles'});

//addToMap
var addToMap = [line, inputPoint, snapped];
snapped.properties['marker-color'] = '#00f';
```

Returns **[Feature][2]<[Point][5]>** closest point on the `lines` to the `inputPoint`. The point will have the following properties: `lineStringIndex`: closest point was found on the nth LineString (only relevant if input is MultiLineString), `segmentIndex`: closest point was found on nth line segment of the LineString, `totalDistance`: distance along the line from the absolute start of the MultiLineString, `lineDistance`: distance along the line from the start of the LineString where the closest point was found, `segmentDistance`: distance along the line from the start of the line segment where the closest point was found, `pointDistance`: distance to the input point.

[1]: https://tools.ietf.org/html/rfc7946#section-3.1

[2]: https://tools.ietf.org/html/rfc7946#section-3.2

[3]: https://tools.ietf.org/html/rfc7946#section-3.1.4

[4]: https://tools.ietf.org/html/rfc7946#section-3.1.5

[5]: https://tools.ietf.org/html/rfc7946#section-3.1.2

[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[9]: https://turfjs.org/docs/api/types/Units

<!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->

---

This module is part of the [Turfjs project](https://turfjs.org/), an open source module collection dedicated to geographic algorithms. It is maintained in the [Turfjs/turf](https://github.com/Turfjs/turf) repository, where you can create PRs and issues.

### Installation

Install this single module individually:

```sh
$ npm install @turf/nearest-point-on-line
```

Or install the all-encompassing @turf/turf module that includes all modules as functions:

```sh
$ npm install @turf/turf
```