geoprox-core 0.3.1

Core library for Geoprox, provides geospatial indexing and sharding functionalities.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# Geoprox Core

A Rust crate designed for geospatial indexing and sharding. It includes two primary modules: `cache` and `shard`. These modules provide efficient geospatial queries and indexing for applications such as food delivery services, real-time inventory tracking, and more.

> **Looking for an API implementation?** See, [`geoprox-server`](https://crates.io/crates/geoprox-server/) for the HTTP API version of this service and [`contrib/client-sdk`](https://github.com/ezrasingh/geoprox/tree/main/contrib/client-sdk) for HTTP client libraries.

## Features

- **Geospatial Indexing**: Efficiently index and search for resources based on their geographic location.
- **Geospatial Sharding**: Manage and query distributed datasets with geospatial awareness.

## Data Stuctures

### SpatialIndex

The `cache` module implements the `SpatialIndex` data structure, enabling efficient placement and searching of resources based on their geohash-encoded locations.

Key features include:

- **Placing Resources**: Add resources to the index with their geohash-encoded locations.
- **Searching Resources**: Perform range queries to find resources within a specified distance from a given location.

#### Example Usage

```rust
extern crate geoprox_core;

let mut geo_index = geoprox_core::SpatialIndex::default();

// ? place object keys into index
geo_index.insert("player1", &geohash::encode([40.7129, 74.007].into(), depth).unwrap());
geo_index.insert("player2", &geohash::encode([40.7127, 74.005].into(), depth).unwrap());

// ? search index for objects near New York
let nearby: LatLngCoord = [40.7128, 74.006];
let within: f64 = 200.0; // 200km radius
let count = 100; // return up to 100 results
let sorted = true; // sort results by distance
let depth = 6; // ? determines geohash length (i.e precision)
let res = geo_index.search(nearby, within, count, sorted, Some(depth)).unwrap();

println!("found: {:#?}", res);

assert_eq!(res.len(), 2);

res.iter().for_each(|neighbor| {
    assert!(neighbor.distance <= within);
});
```

### GeoShard

The `shard` module implements the `GeoShard` data structure, which facilitates geographical sharding of datasets and enables efficient range queries.

Key features include:

- **Creating Indexes**: Initialize geospatial indexes for different datasets.
- **Inserting Keys**: Insert keys into the geospatial index with their corresponding locations.
- **Querying Ranges**: Query the index to find keys within a specified range from a given location.
- **Drop Index**: Deletes the index and its associated keys.

#### Example Usage

```rust
extern crate geoprox_core;

let mut shard = geoprox_core::GeoShard::default();
// ? create an index to store driver coordinates
shard.create_index("drivers").unwrap();

// ? place drivers into index
shard.insert_key("drivers", "alice", [36.2049, 138.253]).unwrap();
shard.insert_key("drivers", "bob", [36.2047, 138.2528]).unwrap();

// ? search drivers near Japan
let nearby: LatLngCoord = [36.2048, 138.2529];
let within: f64 = 50.0; // 50km radius
let count = 100; // return up to 100 results
let sorted = true; // sort results by distance
let res = shard.query_range("drivers", nearby, within, count, sorted).unwrap();

println!("found: {:#?}", res);
```

## Contributing

Contributions are welcome! Please see the [contributing guidelines](https://github.com/ezrasingh/geoprox/blob/main/CONTRIBUTING.md) for more information.

## License

This project is licensed under the [Apache 2.0](LICENSE-APACHE) or [MIT License](LICENSE-MIT) (your choice).