Search Distance Within

Description

The "Search Distance Within" beta endpoint allows you to search a region of many Geographies at once on the earth using a point of reference and a radius in meters.

Proto Definition


service BGSearchBeta {
	rpc BetaSearchDistWithin (BetaSearchDistWithinArgs) returns (stream BetaSearchResult){}
}

Input Message

Name: BetaSearchDistWithinArgs

Attribute	Type	Description
`collection`	`string`	The collection to search.
`search_geometry`	`LatLng`	The Geography used to search on the surface of the earth. Please reference LatLng.
`distance_m`	`double`	The distance from the input geometry to search.
`controls`	`BetaSearchControls`	Controlling whether you would like to obtain the geometries only, or payload, or both, as well as controlling the level of aggregation returned.

BetaSearchControls:

Attribute	Type	Description
`return_geometries`	`bool`	Controls whether the search returns geometries (it'll always return IDs).
`return_payloads`	`bool`	Controls whether the search returns payloads associated with geometries.
`geometries_chunk_size`	`uint64`	Controls the number of geometries returned in each streamed `BetaSearchResult` message. If 0 is passed, it'll return the search result geometries one by one which is very slow.
`aggregates_chunk_size`	`uint64`	Controls the number of aggregated triangles returned in each streamed `BetaSearchResult` message. If 0 is passed, it'll return the search result triangles one by one which is very slow.
`aggregationArgs`	`AggregationArgs`?	Controls the aggregation behaviour. If it's not set, no aggregation happens.

AggregationArgs:

Attribute	Type	Description
`max_geoms_per_cell`	`uint64`	The maximum number of geometries before BG-Search returns an aggregate view for that cell. A good value depends on your data but a reasonable range is between 50 to 200. Lower number means more aggressive aggregation.
`resolution_offset`	`uint64`	Controls the resolution of the aggregated cells returned. a good range of values in 2 to 4.
`max_additional_refines`	`uint64`	The maximum additional refinement for the aggregated cells. It should be 0 for most use cases.
`count_refine_factor`	`double`	This a threshold for when to do the additional refinement aggregate. Use 1.0 for start.

message BetaSearchControls {
  bool return_geometries = 1;
  bool return_payloads = 2;
  uint64 geometries_chunk_size = 3;
  uint64 aggregates_chunk_size = 4;
  optional AggregationArgs aggregationArgs = 5;
};

message BetaSearchDistWithinArgs {
  string collection = 1;
  double distance_m = 2;
  oneof search_geometry {
    LatLng point = 3;
    // LineStrip line_strip = 4;
    // Polygon polygon = 5;
  };
  reserved 4, 5;
  reserved "line_strip", "polygon";
  reserved 10 to 14;
  BetaSearchControls controls = 15;
}

Output Message

A stream of the Results from the search containing aggregated Triangles and individual Geographies that are sparse enough to not be aggregated.

The result is either a Geometry or Aggregate, the description of each is given below:

Geometry:

Attribute	Type	Description
`id`	`GeometryId`	The id of the Geometry, more information can be found here.
`Geometry`	`IndexableGeometry`	The Geometry found from the search, with a type defined here.
`payload`	`Payload`	The payload associated with this Geometry, more information about this type can be found here.

Aggregate:

Attribute	Type	Description
`cell_index`	`DGGSIndex`	The corresponding DGGSIndex of the aggregated cell. This type is the same as that returned by PointToDGGSIndex.
`cell_vertices`	`Ring`	The Ring denoting the vertices of the triangle on the earth. Information about the Ring type can be found here.
`point_count`	`uint64`	The number of LatLng contained in this aggregate Triangle.
`non_point_count`	`uint64`	The number of Geometries excluding LatLng contained in this aggregate Triangle.
`mean_point`	`LatLng`	The mean point used to represent the aggregate cell in LatLng for heatmap visualization.

BetaSearchResult

Attribute	Type	Description
`geometries`	`Geometry[]`	A list of the Geometries found as a result of this search.
`aggregates`	`Aggregate[]`	A list of the aggregated triangles containing more information.

message BetaSearchResult {
  message Geometry {
    GeometryID id = 1;
    optional IndexableGeometry geometry = 2;
    optional Payload payload = 3;
  }
  // Subject to change
  message Aggregate {
    DGGSIndex cell_index = 1;
    Ring cell_vertices = 2;
    uint64 point_count = 3;
    uint64 non_point_count = 4;
    LatLng mean_point = 5;
  }

  repeated Geometry geometries = 1;
  repeated Aggregate aggregates = 2;
}