# distance_calculator

The distance calculator is a module for calculating distance between two
geographic locations. It measures the distance along the surface of the earth.
Formula takes into consideration the radius of the earth. For this algorithm, it
is necessary to define an object that has longitude and latitude properties like
this:

```cypher
(location:Location {lat: 44.1194, lng: 15.2314})
```

| Trait               | Value                                                 |
| ------------------- |------------|
| **Module type**     | module     |
| **Implementation**  | C++        |
| **Graph direction** | undirected |
| **Edge weights**    | unweighted |
| **Parallelism**     | sequential |

## Procedures

> **Info**
>
> You can execute this algorithm on [graph projections, subgraphs or portions of the graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph).

### `single()`

Measures a distance from the start node to the end node. 

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

* `start: Vertex` ➡ Starting point to measure distance. Required to have `lng` and `lat` properties.
* `end: Vertex` ➡ Ending point to measure distance. Required to have `lng` and `lat` properties.
* `metrics: string` ➡ Can be either "m" or "km". These stand for meters and kilometers respectively.
* `decimals:int` ➡ Number of decimals to round up the result.

#### Output:

* `distance: double` ➡ The final result obtained by calculating distance (in 'm'
  or 'km') between the 2 points that each have its latitude and longitude
  properties.

#### Usage:

The following query measures a distance from the start node to the end node:

```cypher
MATCH (n:Location), (m:Location)
CALL distance_calculator.single(m, n, 'km')
YIELD distance
RETURN distance;
```

### `multiple()`

The procedure calculates the distance from all nodes from a start list, to all
the nodes from an end list. 

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

* `start_points: List[Vertex]` ➡ Starting points to measure distance collected in a list. Required to have `lng` and `lat` properties. Must be of the same size as `end_points`.
* `end_points: List[Vertex]` ➡ Ending points to measure distance collected in a list. Required to have `lng` and `lat` properties. Must be of the same size as `start_points`.
* `metrics: string` ➡ Can be either "m" or "km". These stand for metres and kilometres respectively.
* `decimals:int` ➡ Number of decimals to round up the result.

#### Output:

* `distance: List[double]` ➡ The final result obtained by calculating distance (in 'm'
  or 'km') from all the nodes from the start list, to all the nodes from the end list.

#### Usage:

```cypher
MATCH (n), (m)
WITH COLLECT(n) AS location_set1, COLLECT(m) AS location_set2
CALL distance_calculator.multiple(location_set1, location_set2, 'km') YIELD distances
RETURN distances;
```

## Examples

Calculate distance between Zagreb and Zadar. 

### Database state
 

The database contains the following data: 

![](https://memgraph.com/docs/pages/advanced-algorithms/available-algorithms/distance_calculator/distance-calculator-1.png)

Created with the following Cypher queries:

```
CREATE (location:Location {name: 'Zagreb', lat: 45.8150, lng: 15.9819});
CREATE (location:Location {name: 'Zadar', lat: 44.1194, lng: 15.2314});
```

### Calculate distance
 

```
MATCH (n {name: 'Zagreb'}), (m {name: 'Zadar'})
CALL distance_calculator.single(n, m, 'km') YIELD distance
RETURN distance;
```

Result:

```
+----------+
| distance |
+----------+
| 197.568  |
+----------+
```

Calculate distance between:
- Samobor and Zadar,
- Velika Gorica and Zadar,
- Samobor and Biograd,
- Velika Gorica and Biograd. 

Samobor and Velika Gorica are in Zagrebacka county. 
Zadar and Biograd are in Zadar county. 

### Database state
 

The database contains the following data: 

![](https://memgraph.com/docs/pages/advanced-algorithms/available-algorithms/distance_calculator/distance-calculator-2.png)

Created with the following Cypher queries:

```
CREATE (location:Location {name: 'Samobor', county: 'Zagrebacka', lat: 45.8011, lng: 15.7110});
CREATE (location:Location {name: 'Velika Gorica', county: 'Zagrebacka', lat: 45.7142, lng: 16.0752});
CREATE (location:Location {name: 'Zadar', county:'Zadar', lat: 44.1194, lng: 15.2314});
CREATE (location:Location {name: 'Biograd', county:'Zadar', lat: 43.9373, lng: 15.4436});
```

### Calculate distance
 

Get the values using the following query:

```
MATCH (n:Location {county: "Zagrebacka"})
MATCH (m:Location {county: "Zadar"})
WITH  COLLECT(n) as ZG, COLLECT(m) as ZD
CALL distance_calculator.multiple(ZG, ZD, "km", 2) YIELD distances
RETURN ZG, ZD, distances;
```

Results (the information about nodes in the lists have been shortened to include only city names):

```
+----------------+------------+-----------+
| ZG             | ZD         | distances | 
+----------------+------------+-----------+
| Samobor        | Zadar      | 190.76    |
+----------------+------------+-----------+
| Velika Gorica  | Zadar      | 189.37    |
+----------------+------------+-----------+
| Samobor        | Biograd    | 208.31    |
+----------------+------------+-----------+
| Velika Gorica  | Biograd    | 203.76    |
+----------------+------------+-----------+
```