# Geoq Usage Manual
## Input Formats
For most commands, geoq accepts linewise input via STDIN. The following common GIS formats are accepted:
* WKT
* GeoJSON
* Geohashes (Base 32 encoded, e.g. `9q5`)
* Comma or Tab-separated Latitude/Longitude Pairs: `12.0,34.0` or `12.0 34.0`
Remember that even for WKT or GeoJSON inputs, they must be submitted **1 per line**. [jq](https://stedolan.github.io/jq/) can be useful for compacting unruly GeoJSON inputs if needed: `cat multi_line_geojsons.json | jq -cr . | geoq ...`.
### Note on Feature Collections
GeoJSON includes a [Feature Collection](https://macwright.org/2015/03/23/geojson-second-bite.html#featurecollection) type which represents a collection of multiple GeoJSON features.
When reading a Feature Collection, geoq will actually unwrap the collection and treat its features as individual inputs, e.g.:
```
echo '{"features":[{"geometry":{"coordinates":[-118.44,34.7],"type":"Point"},"properties":{},"type":"Feature"},{"geometry":{"coordinates":[-117.87,35.06],"type":"Point"},"properties":{},"type":"Feature"}],"type":"FeatureCollection"}' | geoq wkt
POINT(-118.44 34.7)
POINT(-117.87 35.06)
```
This behaves the same as if you had provided each point as its own GeoJSON feature on its own line in absence of the Feature Collection.
This is useful for exploding and manipulating individual features, and it means that `geoq gj fc` can even be used to concat multiple feature collections. If you actually want to have a collection of Lines/Polygons/Points treated as a single geometry, try one of the [Multi- Geometry variants](https://macwright.org/2015/03/23/geojson-second-bite.html#multi-geometries).
## Commands
### GeoJSON - `geoq gj`
#### As Geometry: `geoq gj geom`
```
```
#### As Feature: `geoq gj f`
```
```
#### As FeatureCollection: `geoq gj fc`
Note: This command behaves as an aggregation -- it will gather all inputs provided via STDIN and combine them into a single GeoJSON Feature Collection.
```
print "12,34\n56,78\n" | geoq gj fc | jq
{
"features": [
{
"geometry": {
"coordinates": [
34,
12
],
"type": "Point"
},
"properties": {},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
78,
56
],
"type": "Point"
},
"properties": {},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
```
### WKT - `geoq wkt`
Output each entity as WKT:
```
```
### Geohashes - `geoq gh`
#### Geohash for a point - `geoq gh point`
Get the Base 32 geohash representation for a point at a given character level.
Note that only Point geometries are supported for this operation.
```
echo '{"coordinates":[34.0,12.0],"type":"Point"}' | geoq gh point 3
sf0
```
#### Geohash neighbors - `geoq gh neighbors`
Get the adjacent geohashes for a given geohash.
Only geohash inputs are supported.
```
9q7
9qk
9qh
9mu
9mg
9mf
9q4
9q6
```
Note: By default, the given geohash is also included in the output, giving a full 3x3 grid centered on the given geohash. **To reverse this behavior, use the `-e` flag.**
```
9qk
9qh
9mu
9mg
9mf
9q4
9q6
```
#### Geohash children - `geoq gh children`
```
9q51
9q52
9q53
9q54
9q55
9q56
(...)
```
#### Covering geohashes - `geoq gh covering`
Get the set of geohashes "covering" each provided entity. This is useful for doing geohash tiling of geometries.
```
djf85
djdxu
```
It's also possible to include the original input with its list of geohashes. Use the `-o` flag for this:
```
djf8h
djf85
djdxu
```
### Mapping - `geoq map`
Display given entities on a map using [geojson.io](http://geojson.io).
```
This involves a 2-step process where geoq first aggregates all your inputs into a GeoJSON Feature Collection (similar to `geoq gj fc`), and then sends the result to geojson.io in your browser via a URL parameter.
Unfortunately, there is a limit on the amount of data that can be sent to geojson.io this way, so larger inputs will not work. We hope to have a better solution for this in the future but for now GeoJSON data over 27k characters will be rejected.
### Filtering - `geoq filter`
Select geometries which match certain conditions
#### Filter by Polygon intersection: `geoq filter intersects <query>`
Will output only those entities which intersect the given query geometry.
Currently only polygons are supported for querying, but hopefully more geometries will be added soon.
```
print "34.70,-118.44\n35.06,-117.87\n" | geoq filter intersects 9q5
34.70,-118.44
```