Geoprox

A standalone runtime for the Geoprox project.

Geoprox is an in-memory geospatial search engine designed for efficient real-time location-based pairing.

It helps quickly identify users or entities near a specific location, making it ideal for applications that need to match contracts with nearby users. Whether it's for ride-sharing services like Uber and Lyft or delivery platforms like Grubhub, Geoprox provides the speed and accuracy needed to enhance geo-aware interactions.

Discussed @ May 2024 Rust Indy.rs meetup

This crate offers a command-line tool for launching and managing the Geoprox server.

Installation

To install geoprox, use the following command:

cargo install geoprox

Usage

Geoprox provides several commands to start the server and work with geohashes:

geoprox help
Usage: geoprox [COMMAND]

Commands:
  run     Start Geoprox server
  encode  Hash latitude/longitude into geohash
  decode  Decode geohash into approximate longitude/latitude
  spec    Generate an OpenAPI specification file
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Getting Started

To start using Geoprox, you can run the following command to start the server:

geoprox run

You can also encode and decode geohashes directly from the CLI:

# Encode latitude and longitude into geohash
geoprox encode --lat=37.7749 --lng=-122.4194 --depth=5

# Decode geohash into latitude and longitude
geoprox decode 9q8yy

For detailed help on any command, use the help command:

geoprox help encode

Configuration

Geoprox allows specifying a configuration file using the -c or --config option or set the GEOPROX_CONFIG environment variable. This file can contain various settings to customize the behavior of the Geoprox server and commands. The configuration can be provided in any common format such as YAML, TOML, JSON, or INI.

Example Usage

Specify config using -c flag:

# from current working directory
geoprox run -c geoprox.toml

# from absolute path
geoprox run -c /my/custom/config.yaml

or using environment variables:

export GEOPROX_CONFIG='/my/custom/config.json'

geoprox run

Example Config

Here's an example configuration file in TOML format:

# All settings are optional; these are the default values.
[server]
# The address the server will bind to
http_addr = '0.0.0.0'
# The port the server will listen on
http_port = 5000
# Request timeout
timeout = '10s'

[shard]
# Determines the default geohash length for inserts
insert_depth = 6
# Determines the default geohash length for searches
search_depth = 6
# Specifies the default number of results returned in range queries
default_count = 100
# Toggles the default sorting behavior for query results
default_sorted = false

[server.snapshots]
# Toggle snapshot usage
disabled = false
# Directory where snapshots will be stored
path = '/var/lib/geoprox/snapshots'
# How often snapshots will be taken
every = '30s'

Environment Variables

These are the currently supported environment variables. They will take precedence over settings defined in the configuration file.

Fine Tuning

Geohashes divide the world into a grid of cells, each with a unique identifier (encoded in base 32). The precision of the geohash can be adjusted by changing its length:

• Short geohashes represent larger areas.
• Long geohashes represent smaller, more precise areas.

For example, a depth of 6 corresponds to a geohash precision of approximately 1km x 1km. This is the default depth and generally recommended, as greater precision (smaller depths) may not be necessary for most use cases.

The insert_depth and search_depth settings control the precision of geohashing and impact the performance of distance calculations and search queries.

Optimizing insert_depth

Higher Insert Depth:

• Description: Objects are grouped into smaller, more precise regions.
• Impact: Searching takes slightly longer, but distance calculations are more accurate.
• Use Case: Ideal for scenarios where precise distance measurements are crucial.

Lower Insert Depth:

• Description: Objects are grouped into larger regions.
• Impact: Search performance improves, but distance calculations become less accurate.
• Use Case: Best for cases where fast general distance estimates are acceptable.

Optimizing search_depth

Higher Search Depth:

• Description: The initial search region is smaller and more precise.
• Impact: Search queries take slightly longer, but results are more accurate.
• Use Case: Suitable for narrow range queries where high accuracy is needed.

Lower Search Depth:

• Description: The initial search region is larger, leading to faster searches.
• Impact: Search speed improves, but accuracy may be reduced.
• Use Case: Ideal for wide range queries where speed is prioritized over precision.

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

License

This project is licensed under the Apache 2.0 or MIT License (your choice).