Package com.cercalia.sdk.services

Class GeofencingService

java.lang.Object
com.cercalia.sdk.CercaliaClient
com.cercalia.sdk.services.GeofencingService
public class GeofencingService extends CercaliaClient
GeofencingService - Point-in-Polygon checks using Cercalia InsideGeoms API.

This service checks whether points are inside defined geographic zones (geofences). Essential for delivery zone validation, fleet monitoring, and location-based alerts.

Example usage: 


 GeofencingService service = new GeofencingService(config);
 
 // Define geofence zones
 List<GeofenceShape> zones = Arrays.asList(
     GeofenceShape.circle("zone1", 2.17, 41.38, 1000), // 1km radius circle
     new GeofenceShape("zone2", "POLYGON((2.15 41.37, 2.19 41.37, 2.19 41.40, 2.15 41.40, 2.15 41.37))")
 );
 
 // Check points against zones
 List<GeofencePoint> points = Arrays.asList(
     GeofencePoint.of("vehicle1", 41.385, 2.170),
     GeofencePoint.of("vehicle2", 41.400, 2.200)
 );
 
 GeofenceResult result = service.check(zones, points, GeofenceOptions.defaults());
See Also:

  • Constructor Details

    • GeofencingService

      public GeofencingService(@NotNull @NotNull CercaliaConfig config)
      Creates a new GeofencingService with the specified configuration.
      Parameters:
      config - the Cercalia configuration

  • Method Details

    • check

      @NotNull public @NotNull GeofenceResult check(@NotNull @NotNull List<GeofenceShape> shapes, @NotNull @NotNull List<GeofencePoint> points, @NotNull @NotNull GeofenceOptions options)
      Check which points are inside which geofence shapes.

      Performs point-in-polygon checks for all combinations of shapes and points. Returns only shapes that contain at least one point.

      Parameters:
      shapes - array of geofence shapes (polygons or circles)
      points - array of points to check
      options - optional coordinate system settings
      Returns:
      result with matches (shapes containing points)
      Throws:
      CercaliaException - if no shapes or points provided, or API error

    • checkAsync

      @NotNull public @NotNull CompletableFuture<GeofenceResult> checkAsync(@NotNull @NotNull List<GeofenceShape> shapes, @NotNull @NotNull List<GeofencePoint> points, @NotNull @NotNull GeofenceOptions options)
      Check which points are inside which geofence shapes asynchronously.
      Parameters:
      shapes - array of geofence shapes
      points - array of points to check
      options - optional coordinate system settings
      Returns:
      CompletableFuture with the result

    • checkPoint

      @NotNull public @NotNull List<String> checkPoint(@NotNull @NotNull List<GeofenceShape> shapes, @NotNull @NotNull Coordinate point)
      Check if a single point is inside any of the given shapes.

      Convenience method for single-point geofence checks.

      Parameters:
      shapes - array of geofence shapes
      point - coordinate to check
      Returns:
      list of shape IDs that contain the point

    • checkPointAsync

      @NotNull public @NotNull CompletableFuture<List<String>> checkPointAsync(@NotNull @NotNull List<GeofenceShape> shapes, @NotNull @NotNull Coordinate point)
      Check if a single point is inside any of the given shapes asynchronously.
      Parameters:
      shapes - array of geofence shapes
      point - coordinate to check
      Returns:
      CompletableFuture with list of shape IDs that contain the point

    • isInsideCircle

      public boolean isInsideCircle(@NotNull @NotNull Coordinate center, double radiusMeters, @NotNull @NotNull Coordinate point)
      Check if a point is inside a circular zone.

      Convenience method for circular geofence checks.

      Parameters:
      center - center of the circular zone
      radiusMeters - radius of the zone in meters
      point - point to check
      Returns:
      true if point is inside the circle

    • isInsideCircleAsync

      @NotNull public @NotNull CompletableFuture<Boolean> isInsideCircleAsync(@NotNull @NotNull Coordinate center, double radiusMeters, @NotNull @NotNull Coordinate point)
      Check if a point is inside a circular zone asynchronously.
      Parameters:
      center - center of the circular zone
      radiusMeters - radius of the zone in meters
      point - point to check
      Returns:
      CompletableFuture with true if point is inside the circle

    • isInsidePolygon

      public boolean isInsidePolygon(@NotNull @NotNull String polygonWkt, @NotNull @NotNull Coordinate point)
      Check if a point is inside a polygon zone.

      Convenience method for polygon geofence checks.

      Parameters:
      polygonWkt - polygon in WKT format
      point - point to check
      Returns:
      true if point is inside the polygon

    • isInsidePolygonAsync

      @NotNull public @NotNull CompletableFuture<Boolean> isInsidePolygonAsync(@NotNull @NotNull String polygonWkt, @NotNull @NotNull Coordinate point)
      Check if a point is inside a polygon zone asynchronously.
      Parameters:
      polygonWkt - polygon in WKT format
      point - point to check
      Returns:
      CompletableFuture with true if point is inside the polygon

    • filterPointsInShape

      @NotNull public @NotNull List<GeofencePoint> filterPointsInShape(@NotNull @NotNull GeofenceShape shape, @NotNull @NotNull List<GeofencePoint> points)
      Filter points to only those inside a shape.

      Useful for filtering a list of locations to only those within a service area.

      Parameters:
      shape - single geofence shape
      points - array of points to filter
      Returns:
      only points that are inside the shape

    • filterPointsInShapeAsync

      @NotNull public @NotNull CompletableFuture<List<GeofencePoint>> filterPointsInShapeAsync(@NotNull @NotNull GeofenceShape shape, @NotNull @NotNull List<GeofencePoint> points)
      Filter points to only those inside a shape asynchronously.
      Parameters:
      shape - single geofence shape
      points - array of points to filter
      Returns:
      CompletableFuture with only points that are inside the shape

    • createCircle

      @NotNull public @NotNull GeofenceShape createCircle(@NotNull @NotNull String id, @NotNull @NotNull Coordinate center, double radiusMeters)
      Create a circular geofence shape helper.
      Parameters:
      id - unique identifier for the geofence
      center - center coordinate
      radiusMeters - radius in meters
      Returns:
      GeofenceShape object

    • createRectangle

      @NotNull public @NotNull GeofenceShape createRectangle(@NotNull @NotNull String id, @NotNull @NotNull Coordinate southwest, @NotNull @NotNull Coordinate northeast)
      Create a rectangular geofence shape helper.
      Parameters:
      id - unique identifier for the geofence
      southwest - southwest corner coordinate
      northeast - northeast corner coordinate
      Returns:
      GeofenceShape object with polygon WKT