# @mapbox/probematch

> A small module for matching probes to road networks

Latest version **3.0.0** (published 2018-05-18) · ISC license · 0 weekly downloads

## Install

```sh
npm install @mapbox/probematch
pnpm add @mapbox/probematch
yarn add @mapbox/probematch
bun add @mapbox/probematch
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2018-05-18 |
| First published | 2018-03-21 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 301.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 19 |
| Author | Tim Channell |
| Maintainers | 1ec5, aaaandrea, aag6z, aarthykc, ajashton, akit, alianthes, aliceykuo, alinapaz, allanwalkerit, allieoop, allierowan, alulsh, amishas157, ampetr89, amyleew, anandthakker, andygol, angela.navarro, ansis, aparlato, apavani, apendleton, arunasank, arya-elf, asheemmamoowala, atevans-mapbox, benjamintd, bhousel, bkowshik, boblannon, brendanmcfarland, brsbl, brunoabinader, bsrinivasa, bsudekum, camillacaros, camilo.sanin, cammace, captainbarbosa-mbx, caseymm, castledoor, charloyd, chaupow, chriscx, chrisloer, chriswu42, cknouss, cmtoomey, colleenmcginnis, coxchapman, d-prukop, danieljh, danmactough, danpat, danpaz-mb, danswick, dasulit, davidtheclark, deniskoronchik, dgearhart, dhcole, dianeschulze, dnesbitt, dnomadb, dombox, dputtick, drboyer, dthompson, edgar-marca, electrostat, elifitch, emilymcafee, emilymdubois, enf, ericdeveloper, eschow, fa7c0n, fabianguerra, flippmoke, franka, freenerd, friedbunny, geografa, ghoshkaj, gknisely, gretacb, guardiola31337, heyadam_mapbox, heystenson, hjudge, ian29, ianshward, ingalls, isiyu, ivovandongen, jacquestardie, jayana, jc-clark, jcsg, jerrad, jfirebaugh, jim-martin, jinnycho503, jjanczyszyn, jmkiley, jordanwebb, jothirnadh, jrpruit1, jseppi, julianrex, k-mahoney, kaibot3000, kalimar, karenell, karenzshea, katydecorah, kdiluca, kellyoung, kepta, kevinkreiser, kilatsat, kkaefer, ksummerill, l-r, langstonsmith, lbud, lily-chai, lingoded, lizziegooding, lobenichou, lshig, lukasmartinelli, lukaspaczos, lxbarth, lyzidiamond, macro-shen, maikyon, mal-wood, maning, manoharuss, mapbox-admin, mapsam, markmisener, mateov, matt.gosline, mattficke, mcwhittemore, miccolis, mikelmaron, millzpaugh, mollymerp, morgane, morganherlocker, mourner, mpozdnyakov, msirenko, mtirwin, nammala, natslaughter, nickcordella, nickidlugash, nickitaliano, nikhilprabhakar, nmargolis, norchard, normanb, oini, okoriep, oliikit, oormilavinod, osana, otherwiseman, oxidase, paigemoody, pdgoodman, perrygeo, peterqliu, petersirota, planemad, poornibadrinath, pratikyadav, pt-44, pveugen, ramshackle-jamathon, rasagy, rclark, rcleedev, recursivefunk, rmrice, ruggeroaltair, ryan-baumann, s-heisler, sabaelhilo, sabzo, sadiew, saikia.abhishek, samanbb, samely, samfader, sbma44, scottschultz, scottsfarley93, seekely, sgillies, springmeyer, srividyacb, tapasweni-pathak, taziam, tcql, themarex, tmpsantos, tobrun, tony-cj, tonysun, trevorspecht, tridip1931, tristen, upendrayadav, vakila, vincents, virginiayung, willwhite, xianny, yhahn, yuffster, yuletide, zhuwenlong, zmully, zugaldia, zurihunter92 |
| Keywords | gps, match, probe, geojson |

## Links

- npm: https://www.npmjs.com/package/@mapbox/probematch
- Repository: https://github.com/mapbox/probematch
- Homepage: https://github.com/mapbox/probematch#readme
- Issues: https://github.com/mapbox/probematch/issues
- npm.io page: https://npm.io/package/@mapbox/probematch

## Dependencies (5)

- [xtend](https://npm.io/package/xtend.md) ^4.0.0
- [flatbush](https://npm.io/package/flatbush.md) ^3.0.0
- [@turf/bbox](https://npm.io/package/@turf/bbox.md) ^6.0.1
- [cheap-ruler](https://npm.io/package/cheap-ruler.md) ^2.4.0
- [turf-linestring](https://npm.io/package/turf-linestring.md) ^1.0.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.0.0 (latest) — 2018-05-18
- 3.0.0-rc1 — 2018-05-18
- 3.0.0-rc0 — 2018-05-18
- 2.4.3 — 2018-05-09
- 2.4.2 — 2018-03-21
- 2.4.1 — 2018-03-21

## README

# @mapbox/probematch

Match a single GPS measurements (probe) or line of sequential GPS measurements (trace) to a road network.

*probematch* creates an [flatbush index](https://github.com/mourner/flatbush) of a road network to allow you to quickly match probes or traces to the roads using configurable distance and bearing filters.

### terms

- **probe** - a single GPS measurement, represented by a Feature<Point>
- **trace** - a collection of sequential GPS measurements, represented by a Feature<LineString>
- **road** - a Feature<LineString> representing a road, which we may attempt to match probes and traces to
- **roads, network, road network** - a FeatureCollection of roads
- **segment** - a single edge of a road. For road A -> B -> C, there are two segments: A -> B and B -> C. Segments always have only 2 points.

# install

`npm install @mapbox/probematch`

# configuration

```js
var probematch = require('@mapbox/probematch');

var roads = {
  'type': 'FeatureCollection',
  'features': [
    // Linestring features representing the road network
  ]
};

var matcher = probematch(roads, {
  compareBearing: true,
  maxBearingRange: 5,
  bidirectionalBearing: false,
  maxProbeDistance: 0.01
});
```

key | type | default | description
--- | --- | --- | ---
compareBearing | boolean | true | Should bearing of probes be used to evaluate match quality? <br /><br />If true, the bearing of the probe is compared to the bearing of each possible matching road segment. This ensures probes don't match cross-streets that obviously aren't the same as the probe's direction of travel
maxBearingRange | number | 5 | Maximum amount in degrees that a probe's bearing may differ from a road segment's when using `compareBearing`
bidirectionalBearing | boolean | false | Should bearing matches allow for probes to be moving in the opposite direction of a road segment's bearing? This should be true if the road network includes 2-way roads.
maxProbeDistance | number | 0.01 | Maximum distance in kilometers that a probe may be from a road segment in order to consider it a possible match. Prevents matching probes to segments that are too far away from them.




# usage
## match

```js
var probematch = require('@mapbox/probematch');

var roads = /* FeatureCollection of road geometries */;
var matcher = probematch(roads, {/* configuration */});

var probe = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [0, 0]
  }
};

var probeBearing  = 57; // probe's direction of travel in degrees

var results = matcher(probe, probeBearing);
```

The result of matching a single proble is an array of possible matches to the road network. Results are ordered by the probe's distance from the candidate road.

Each possible match represents a road that is likely to have matched the probe.

key | type | description
--- | --- | ---
**road** | Feature&lt;LineString&gt; | The geometry of a road that may have been matched
**index** | Number | The start index of the segment closest to the probe may have matched (in the road's coordinates)
**distance** | number | Distance (in kilometers) between the probe and the road
**bearing** | number | The bearing of the road at the location that matched

## matchTrace


```js
var probematch = require('@mapbox/probematch');

var roads = /* FeatureCollection of road geometries */;
var matcher = probematch(roads, {/* configuration */});

var results = matcher.matchTrace(line);
```

`matchTrace` returns an array of `match` results. The order of results is the same as the order of the coordinates in the input trace. This means that the zeroeth element in the `matchTrace` result is an array of possible matches for the zeroeth coordinate, and so on.

---
_Source: https://npm.io/package/@mapbox/probematch · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._