Geo Assist

Manage and query your geo-spatial data efficiently.

Report a Bug · Request a Feature

⚡️ What is it?

Geo Assist is an open-source Java library designed to simplify the process of working with spatial data. With an implementation of KD Trees, users can efficiently store and query spatial data such as latitude/longitude coordinates.

By providing a streamlined interface for complex geospatial operations, Geo Assist enables developers to build powerful and accurate search algorithms for applications such as geospatial analysis, location-based services, and more.

The project aims to enable the use of complex search algorithms, by tweaking them for geospatial operations.

📖 How to?

Install:

Geo-assist is available on maven repository and can be imported to your project.

<dependency>
    <groupId>com.thegeekyasian</groupId>
    <artifactId>geo-assist</artifactId>
    <version>1.0.4</version>
</dependency>

🌳 K-d Tree:

K-d Tree, formally called K-Dimensional Trees, are one of the best options when storing and retrieving objects based on geospatial parameters.

I have provided an implementation of storing objects in a K-d tree using the coordinates and searching nearest neighbors for the provided location (latitude/longitude) and the distance.

Insert

Here is how to initialize your data:

KDTree<Long, Object> kdTree = new KDTree<>();
kdTree.insert(new KDTreeObject.Builder<Long, Object>()
				.id(5)
				.latitude(25.2002450)
				.longitude(55.2734184)
				.build());

Find Nearest Neighbors

Once you have inserted your object(s) in the tree, here is how you can search for the nearest neighbors for a provided location:

Point point = new Point.Builder()
				.latitude(25.2012544)
				.longitude(55.2569389)
				.build();
List<KDTreeObject<Long, Object>> nearestNeighbors = 
        kdTree.findNearestNeighbor(point, 2); // 2 kilometers based on haversine distance.

Find The Nearest-Most Neighbor

Another feature provided allows you to find the nearest most object. From the objects that you can find in using the findNearestNeighbor feature, this method allows you to get the closest one, based on the provided location and distance.

The method is called findNearest, and returns a wrapper that holds the closes KDTreeObject and its distance from the provided location.

The API can be invoked as below:

Point point = new Point.Builder()
				.latitude(25.2012544)
				.longitude(55.2569389)
				.build();
KDTreeNearestNeighbor<String, Object> nearestNeighbor = 
        this.kdTree.findNearest(point, 2); // 2 kilometers based on haversine distance.

Find in Bounding Box (range)

You can also find of objects in a bounding box for the provided range.
The findInRange method searches the k-d tree for all nodes whose coordinates fall within a given bounding box. This is useful for finding all points within a specific geographic region or for performing spatial queries on a set of points. The method takes in a BoundingBox object that defines the range to search within, and returns a list of KDTreeObject objects whose coordinates fall within the bounding box.

Here is how you can use find in range:

BoundingBox boundingBox = new BoundingBox.Builder()
				.lowerPoint(new Point.Builder()
						.latitude(24.836135)
						.longitude(66.976089)
						.build())
				.upperPoint(new Point.Builder()
						.latitude(24.951953)
						.longitude(67.157364)
						.build())
				.build();
				
List<KDTreeObject<String, Object>> objects = kdTree.findInRange(boundingBox);

Delete

You can delete the object based on the custom identifier ID:

boolean ok = kdTree.delete(5);

This is how simple it has been made to query your geo-spatial data.

⭐️ Project assistance

If you want to say thank you or/and support active development of Geo Assist:

• Add a GitHub Star to the project.
• Tweet about project on your Twitter.
• Write interesting articles about project on Dev.to, Medium or personal blog.
• Create an issue to open discussion threads or new feature requests.
• Contribute to the project for any new features.

Together, we can make this project better every day! ❤️

For any questions, discussions or support you can join the Geo Assist Discord Server.