### Basic store and query with Geomem Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geomem.md Shows how to add records and query them with find. The example adds points with latitude, longitude, time, value, and id, then iterates over results. Demonstrates the inclusive start and exclusive finish time range. ```java // Basic — store and query Geomem g = new Geomem(); g.add(-15, 120, 500, "A1", "a1"); // lat, lon, epoch-ms time, value, id g.add(-15, 120, 1500, "A2"); long now = System.currentTimeMillis(); g.add(-5, 100, now, "ship-1"); Iterable> result = g.find(-5, 100, -45, 170, now, now + 1_000); // start inclusive, finish exclusive for (Info info : result) { System.out.println(info.value() + " @ " + info.lat() + "," + info.lon() + " t=" + info.time()); } ``` -------------------------------- ### Info usage examples Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geomem.md Shows basic accessor usage and a non-trivial example filtering on the optional id while iterating a find result. ```java // Basic Info info = new Info(-15, 120, 500, "A1", Optional.of("a1")); double lat = info.lat(); long t = info.time(); Optional id = info.id(); String v = info.value(); // Non-trivial — filter on the optional id while iterating a find result for (Info i : g.find(-5, 100, -45, 170, 0, 60000)) { if (i.id().isPresent() && i.id().get().equals("a1")) { ... } } ``` -------------------------------- ### Usage example for coverBoundingBox and coverBoundingBoxMaxHashes Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Example usage of coverBoundingBox and coverBoundingBoxMaxHashes. Demonstrates basic usage with default max hashes, advanced usage with explicit budget (may return null), and error handling when topLeftLat is less than bottomRightLat. ```java // Basic — default max hashes (12) Coverage c = GeoHash.coverBoundingBox(42.9, -74.1, 41.7, -72.6); for (String hash : c.getHashes()) System.out.println(hash); System.out.println(c.getRatio()); // >= 1.0, closer to 1 = tighter fit System.out.println(c.getHashLength()); // Advanced — explicit budget; null possible Coverage c2 = GeoHash.coverBoundingBoxMaxHashes(42.9, -74.1, 41.7, -72.6, 700); if (c2 != null) { ... } // Error handling try { GeoHash.coverBoundingBox(0, 100, 10, 120); // topLeftLat < bottomRightLat } catch (IllegalArgumentException e) { // "topLeftLat must be >= bottomRighLat" } ``` -------------------------------- ### gridAsString usage examples Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Two Java examples: a basic call with an empty highlight set, and a non-trivial call that highlights neighbours f2 and f8 in upper case using explicit corner offsets. ```java // Basic System.out.println(GeoHash.gridAsString("dr", 1, Collections.emptySet())); // Non-trivial — highlight a neighbour in upper case System.out.println(GeoHash.gridAsString("dr", -1, -1, 1, 1, Sets.newHashSet("f2", "f8"))); ``` -------------------------------- ### Preconditions usage examples with error handling Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/preconditions.md Examples of using checkArgument and checkNotNull, including basic usage and the exact calls GeoHash makes, plus error handling try-catch blocks. ```java // Basic Preconditions.checkArgument(length > 0 && length <= 12, "length must be between 1 and 12"); String geohash = Preconditions.checkNotNull(input, "geohash cannot be null"); // Non-trivial — the exact calls GeoHash makes (source: GeoHash.java lines 141, 200, 351-352, 422, 637, 639) Preconditions.checkArgument(hash.length() > 0, "adjacent has no meaning for a zero length hash that covers the whole world"); Preconditions.checkArgument(topLeftLat >= bottomRightLat, "topLeftLat must be >= bottomRighLat"); Preconditions.checkArgument(length > 0, "length must be greater than zero"); // Error handling try { Preconditions.checkArgument(false, "boom"); } catch (IllegalArgumentException e) { // e.getMessage() == "boom" } try { Preconditions.checkNotNull(null, "must not be null"); } catch (NullPointerException e) { // e.getMessage() == "must not be null" } ``` -------------------------------- ### Basic and sign round-trip examples for encodeBase32 and decodeBase32 Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/base32.md Shows round-tripping a small value with zero-padding, using the default length, and handling negative values. The decodeBase32 method recovers the sign from a leading '-'. ```java // Basic — round-trip on a small value, zero-padded to 3 digits Base32.decodeBase32("010"); // 32 String s = Base32.encodeBase32(32, 3); // "010" String s12 = Base32.encodeBase32(32); // default length 12: "000000000010" // Non-trivial — sign round-trip String neg = Base32.encodeBase32(-32, 3); // "-010" long back = Base32.decodeBase32(neg); // -32 ``` -------------------------------- ### neighbours - get 8 surrounding hashes Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Returns a list of the 8 surrounding hashes in a fixed order: left, right, top, bottom, left-top, left-bottom, right-top, right-bottom. The example shows basic usage and how to access individual neighbours. ```java // Basic List ns = GeoHash.neighbours("drt"); // ns.get(0) == GeoHash.left("drt"), ns.get(1) == GeoHash.right("drt"), ... ``` -------------------------------- ### Coverage usage example Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/coverage.md Illustrates typical usage of Coverage: creating a coverage with GeoHash.coverBoundingBox, retrieving hashes, ratio, and hash length. Also shows using the hashes for a database lookup and handling a directly constructed empty coverage, which can occur even though GeoHash.coverBoundingBox never returns an empty coverage. ```java // Basic Coverage c = GeoHash.coverBoundingBox(42.9, -74.1, 41.7, -72.6); Set hashes = c.getHashes(); double ratio = c.getRatio(); int len = c.getHashLength(); // Non-trivial — drive a database lookup with the hashes (single equality conditions) Geomem store = ...; // see api-reference/geomem.md for (String h : hashes) { for (Info info : store.findFromHash(h)) { ... } // illustrative } // Error handling — an empty coverage never occurs from GeoHash.coverBoundingBox // (the algorithm always returns at least the covering hashes), but a directly // constructed Coverage can be empty; guard accordingly Coverage empty = new Coverage(Collections.emptySet(), 1.0); if (empty.getHashLength() == 0) { /* no hashes */ } ``` -------------------------------- ### LatLong usage example: basic, immutability, and validation Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/latlong.md Shows basic LatLong creation and getters, demonstrates that add() returns a new instance leaving the original unchanged, and illustrates defensive validation since the constructor performs no range checking. ```java // Basic LatLong p = new LatLong(-25.382708, -49.265506); double lat = p.getLat(); double lon = p.getLon(); // Non-trivial — immutability: add returns a new instance LatLong moved = p.add(1.5, -2.5); // p unchanged // Error handling / defensive use — no validation exists, so guard inputs yourself if (Math.abs(lat) > 90) throw new IllegalArgumentException("latitude out of range"); ``` -------------------------------- ### Basic and error handling examples for decodeBase32 Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/base32.md Shows decoding a valid hash and handling an IllegalArgumentException for uppercase characters. The error message is "not a base32 character: D". ```java // Basic long l = Base32.decodeBase32("drt"); String back = Base32.encodeBase32(l, 3); // "drt" // Error handling try { Base32.decodeBase32("DRT"); // uppercase } catch (IllegalArgumentException e) { // "not a base32 character: D" } ``` -------------------------------- ### gridAsString example output Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Output of gridAsString("dr", 1, Collections.emptySet()) as shown in the documentation. The returned string contains three lines of space-separated hashes. ```text f0 f2 f8 dp dr dx dn dq dw ``` -------------------------------- ### hashLengthToCoverBoundingBox - get hash length for bounding box Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Returns the maximum hash length whose cell fully encloses the given bounding box. The example shows a basic call for a box covering Schenectady NY to Hartford CT. ```java // Basic — Schenectady NY -> Hartford CT box int len = GeoHash.hashLengthToCoverBoundingBox(42.9, -74.1, 41.7, -72.6); ``` -------------------------------- ### hashContains basic usage Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Example call to hashContains with a sample geohash and coordinates. Returns a boolean indicating containment. ```java // Basic boolean inside = GeoHash.hashContains("6gkzwg", -25.382708, -49.265506); ``` -------------------------------- ### heightDegrees and widthDegrees basic usage Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Example calls to widthDegrees and heightDegrees with n=6, showing the computed degree values. The comment notes that widthDegrees(1) equals 45.0 and that height follows 180 / 2^(2.5n). ```java // Basic // widthDegrees(1) == 45.0 (test-verified); height follows 180 / 2^(2.5n) double w = GeoHash.widthDegrees(6); // 180 / 2^14 = 0.0109863... double h = GeoHash.heightDegrees(6); // 180 / 2^15 = 0.0054932... ``` -------------------------------- ### Query condition with geohash equality Source: https://github.com/davidmoten/geo/blob/master/README.md Example query condition using geohashes to replace a bounding box constraint with equality checks on geohash values, combined with a time range. ```text (startTime <= t < finishTime) and (hash3='drt' or hash3='dr2') ``` -------------------------------- ### find(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon, long start, long finish) Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geomem.md Queries the Geomem store for records within the specified bounding box and time range. The bounding box is defined by the top-left (north-west) and bottom-right (south-east) corners. The time range is inclusive of start and exclusive of finish. Returns a lazy iterable of matching records. ```APIDOC ## [GET] /find ### Description Queries the Geomem store for records within a geographic bounding box and time range. The bounding box is defined by the top-left (north-west) and bottom-right (south-east) corners. The time range is inclusive of start and exclusive of finish. Returns a lazy iterable of matching records. ### Method GET ### Endpoint /find ### Parameters #### Query Parameters - **topLeftLat** (double) - Required - Latitude of the top-left (north-west) corner of the search box. - **topLeftLon** (double) - Required - Longitude of the top-left (north-west) corner of the search box. - **bottomRightLat** (double) - Required - Latitude of the bottom-right (south-east) corner of the search box. - **bottomRightLon** (double) - Required - Longitude of the bottom-right (south-east) corner of the search box. - **start** (long) - Required - Start time in epoch milliseconds, inclusive. - **finish** (long) - Required - Finish time in epoch milliseconds, exclusive. ### Request Example ``` GET /find?topLeftLat=-5&topLeftLon=100&bottomRightLat=-45&bottomRightLon=170&start=1500000000000&finish=1500000001000 ``` ### Response #### Success Response (200) - **Iterable>** - A lazy iterable of matching records. Each record contains latitude, longitude, time, value, and optional id. #### Response Example ```json [ { "lat": -15.0, "lon": 120.0, "time": 500, "value": "A1", "id": "a1" } ] ``` ### Error Handling - **IllegalArgumentException** - Thrown if `topLeftLat < bottomRightLat` (message: "topLeftLat must be >= bottomRighLat"). Also thrown if a null record is encountered during iteration (message: "info cannot be null"). ``` -------------------------------- ### Info Constructor Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geomem.md Creates a new Info instance with the specified latitude, longitude, time, value, and optional id. ```APIDOC ## Constructor ### Description Creates a new Info instance with the specified latitude, longitude, time, value, and optional id. ### Method Constructor ### Endpoint `public Info(double lat, double lon, long time, T value, Optional id)` ### Parameters #### Constructor Parameters - **lat** (double) - Required - Latitude in decimal degrees - **lon** (double) - Required - Longitude in decimal degrees - **time** (long) - Required - Time in epoch ms - **value** (T) - Required - The record value - **id** (Optional) - Required - Optional record id (Guava Optional) ### Request Example ```java Info info = new Info(-15, 120, 500, "A1", Optional.of("a1")); ``` ### Response #### Success Response No return value (constructor). #### Response Example No response body. ``` -------------------------------- ### Info constructor Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geomem.md Constructs an Info instance with latitude, longitude, time, value, and optional id. ```java public Info(double lat, double lon, long time, T value, Optional id) ``` -------------------------------- ### Direction.opposite() Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/direction.md Returns the opposite compass direction. For example, opposite(BOTTOM) = TOP, opposite(TOP) = BOTTOM, opposite(LEFT) = RIGHT, opposite(RIGHT) = LEFT. ```APIDOC ## Direction.opposite() ### Description Returns the opposite direction of this Direction constant. The mapping is: BOTTOM -> TOP, TOP -> BOTTOM, LEFT -> RIGHT, RIGHT -> LEFT. ### Method public Direction opposite() ### Returns - **Direction** - The opposite direction constant. ### Example ```java Direction d = Direction.RIGHT; Direction back = d.opposite(); // Direction.LEFT ``` ``` -------------------------------- ### Coverage Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/coverage.md Documentation for the Coverage class, including its constructor and public methods. ```APIDOC ## Coverage ### Description Immutable value class representing a set of geohashes plus a ratio measuring how well that set covers a given bounding box. Returned by `GeoHash.coverBoundingBox` and `GeoHash.coverBoundingBoxMaxHashes`. ### Constructor ```java public Coverage(Set hashes, double ratio) ``` | Parameter | Type | Required | Description | |---|---|---|---| | `hashes` | `Set` | yes | the set of hashes comprising the coverage (kept by reference — not defensively copied) | | `ratio` | `double` | yes | ratio of area of hashes to area of the target region (will be ≥ 1) | ### Methods #### getHashes ```java public Set getHashes() ``` **Returns:** `Set` — the hashes of the coverage, all expected to have the same length (a `TreeSet` sort order when produced by `GeoHash`). #### getRatio ```java public double getRatio() ``` **Returns:** `double` — total area covered by the hashes divided by the area of the bounding box (degrees squared). Closer to 1 means the hashes approximate the bounding box more tightly; will be ≥ 1. #### getHashLength ```java public int getHashLength() ``` **Returns:** `int` — length (in characters) of the first hash returned by an iterator on the hash set (all hashes in a coverage are the same length); returns `0` if the set is empty. #### toString ```java @Override public String toString() ``` **Returns:** `String` — formatted as `Coverage [hashes=, ratio=]`. ### Example Usage ```java // Basic Coverage c = GeoHash.coverBoundingBox(42.9, -74.1, 41.7, -72.6); Set hashes = c.getHashes(); double ratio = c.getRatio(); int len = c.getHashLength(); // Non-trivial — drive a database lookup with the hashes (single equality conditions) Geomem store = ...; // see api-reference/geomem.md for (String h : hashes) { for (Info info : store.findFromHash(h)) { ... } // illustrative } // Error handling — an empty coverage never occurs from GeoHash.coverBoundingBox // (the algorithm always returns at least the covering hashes), but a directly // constructed Coverage can be empty; guard accordingly Coverage empty = new Coverage(Collections.emptySet(), 1.0); if (empty.getHashLength() == 0) { /* no hashes */ } ``` ``` -------------------------------- ### Coverage constructor Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/coverage.md Constructor for the Coverage class. Takes a set of hashes and a ratio. The hashes set is kept by reference, not defensively copied. The ratio is the area of hashes divided by the area of the target region and will be at least 1. ```java public Coverage(Set hashes, double ratio) ``` -------------------------------- ### Direction.opposite() non-trivial usage with adjacentHash Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/direction.md Shows non-trivial usage where opposite() is applied internally by adjacentHash when steps is negative. The example calls adjacentHash with Direction.RIGHT and -3 steps, which internally uses Direction.LEFT with 3 steps. ```java // Non-trivial — adjacency + sign-flipped steps rely on this inversion String h = GeoHash.adjacentHash("drt", Direction.RIGHT, -3); // internally: adjacentHash(hash, Direction.LEFT, 3) ``` -------------------------------- ### Method signatures for coverBoundingBox and coverBoundingBoxMaxHashes Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Method signatures for the three overloads of coverBoundingBox and coverBoundingBoxMaxHashes. The first two are static methods returning Coverage. The third is a 5-arg overload with an exact length parameter. ```java public static Coverage coverBoundingBox(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon) public static Coverage coverBoundingBoxMaxHashes(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon, int maxHashes) public static Coverage coverBoundingBox(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon, int length) ``` -------------------------------- ### adjacentHash - move steps in a direction Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Returns the hash a given number of cells away in a direction. Negative steps use the opposite direction. The example shows basic usage and a non-trivial case with negative steps. ```java // Basic — 4 hashes east of "drt" String h = GeoHash.adjacentHash("drt", Direction.RIGHT, 4); // Non-trivial — 2 hashes west (negative steps == 2 hashes east of left edge handling) String h2 = GeoHash.adjacentHash("drt", Direction.RIGHT, -2); // == adjacentHash("drt", Direction.LEFT, 2) ``` -------------------------------- ### gridAsString(String hash, int size, Set highlightThese) Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geohash.md Generates a square grid of geohashes with the given half-extent size, highlighting the specified hashes in uppercase. ```APIDOC ## [GET] gridAsString ### Description Generates a square grid of geohashes centered on the reference hash, with a half-extent size. The grid is rendered as lines of space-separated hashes, and the specified hashes are highlighted in uppercase. ### Method GET ### Endpoint gridAsString(String hash, int size, Set highlightThese) ### Parameters #### Path Parameters - **hash** (String) - Required - Reference (central) hash - **size** (int) - Required - Half-extent of the square grid in hashes - **highlightThese** (Set) - Required - Set of hashes to render in uppercase ### Request Example ```java GeoHash.gridAsString("dr", 1, Sets.newHashSet("f2", "f8")); ``` ### Response #### Success Response (200) - **String** - Lines of space-separated hashes; each hash at offset (right, bottom) is computed as adjacentHash(adjacentHash(hash, Direction.RIGHT, right), Direction.BOTTOM, bottom). #### Response Example ``` f0 f2 f8 dp dr dx dn dq dw ``` ``` -------------------------------- ### toString() Source: https://github.com/davidmoten/geo/blob/master/_autodocs/api-reference/geomem.md Returns a string representation of the Info object. ```APIDOC ## toString() ### Description Returns a string representation of the Info object. ### Method Accessor ### Endpoint `public String toString()` ### Parameters None ### Request Example ```java String s = info.toString(); ``` ### Response #### Success Response - **toString** (String) - Formatted as `Info [lat=, lon=, time=