---
name: bijection-geospatial
description: "Evaluate and integrate the Geospatial component with Bijection."
---

# Geospatial

Geographic point indexing

- Package: @bijectionhq/geospatial
- Category: Database & Backend
- Status: Reference
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/geospatial/tree/1b43993f3ee9b848ffe0efbf9703a43797a149e8
- Upstream: https://github.com/convex/geospatial/tree/c1c9993620ebe3b6b0f03da63fea67b41d233876
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/geospatial

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/geospatial.git
cd geospatial
git checkout 1b43993f3ee9b848ffe0efbf9703a43797a149e8
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/geospatial. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Geospatial

## Instructions

A geospatial indexing component that enables efficient storage and querying of geographic points within Convex. You can insert points with coordinates, filter keys, and sort keys, then query for all points within rectangular regions or find the nearest points to a given location. The component supports equality filters, range filters on sort keys, and pagination through large result sets while maintaining Convex's consistency and reactivity guarantees.

### Installation

```bash
npm install @convex-dev/geospatial
```

## Use cases

- **Location-based app features** where you need to find nearby restaurants, stores, or services within a user's viewport on a map
- **Fleet management systems** that track vehicle locations and need to efficiently query which vehicles are in specific geographic regions
- **Real estate platforms** filtering properties by price range within map boundaries, with results sorted by price or distance
- **Event discovery apps** finding concerts, meetups, or activities within walking distance of a user's location
- **Asset tracking applications** monitoring equipment or inventory across geographic regions with complex filtering requirements

## How it works

The component installs as a Convex component and provides a `GeospatialIndex` class that wraps the underlying geospatial storage. You insert points using the `insert()` method with coordinates, optional filter keys for querying, and sort keys for result ordering. The component stores points in an indexed structure that enables efficient rectangular and nearest-neighbor queries.

For querying, the `query()` method accepts rectangular shapes and supports filter conditions including `eq()` for exact matches, `in()` for set membership, and range conditions like `gte()` and `lt()` on sort keys. The `nearest()` method finds closest points to a query location with optional maximum distance constraints. Both query types return paginated results with cursor-based continuation for large datasets.

The component integrates with Convex's mutation and query functions, maintaining consistency and reactivity. All geographic computations happen server-side using the indexed data structure, avoiding expensive client-side distance calculations while leveraging Convex's automatic caching and real-time updates.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Geospatial is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fgeospatial)
- [GitHub repository](https://github.com/get-convex/geospatial)
- [Convex Components Directory](https://www.convex.dev/components/geospatial)
- [Convex documentation](https://docs.convex.dev)