feat(GeoSearch): add geospatial query support (algolia#105)

Author: Wackymax

helper/lib/src/model/search_state.dart

@@ -40,6 +40,12 @@ class SearchState implements MultiSearchState {
  this.tagFilters,
  this.userToken,
  this.clickAnalytics,
+ this.aroundLatLngViaIP,
+ this.aroundLatLng,
+ this.aroundRadius,
+ this.minimumAroundRadius,
+ this.aroundPrecision,
+ this.insideBoundingBox,
  });
 
  /// Index name
@@ -122,6 +128,169 @@ class SearchState implements MultiSearchState {
  /// events.
  final bool? clickAnalytics;
 
+ ///
+ /// **AroundLatLngViaIP**
+ ///
+ /// Search for entries around a given location automatically computed from the requester’s IP address.
+ /// By computing a central geolocation (from an IP), this has three consequences:
+ /// - a radius / circle is computed automatically, based on the density of the records near the point defined by this setting
+ /// - only records that fall within the bounds of the circle are returned
+ /// - records are ranked according to the distance from the center of the circle
+ ///
+ /// **Usage notes:**
+ /// - With this setting, you are using the end user’s IP to define a central axis point of a circle in geo-coordinates.
+ /// - Algolia automatically calculates the size of the circular radius around this central axis.
+ /// - To control the precise size of the radius, you would use [aroundRadius].
+ /// - To control a minimum size, you would use [minimumAroundRadius].
+ /// - If you are sending the request from your servers, you must set the X-Forwarded-For HTTP header with the front-end user’s IP address for it to be used as the basis for the computation of the search location.
+ /// - Note: This setting differs from [aroundLatLng], which allows you to specify the exact latitude and longitude of the center of the circle.
+ /// - This parameter will be ignored if used along with [insideBoundingBox] or [insidePolygon]
+ /// - We currently only support IPv4 addresses. If the end user has an IPv6 address, this parameter won’t work as intended.
+ ///
+ /// Source: [Learn more](https://www.algolia.com/doc/api-reference/api-parameters/aroundLatLngViaIP/)
+ ///
+ final bool? aroundLatLngViaIP;
+
+ ///
+ /// **AroundLatLng**
+ ///
+ /// Search for entries around a central geolocation, enabling a geo search within a circular area.
+ ///
+ /// By defining this central point, there are three consequences:
+ /// - a radius / circle is computed automatically, based on the density of the records near the point defined by this setting
+ /// - only records that fall within the bounds of the circle are returned
+ /// - records are ranked according to the distance from the center of the circle
+ ///
+ /// **Usage notes:**
+ /// - With this setting, you are defining a central point of a circle, whose geo-coordinates are expressed as two floats separated by a comma.
+ /// - Note: This setting differs from [aroundLatLngViaIP], which uses the end user’s IP to determine the geo-coordinates.
+ /// - This parameter will be ignored if used along with [insideBoundingBox] or [insidePolygon]
+ /// - To control the maximum size of the radius, you would use [aroundRadius].
+ /// - To control the minimum size, you would use [minimumAroundRadius].
+ /// - The size of this radius depends on the density of the area around the central point. If there are a large number of hits close to the central point, the radius can be small. The less hits near the center, the larger the radius will be.
+ /// - Note: If the results returned are less than the number of hits per page (hitsPerPage), then the number returned will be less than the hitsPerPage. For example, if you recieve 15 results, you could still see a larger number of hits per page, such as hitsPerPage=20.
+ ///
+ /// Source: [Learn more](https://www.algolia.com/doc/api-reference/api-parameters/aroundLatLng/)
+ ///
+ final String? aroundLatLng;
+
+ ///
+ /// **AroundRadius**
+ ///
+ /// Define the maximum radius for a geo search (in meters).
+ ///
+ /// **Usage notes:**
+ /// - This setting only works within the context of a radial (circuler) geo search,
+ /// enabled by `aroundLatLngViaIP` or `aroundLatLng`.
+ /// - ***How the radius is calculated:***
+ /// - If you specify the meters of the radius (instead of `all`), then only records
+ /// that fall within the bounds of the circle (as defined by the radius) will be
+ /// returned. Additionally, the ranking of the returned hits will be based on the
+ /// distance from the central axist point.
+ /// - If you use `all`, there is no longer any filtering based on the radius. All
+ /// relevant results are returned, but the ranking is still based on the distance
+ /// from the central axis point.
+ /// - If you do not use this setting, and yet perform a radial geo search (using
+ /// `aroundLatLngViaIP` or `aroundLatLng`), the radius is automatically computed
+ /// from the density of the searched area. See also `minimumAroundRadius`, which
+ /// determines the minimum size of the radius.
+ /// - For this setting to have any effect on your ranking, the geo criterion must be
+ /// included in your ranking formula (which is the case by default).
+ ///
+ /// **Options:**
+ /// - `radius_in_meters`: Integer value (in meters) representing the radius around the
+ /// coordinates specified during the query.
+ /// - `all`: Disables the radius logic, allowing all results to be returned, regardless
+ /// of distance. Ranking is still based on proxiùmity to the central axis point. This
+ /// option is faster than specifying a high integer value.
+ ///
+ /// value must be a `int` or `'all'`
+ ///
+ /// `1 = 1 Meter`
+ ///
+ /// `Therefore for 1000 = 1 Kilometer`
+ ///
+ /// `'aroundRadius' => 1000` // 1km
+ ///
+ /// Source: [Learn more](https://www.algolia.com/doc/api-reference/api-parameters/aroundRadius/)
+ ///
+ final dynamic aroundRadius;
+
+ ///
+ /// **AroundPrecision**
+ ///
+ /// Precision of geo search (in meters), to add grouping by geo location to the ranking
+ /// formula.
+ ///
+ /// When ranking hits, geo distances are grouped into ranges of `aroundPrecision` size.
+ /// All hits within the same range are considered equal with respect to the `geo` ranking
+ /// parameter.
+ ///
+ /// For example, if you set `aroundPrecision` to `100`, any two objects lying in the range
+ /// `[0, 99m]` from the searched location will be considered equal; same for `[100, 199]`,
+ /// `[200, 299]`, etc.
+ ///
+ /// Usage notes:
+ /// - For this setting to have any effect, the [geo criterion](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/in-depth/ranking-criteria#geo-if-applicable)
+ /// must be included in your ranking formula (which is the case by default).
+ ///
+ /// `1 = 1 Meter`
+ ///
+ /// `Therefore for 1000 = 1 Kilometer`
+ ///
+ /// `'aroundPrecision' => 1000` // 1km
+ ///
+ /// Source: [Learn more](https://www.algolia.com/doc/api-reference/api-parameters/aroundPrecision/)
+ ///
+ final int? aroundPrecision;
+
+ ///
+ /// **MinimumAroundRadius**
+ ///
+ /// Minimum radius (in meters) used for a geo search when `aroundRadius` is not set.
+ ///
+ /// When a radius is automatically generated, the area of the circle might be too
+ /// small to include enough records. This setting allows you to increase the size
+ /// of the circle, thus ensuring sufficient coverage.
+ ///
+ /// **Usage notes:**
+ /// - This setting only works within the context of a circular geo search,
+ /// enabled by `aroundLatLng` or `aroundLatLngViaIP`.
+ /// - This parameter is ignored when `aroundRadius` is set.
+ ///
+ /// `1 = 1 Meter`
+ ///
+ /// `Therefore for 1000 = 1 Kilometer`
+ ///
+ /// `'minimumAroundRadius' => 1000` // 1km
+ ///
+ /// Source: [Learn more](https://www.algolia.com/doc/api-reference/api-parameters/minimumAroundRadius/)
+ ///
+ final int? minimumAroundRadius;
+
+ ///
+ /// **InsideBoundingBox**
+ ///
+ /// Search inside a rectangular area (in geo coordinates).
+ ///
+ /// The rectangle is defined by two diagonally opposite points (hereafter `p1` and `p2`),
+ /// hence by 4 floats: `p1Lat`, `p1Lng`, `p2Lat`, `p2Lng`.
+ ///
+ /// For example: `insideBoundingBox = [ 47.3165, 4.9665, 47.3424, 5.0201 ]`
+ ///
+ /// **Usage notes**
+ /// - You may specify multiple bounding boxes, in which case the search will use the
+ /// union (OR) of the rectangles. To do this, pass either:
+ /// - more than 4 values (must be a multiple of 4: 8, 12…); example:
+ /// `47.3165,4.9665,47.3424,5.0201,40.9234,2.1185,38.6430,1.9916`;
+ /// - [aroundLatLng] and [aroundLatLngViaIP] will be ignored if used along with this
+ /// parameter.
+ /// - Be careful when your coordinates cross over the `180th meridian`.
+ ///
+ /// Source: [Learn more](https://www.algolia.com/doc/api-reference/api-parameters/insideBoundingBox/)
+ ///
+ final List<double>? insideBoundingBox;
+
  /// Make a copy of the search state.
  SearchState copyWith({
  List<String>? attributesToHighlight,
@@ -148,6 +317,12 @@ class SearchState implements MultiSearchState {
  int? maxValuesPerFacet,
  int? page,
  bool? clickAnalytics,
+ bool? aroundLatLngViaIP,
+ String? aroundLatLng,
+ dynamic aroundRadius,
+ int? aroundPrecision,
+ int? minimumAroundRadius,
+ List<double>? insideBoundingBox,
  }) =>
  SearchState(
  attributesToHighlight:
@@ -176,6 +351,12 @@ class SearchState implements MultiSearchState {
  maxValuesPerFacet: maxValuesPerFacet ?? this.maxValuesPerFacet,
  page: page ?? this.page,
  clickAnalytics: clickAnalytics ?? this.clickAnalytics,
+ aroundLatLngViaIP: aroundLatLngViaIP ?? this.aroundLatLngViaIP,
+ aroundLatLng: aroundLatLng ?? this.aroundLatLng,
+ aroundRadius: aroundRadius ?? this.aroundRadius,
+ aroundPrecision: aroundPrecision ?? this.aroundPrecision,
+ minimumAroundRadius: minimumAroundRadius ?? this.minimumAroundRadius,
+ insideBoundingBox: insideBoundingBox ?? this.insideBoundingBox,
  );
 
  @override
@@ -207,7 +388,13 @@ class SearchState implements MultiSearchState {
  tagFilters.equals(other.tagFilters) &&
  analytics == other.analytics &&
  userToken == other.userToken &&
- clickAnalytics == other.clickAnalytics;
+ clickAnalytics == other.clickAnalytics &&
+ aroundLatLngViaIP == other.aroundLatLngViaIP &&
+ aroundLatLng == other.aroundLatLng &&
+ aroundRadius == other.aroundRadius &&
+ aroundPrecision == other.aroundPrecision &&
+ minimumAroundRadius == other.minimumAroundRadius &&
+ insideBoundingBox.equals(other.insideBoundingBox);
 
  @override
  int get hashCode =>
@@ -234,7 +421,13 @@ class SearchState implements MultiSearchState {
  tagFilters.hashing() ^
  analytics.hashCode ^
  userToken.hashCode ^
- clickAnalytics.hashCode;
+ clickAnalytics.hashCode ^
+ aroundLatLngViaIP.hashCode ^
+ aroundLatLng.hashCode ^
+ aroundRadius.hashCode ^
+ aroundPrecision.hashCode ^
+ minimumAroundRadius.hashCode ^
+ insideBoundingBox.hashing();
 
  @override
  String toString() => 'SearchState{'
@@ -261,5 +454,11 @@ class SearchState implements MultiSearchState {
  'sumOrFiltersScore: $sumOrFiltersScore, '
  'tagFilters: $tagFilters, '
  'userToken: $userToken, '
- 'clickAnalytics: $clickAnalytics}';
+ 'clickAnalytics: $clickAnalytics, '
+ 'aroundLatLngViaIP: $aroundLatLngViaIP, '
+ 'aroundLatLng: $aroundLatLng, '
+ 'aroundRadius: $aroundRadius, '
+ 'aroundPrecision: $aroundPrecision, '
+ 'minimumAroundRadius: $minimumAroundRadius, '
+ 'insideBoundingBox: $insideBoundingBox}';
 }

helper/lib/src/service/algolia_client_extensions.dart

@@ -49,6 +49,12 @@ extension AlgolisSearchStateExt on SearchState {
  userToken: userToken,
  filters: filters,
  clickAnalytics: clickAnalytics,
+ aroundLatLng: aroundLatLng,
+ aroundLatLngViaIP: aroundLatLngViaIP,
+ aroundPrecision: aroundPrecision,
+ aroundRadius: aroundRadius,
+ minimumAroundRadius: minimumAroundRadius,
+ insideBoundingBox: insideBoundingBox,
  );
  return search;
  }

helper/pubspec.yaml

@@ -7,20 +7,20 @@ environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '>=1.17.0'
 dependencies:
- algolia_insights: ^0.2.1
- algoliasearch: ^0.2.0
- collection: ^1.16.0
+ algolia_insights: ">=0.2.0 <1.0.0"
+ algoliasearch: ">=0.2.0 <1.0.0"
+ collection: ">=1.17.0 <2.0.0"
  flutter:
  sdk: flutter
- logging: ^1.0.2
- meta: ^1.7.0
- rxdart: ^0.27.4
+ logging: ">=1.0.0 <2.0.0"
+ meta: ">=1.7.0 <2.0.0"
+ rxdart: ">=0.26.0 <1.0.0"
 dev_dependencies:
- build_runner: 2.4.4
- flutter_lints: ^2.0.0
+ build_runner: ">=2.0.0 <3.0.0"
+ flutter_lints: ">=2.0.0 <3.0.0"
  flutter_test:
  sdk: flutter
- lints: ^2.1.0
- mockito: ^5.4.2
- provider: ^6.0.3
- test: ^1.24.0
+ lints: ">=2.1.0 <3.0.0"
+ mockito: ">=5.0.0 <6.0.0"
+ provider: ">=6.0.0 <7.0.0"
+ test: ">=1.20.0 <2.0.0"

insights/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.2.2
+
+- **CHORE**: Update dependencies to be more relaxed.
+
 ## 0.2.1
 
  - **CHORE**: Fix pana issues (#95).

insights/pubspec.yaml

@@ -8,20 +8,20 @@ environment:
  sdk: ">=2.17.5 <4.0.0"
  flutter: '>=1.17.0'
 dependencies:
- algolia_client_insights: ^0.2.0
- collection: ^1.16.0
+ algolia_client_insights: ">=0.2.0 <0.3.0"
+ collection: ">=1.17.0 <2.0.0"
  flutter:
  sdk: flutter
- hive: ^2.2.3
- logging: ^1.0.2
- meta: ^1.7.0
- path_provider: ^2.0.15
- rxdart: ^0.27.4
- uuid: ^3.0.6
+ hive: ">=2.0.0 <3.0.0"
+ logging: ">=1.0.0 <2.0.0"
+ meta: ">=1.7.0 <2.0.0"
+ path_provider: ">=2.0.0 <3.0.0"
+ rxdart: ">=0.27.0 <1.0.0"
+ uuid: ">=3.0.0 <5.0.0"
 
 dev_dependencies:
- build_runner: ^2.4.4
- lints: ^2.1.0
- mockito: ^5.4.0
- test: ^1.24.0
+ build_runner: ">=2.4.0 <3.0.0"
+ lints: ">=2.0.0 <3.0.0"
+ mockito: ">=5.0.0 <6.0.0"
+ test: ">=1.0.0 <2.0.0"
  test_api: ">=0.2.1 <0.6.0"