The thing.aggregate.locations command aggregates the Things based on the bounding box (and a precision) and returns points in pre-computed Geohash bins.
When looking at a map, the bounding box limiting your results to Things within that box as defined by the upper left and lower right coordinates. For example, to get a box of all things on the island of Jamaica, you would specify the coordinate pair: (upper left) 18.67, -78.51 and (bottom right) 17.54, -76.06. This would define the upper left and lower right points of a rectangle surrounding the island. Doing so ensures that all of the results will be within that box.
What is Geohash?
A Geohash is a convenient way of expressing a location (anywhere in the world) using a short alphanumeric string, with greater precision obtained with longer strings. Geohashes divide the world into a grid of 32 cells—4 rows and 8 columns—each represented by a letter or number. For example, see the map below, the 9 cell covers half of United States of America, all of Mexico, and most of Guatemala. Each cell can be further divided into another 32 cells, which can be divided into another 32 cells, and so on. It actually identifies a rectangular cell: at each level, each extra character identifies one of 32 sub-cells. The 9x cell covers Wyoming, part of Colorado, Nebraska, and Idaho, 9xj covers area around of Denver, CO and 9xj34kh1 is the Writers Vista Park, CO.
The cell sizes of geohashes of different lengths are as follows; note that the cell width reduces moving away from the equator (to 0 at the poles):
| Geohash Precision | Cell width x Cell height |
|---|---|
| 1 | ≤ 5000km x 5000km |
| 2 | ≤ 1250km x 625km |
| 3 | ≤ 156km x 156km |
| 4 | ≤ 39.1km x 19.5km |
| 5 | ≤ 4.89km x 4.89km |
| 6 | ≤ 1.22km x 0.61km |
| 7 | ≤ 153m x 153m |
| 8 | ≤ 38.2m x 19.1m |
| 9 | ≤ 4.77m x 4.77m |
| 10 | ≤ 1.19m x 0.596m |
| 11 | ≤ 149mm x 149mm |
| 12 | ≤ 37.2mm x 18.6mm |
TR50 Request
//Using Query
{
"1": {
"command": "thing.aggregate.locations",
params": {
"query":"loc.addr.country:US",
"precision":5,
"limit":1000,
"bounds":true
}
}
}//Using BBox
{
"1":{
"command":"thing.aggregate.locations",
"params":{
"bbox":{
"bottomRight":{
"lat":-11.178401873712,
"lng":17.841796875
},
"topLeft":{
"lat":61.814663894684,
"lng":-115.576171875
}
},
"precision":"4"
}
}
}Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | String | Query to filter list of Things to be aggregated | |
| precision | Integer | The size of the buckets used for returning the points, larger precision will result in more results. The valid precision values are from 1 to 12, where 1 creates large buckets (each bucket covers a large area and there are fewer buckets) and 12 creates small buckets (each bucket covers a tiny area and there are significantly more buckets). | |
| limit | Integer | Limit the number of boxes returned, if the limit is reached, the largest buckets will be returned. | |
| bounds | Boolean | Return the bounding boxes for each bucket, as well as the total viewport. If set to false only the centroid of each bucket is returned. |
TR50 Response
If the command is sent successfully a success message is returned. Otherwise, an error and error message will be returned.
//Response using Query
{
"1": {
"success": true,
"params": {
"bbox": {
"bottomRight": {
"lat": 0,
"lng": 0
},
"topLeft": {
"lat": 39.57275390625,
"lng": -105.01831054688
}
},
"count": 2,
"result": [
{
"geohash": "dhxn15",
"lat": 26.384,
"lng": -80.11,
"bbox": {
"topLeft": {
"lat": 26.38916015625,
"lng": -80.1123046875
},
"bottomRight": {
"lat": 26.383666992188,
"lng": -80.101318359375
}
},
"count": 1
},
{
"geohash": "9xj347",
"lat": 39.568,
"lng": -105.01,
"bbox": {
"topLeft": {
"lat": 39.57275390625,
"lng": -105.01831054688
},
"bottomRight": {
"lat": 39.567260742188,
"lng": -105.00732421875
}
},
"count": 1
}
],
"things": 2
}
}
}//Response using BBox
{
"1":{
"success":true,
"params":{
"count":12,
"result":[
{
"geohash":"dhxn",
"lat":26.4,
"lng":-80.1,
"count":22
},
{
"geohash":"dhwv",
"lat":26.2,
"lng":-80.5,
"count":3
},
{
"geohash":"9y53",
"lat":34,
"lng":-96.6,
"count":3
},
{
"geohash":"dhxj",
"lat":26.2,
"lng":-80.1,
"count":2
},
{
"geohash":"dhxh",
"lat":26.1,
"lng":-80.1,
"count":2
},
{
"geohash":"6ztx",
"lat":-1.5,
"lng":-48.5,
"count":2
},
{
"geohash":"s1z0",
"lat":9.9,
"lng":9.9,
"count":1
},
{
"geohash":"s0u7",
"lat":4.8,
"lng":6,
"count":1
},
{
"geohash":"dhwy",
"lat":26.4,
"lng":-80.5,
"count":1
},
{
"geohash":"dhp4",
"lat":22.9,
"lng":-80.1,
"count":1
},
{
"geohash":"9zvx",
"lat":44.9,
"lng":-93.5,
"count":1
},
{
"geohash":"7pkd",
"lat":-3.8,
"lng":-38.6,
"count":1
}
],
"things":40
}
}
}Response Parameters
| Name | Type | Description |
|---|---|---|
| bbox | String | Total view port or the root bounding box that covers the entire area that is queried. |
| topLeft | Object | The top left (NW corner) of the bounding box |
| bottomRight | Object | The bottom right (SE corner) of the bounding box |
| count | Integer |
The count below the bbox shows the total number of Things found in the entire view port. The count below the individual geohash buckets are the Things found in each bucket. |
| result | Array |
The result set of the returned geohash buckets. The precision in the request is set to 5 and the corresponding geohash buckets returned contains 5 characters. There are only 2 buckets ( |
| geohash | String | The geohash buckets. The lat and lng (under each geohash) are the centroids of the buckets. |
| things | Integer | The total number of Things found. |