@cercalia/sdk
    Preparing search index...

    Class GeofencingService

    GeofencingService - Point-in-Polygon Geofencing 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.

    • Polygon Geofences: Define zones using WKT polygon geometries
    • Circle Geofences: Define zones using center point and radius
    • Batch Processing: Check multiple points against multiple zones in one call
    • Flexible Coordinates: Support for different coordinate systems
    • Delivery zone validation
    • Fleet geofencing alerts
    • Service area verification
    • Restricted zone monitoring
    const geofencing = new GeofencingService(config);

    // Define geofence zones
    const zones: GeofenceShape[] = [
      { id: 'zone1', wkt: 'CIRCLE(2.17 41.38, 1000)' }, // 1km radius circle
      { id: 'zone2', wkt: '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
    const points: GeofencePoint[] = [
      { id: 'vehicle1', coord: { lat: 41.385, lng: 2.170 } },
      { id: 'vehicle2', coord: { lat: 41.400, lng: 2.200 } }
    ];

    const result = await geofencing.check(zones, points);
    // Returns which points are inside which zones

    https://docs.cercalia.com/docs/cercalia-webservices/geofencing/

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    config

    Methods

    check checkPoint createCircle createRectangle filterPointsInShape isInsideCircle isInsidePolygon request

    Constructors

    Properties

    config: CercaliaConfig

    Configuration for the Cercalia API connection.

    Methods

    • 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

      Returns Promise<GeofenceResult>

      Result with matches (shapes containing points)

      Error if no shapes or points provided, or API error

      const shapes = [
        { id: 'warehouse', wkt: 'CIRCLE(2.17 41.38, 500)' }
      ];
      const points = [
        { id: 'truck1', coord: { lat: 41.38, lng: 2.17 } }
      ];

      const result = await service.check(shapes, points);

      if (result.matches.length > 0) {
        logger.info('truck1 is inside the warehouse zone');
      }

    • Check if a single point is inside any of the given shapes

      Convenience method for single-point geofence checks.

      Parameters

      Returns Promise<string[]>

      Array of shape IDs that contain the point

      const deliveryZones = [
        { id: 'zone-north', wkt: 'POLYGON(...)' },
        { id: 'zone-south', wkt: 'POLYGON(...)' }
      ];

      const matchingZones = await service.checkPoint(deliveryZones, {
        lat: 41.38,
        lng: 2.17
      });

      logger.info(`Point is in zones: ${matchingZones.join(', ')}`);

    • Create a circular geofence shape helper

      Parameters

      • id: string

        Unique identifier for the geofence

      • center: Coordinate

        Center coordinate

      • radiusMeters: number

        Radius in meters

      Returns GeofenceShape

      GeofenceShape object

      const zone = service.createCircle('warehouse', { lat: 41.38, lng: 2.17 }, 1000);
      // { id: 'warehouse', wkt: 'CIRCLE(2.17 41.38, 1000)' }

    • Create a rectangular geofence shape helper

      Parameters

      • id: string

        Unique identifier for the geofence

      • southwest: Coordinate

        Southwest corner coordinate

      • northeast: Coordinate

        Northeast corner coordinate

      Returns GeofenceShape

      GeofenceShape object with polygon WKT

      const zone = service.createRectangle(
        'area1',
        { lat: 41.37, lng: 2.15 }, // SW corner
        { lat: 41.40, lng: 2.19 }  // NE corner
      );

    • Filter points to only those inside a shape

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

      Parameters

      Returns Promise<GeofencePoint[]>

      Only points that are inside the shape

      const serviceArea = { 
        id: 'delivery-zone', 
        wkt: 'POLYGON(...)' 
      };

      const allCustomers = [
        { id: 'c1', coord: { lat: 41.38, lng: 2.17 } },
        { id: 'c2', coord: { lat: 41.50, lng: 2.30 } },
        { id: 'c3', coord: { lat: 41.39, lng: 2.16 } }
      ];

      const eligibleCustomers = await service.filterPointsInShape(
        serviceArea,
        allCustomers
      );
      // Returns only customers within the delivery zone

    • Check if a point is inside a circular zone

      Convenience method for circular geofence checks.

      Parameters

      • center: Coordinate

        Center of the circular zone

      • radiusMeters: number

        Radius of the zone in meters

      • point: Coordinate

        Point to check

      Returns Promise<boolean>

      True if point is inside the circle

      const warehouseLocation = { lat: 41.38, lng: 2.17 };
      const deliveryPoint = { lat: 41.385, lng: 2.172 };

      const isNearWarehouse = await service.isInsideCircle(
        warehouseLocation,
        500, // 500m radius
        deliveryPoint
      );

      if (isNearWarehouse) {
        logger.info('Delivery is within warehouse zone');
      }

    • Check if a point is inside a polygon zone

      Convenience method for polygon geofence checks.

      Parameters

      • polygonWkt: string

        Polygon in WKT format

      • point: Coordinate

        Point to check

      Returns Promise<boolean>

      True if point is inside the polygon

      const zoneWkt = 'POLYGON((2.15 41.37, 2.19 41.37, 2.19 41.40, 2.15 41.40, 2.15 41.37))';
      const vehicleLocation = { lat: 41.38, lng: 2.17 };

      const isInZone = await service.isInsidePolygon(zoneWkt, vehicleLocation);

      if (!isInZone) {
        logger.info('Vehicle has left the designated zone!');
      }

    • Executes a generic request to the Cercalia API.

      Type Parameters

      • T

      Parameters

      • params: Record<string, string>

        Query parameters for the API request.

      • operationName: string = 'Cercalia Request'

        Human-readable name for logging and debugging.

      • OptionalbaseUrl: string

        Optional override for the base API URL.

      Returns Promise<T>

      A promise resolving to the parsed API response.

      Error with code '30006' when no results are found.

      Error for HTTP errors or invalid JSON responses.

      const response = await this.request<MyResponse>(
        { cmd: 'cand', adr: 'Gran Via 1' },
        'Geocoding'
      );

    Settings

    Member Visibility

    On This Page

    Key FeaturesUse CasesUsage Examples
    Constructors
    Properties
    Methods