Query geographic points within map regions using efficient spatial indexing for location-based features in Convex applications.
npm install @convex-dev/geospatialThis component adds a geospatial index to Convex, allowing you to efficiently store and query points on the Earth's surface.
Insert points into the geospatial key value store along with their geographic coordinates.
Efficiently query for all points within a given rectangle on the sphere.
Control the sort order for the results with a custom sorting key.
Filter query results with equality and IN clauses.
And since it's built on Convex, everything is automatically consistent, reactive, and cached!
This component is currently in beta. It's missing some functionality, but what's there should work. We've tested the example app up to about 1,000,000 points, so reach out if you're using a much larger dataset. If you find a bug or have a feature request, you can file it here.
The Geospatial component provides spatial indexing and querying functions to find points within a specified radius or region. You can query restaurants, stores, or users within a geographic area using optimized algorithms that work with Convex's database.
This component enables location-based features like proximity search, delivery zone validation, and regional content filtering. It provides functions to query points within polygons, circles, and bounding rectangles with efficient spatial indexing.
The Geospatial component adds spatial query capabilities to Convex databases, allowing you to efficiently search for geographic points within defined regions. It handles the complexity of coordinate systems and spatial algorithms for location-aware applications.
The Convex Geospatial component uses the WGS84 coordinate system with latitude and longitude values in decimal degrees. This is the standard system used by GPS and most mapping services, making it compatible with location data from mobile devices and mapping APIs.
Yes, the Geospatial component supports querying points within custom polygon regions defined by coordinate arrays. You can define irregular shapes like delivery zones, administrative boundaries, or custom service areas and efficiently find all points contained within them.
The Geospatial component's spatial queries work seamlessly with Convex's reactive subscriptions. When geographic data changes, components automatically re-render with updated results. The spatial indexing optimizes query performance while maintaining real-time reactivity for location-based features.
Radius queries in the Geospatial component are generally faster than polygon queries since they use simpler distance calculations. Complex polygons with many vertices require more computation for point-in-polygon tests, but the component uses optimized algorithms to minimize performance impact for typical use cases.