geoq

Geoq is a command-line tool for working with geospatial data.

It combines common GIS serialization formats with utilities for manipulating and visualizing data on a map.

For example:

# Print the geometry and the set of level 2 geohashes which covers the given geometry
$ echo '{"type":"Polygon","coordinates":[[[-34,38],[-37,32],[-23,33],[-34,38]]]}' | geoq gh covering 2 -o
{"type":"Polygon","coordinates":[[[30,10],[40,40],[20,40],[10,20],[30,10]]]}
eq
en
em
ej

# Feed that output into a map on geojson.io
$ echo '{"type":"Polygon","coordinates":[[[-34,38],[-37,32],[-23,33],[-34,38]]]}' | geoq gh covering 2 -o | geoq map

See the Manual for more examples and available commands.

Install

Geoq is installed via cargo, the Rust package manager, and requires nightly rust.

If you have all this set up, you can just run cargo install geoq.

To install Rust and the Cargo toolchain:

curl https://sh.rustup.rs -sSf | sh
rustup toolchain install nightly
rustup default nightly
cargo install geoq

You'll also need to add Cargo's bin directory to your path:

# e.g. in your ~/.bash_profile or other shell profile
export PATH="$HOME/.cargo/bin:$PATH"

Updating an Existing Installation

To pull and install a newer version from crates.io, run:

cargo install geoq --force

Supported Input Formats

Geoq will detect the following GIS input formats automatically:

• Comma-separated Lat/Lon: 34.0,-118.0
• Geohashes (base 32): 9q5
• WKT: POINT (-118.0, 34.0)
• GeoJSON: {"type": "Point", "coordinates": [-118.0, 34.0]}
• H3 Cells in Hex String format: 8c274996e1683ff

One Feature Per Line, One Line Per Feature

Geoq processes text inputs on a per-line basis, and it expects inputs not to stretch across multiple lines.

This sometimes causes problems, especially with GeoJSON, because many JSON processing tools like to output pretty-printed JSON in a multi-line format.

One way to fix this problem with pretty-printed GeoJSON is to use the jq tool:

echo '{
    "type": "Point",
    "coordinates": [30, 10]
}
' | jq -c . | geoq map

Commands

See the built-in command help using geoq --help or geoq <subcommand> --help for more detailed information on these:

• bbox - Give bounding boxes for geometries, or for a stream of geometries collectively
• centroid - Cet the centroid of a geometry
• filter - Spatial predicate filtering
  • intersects - Select features intersecting a given query geometry
  • contains - Select features contained by a given query geometry
• gh - Geohash subcommands
  • children - Get children of a geohash
  • covering - Output geohashes that "cover" a geometry
  • neighbors - Get neighbors of a Geohash
  • point - Output base 32 Geohash for a given Lat,Lon
• gj - GeoJSON subcommands
  • f - Output geometry as GeoJSON feature
  • geom - Output geometry as GeoJSON geometry
  • fc - Collect all input geometries into a GeoJSON Feature Collection
• json - JSON -> GeoJSON coercion
  • munge - Attempt to convert arbitrary JSON to a GeoJSON Feature.
• map - Visualization with geojson.io
• measure - Measurement subcommands
  • distance - Measure distances between features
  • coord-count - Give the number of vertices in geometries
• read - Debugging / format validation
• shp - Convert shapefiles to GeoJSON
• simplify - Simplify geometries, either with fixed threshold or iteratively toward target coord-count
• whereami - Output IP geolocation-based current lat/lon as GeoJSON
• wkt - Output geometries as WKT
• fgb - Working with flatgeobuf
  • write - write flatgeobuf files from GeoJSON lines to STDIN
  • read - read flatgeobuf files to GeoJSON with optional bbox filter
• h3 - Working with H3 spatial grid system
  • children- Get children for h3 cell(s)
  • covering - Generate set of H3 cells covering a geometry.
  • from-str - Convert h3 hexadecimal string IDs to 64-bit numeric ids
  • grid-disk - Get disk of given radius around given cells
  • hierarchy - Output all h3 cells for a given point, from res 0 to 15
  • parent - Get parent (or ancestor) for cells
  • point - Get H3 cell for a point
  • resolution - Get resolution for an H3 cell
  • to-str - Convert 64-bit numeric h3 index its hexadecimal string representation

See the Manual for more examples and available commands.

Development

Running Tests

cargo test

Building / Releasing

cargo publish
git tag release/<VERSION>
git push origin release/<VERSION>