Geofences & Asset Monitoring API (1.0.0 Beta)

Description

Use this endpoint to add or update geofence areas. Each geofence is defined by its type, name, keywords, properties, and geographic data. The endpoint supports batch operations of up to 1,000 geofences per request.

Request Body Parameters

The request body must be a JSON object containing the following parameters:

• geofences (Array of objects): An array of geofence objects. Each geofence object includes:

  • p_id (string | optional): Unique id for the geofence. If not provided, an unique ID will be automatically generated in UUID format.

  • p_type (string): The type of the geofence, "circle", "rectangle" or "polygon".

  • p_name (string | optional): A name for the geofence.

  • p_keywords (array of strings | optional): Keywords associated with the geofence, used for searching or filtering.

  • p_properties (object | optional): Additional JSON properties related to the geofence.

  • p_geojson (object): Geographical information formatted as JSON, which includes:

    • type (string): The type of geometry, "Circle", "Rectangle" or "Polygon".

    • coordinates (Array): An array of coordinates defining the geofence area.

Response

On a successful request, the API will return a JSON array containing the following:

• id (string): The unique identifier for the added geofence.

• error (string): Any error message related to the request (if applicable).

Description

This endpoint allows you to update an existing geofence area attributes such as name, keywords, properties or area. The request requires a JSON object containing specific parameters that define the geofence area you wish to update.

Request Body Parameters

The request body should be a JSON object containing the following parameters:

• p_id (string): The unique identifier for the geofence area that needs to be updated.

• p_type (string | optional): The type of the geofence area (e.g., rectangle). Optional when not updating the geofence area.

• p_name (string | optional): The name of the geofence area.

• p_keywords (Array of strings | optional): A list of keywords associated with the geofence area.

• p_properties (object | optional): A JSON object containing the updated properties related to the geofence area

• p_geojson (object | optional): Optional when not updating the geofence area. A JSON object representing the geographical data of the geofence area, which includes:

  • type (string): The type of geometry (e.g., Rectangle).

  • coordinates (Array): The coordinates defining the shape of the geofence.

Response

Upon a successful request, the API will return a response with the following structure:

• id (string): The identifier of the updated geofence area.

• error (string): Any error message if applicable; otherwise, it will be an empty string.

Description

This endpoint allows users to delete specified geofence areas from the system. The request requires a JSON payload containing an array of geofence area identifiers (IDs) to be removed and/or an array of keywords.

Request Body Parameters

• p_ids (Array of strings | optional): A list of unique identifiers for the geofence areas that you wish to delete. Each identifier should be a valid geofence ID.

• p_keywords (Array of strings | optional): A list of keywords for the geofence areas that you wish to delete.

Expected Response

Upon successful deletion, the API will respond with a JSON object indicating which geofence areas have been deleted.

• deleted (Array of Strings): A list of identifiers for the geofence areas that were successfully deleted. If no areas were deleted, this array may be empty.

Notes

• Ensure that the provided IDs and/or keywords are correct and correspond to existing geofence areas in the system.

• This operation is irreversible; once a geofence area is deleted, it cannot be recovered.

Description

This endpoint retrieves geofence area details in GeoJSON format. It allows users to specify a list of geofence IDs to fetch their corresponding data.

Request Body Parameters

• p_ids (Array of strings): A list of geofence IDs to be retrieved.

Response

The response is a GeoJSON object that contains the following fields:

• type (string): GeoJSON feature collection.

• features (Array of objects): A collection of geofence features, each containing:

  • id (string): The unique identifier for the geofence.

  • name (string): The name of the geofence.

  • type (string): The type of geofence.

  • geometry (object): The geometric representation of the geofence, which includes:

    • type (string): The type of geometry (always Polygon).

    • coordinates (Array): An array of coordinates defining the shape of the geofence.

  • keywords (Array of strings): A list of keywords associated with the geofence.

  • properties (object): Additional JSON properties related to the geofence, which may include custom attributes.

  • type_geofence (string): The specific type of geofence (circle, rectangle or polygon).

  • rectangle_max_xy (Array of numbers): Only for rectangle geofences. The maximum longitude and latitude defining the bounding rectangle of the geofence.

  • rectangle_min_xy (Array of numbers): Only for rectangle geofences. The minimum longitude and latitude defining the bounding rectangle of the geofence.

  • circle_center (Array of numbers):
    Only for circle geofences. The circle area center point longitude and latitude.

  • circle_radius (Array of numbers):
    Only for circle geofences. The circle radius in meters.

  • created_at (integer): Unix timestamp of when the geofence was created.

  • updated_at (integer): Unix timestamp of the last update to the geofence.

Description

This endpoint retrieves geofence areas based on the specified keywords list. It allows users to paginate through the results for better management of large datasets.

Request Body Parameters

• p_keywords (Array of strings | optional): A list of keywords to filter the geofences. For example, ["warehouse"].

• p_min_longitude (float | optional): The minimum longitude of the bounding box.

• p_min_latitude (float | optional): The minimum latitude of the bounding box.

• p_max_longitude (float | optional): The maximum longitude of the bounding box.

• p_max_latitude (float | optional): The maximum latitude of the bounding box.

• p_page_no (integer | optional): The page number of the results to retrieve, starting from 1.

• p_entries_per_page (integer | optional): The number of entries to return per page (default 1000).

Response

The response is a JSON object that contains the following fields:

• data (object): JSON object containing geofences data

  • type (string): GeoJSON feature collection.

  • features (Array of objects): A collection of geofence features, each containing:

    • id (string): The unique identifier for the geofence.

    • name (string): The name of the geofence.

    • type (string): The type of geofence.

    • geometry (Object): The geometric representation of the geofence, which includes:

      • type (string): The type of geometry (always Polygon).

      • coordinates (Array): An array of coordinates defining the shape of the geofence.

    • keywords (Array of strings): A list of keywords associated with the geofence.

    • properties (Object): Additional properties related to the geofence, which may include custom attributes.

    • type_geofence (string): The specific type of geofence (circle, rectangle or polygon).

    • rectangle_max_xy (Array of numbers): Only for rectangle geofences. The maximum longitude and latitude defining the bounding rectangle of the geofence.

    • rectangle_min_xy (Array of numbers): Only for rectangle geofences. The minimum longitude and latitude defining the bounding rectangle of the geofence.

    • circle_center (Array of numbers):
      Only for circle geofences. The circle area center point longitude and latitude.

    • circle_radius (Array of numbers):
      Only for circle geofences. The circle radius in meters.

    • created_at (integer): Unix timestamp of when the geofence was created.

    • updated_at (integer): Unix timestamp of the last update to the geofence.

• page (object): Pagination information including:

  • page_no (integer): The current page number.

  • has_more (boolean): Indicates if there are more entries available.

  • total_pages (integer): Total number of pages available.

  • total_entries (integer): Total number of entries available.

  • offset_entries (integer): Number of entries offset from the start.

  • entries_per_page (integer): Number of entries per page.

Description

This endpoint checks whether specified locations are contained within given geofences. It is useful for applications that need to determine if certain geographical points fall within predefined areas.

Request Body Parameters

The request body must be in JSON format and should include the following parameters:

• p_geofence_ids (Array of strings): An array of geofence identifiers that you want to check against.

• p_locations (Array of arrays): An array of locations, where each location is represented as an array containing longitude and latitude values. For example, [[longitude, latitude]].

Response

The response will be in JSON format and will include the following structure:

• checked_geofences (Array): An array containing the results for each geofence checked.

  • locations (Array): An array of location results for each geofence.

    • index (integer): The index of the location in the original request.

    • inside (boolean): A flag indicating whether the location is inside the geofence.

    • distance_m (number): The distance in meters from the location to the nearest point of the geofence.

  • geofence_id (string): The identifier of the geofence that was checked.

Description

This endpoint retrieves geofence proximity areas based on the specified location and parameters. It allows users to find nearby geofences within a defined distance.

Request Body Parameters

The request requires the following parameters in the JSON payload:

• p_location (Array of floats): An array containing latitude coordinates of the location for which proximity areas are to be retrieved.

• p_limit_count (integer): The maximum number of proximity areas to return.

• p_distance_tolerance_m (integer): The distance tolerance in meters to consider when searching for proximity areas.

• p_keywords (Array of strings): Optional, an array of keywords to filter the nearest geofence areas based on specific criteria.

Response

The response will be an array of objects, each representing a geofence proximity area. The structure of each object in the response includes:

• id (string): The unique identifier for the geofence.

• name (string): The name of the geofence.

• contains_point (boolean): Indicates whether the specified location is within the geofence.

• distance_to_border (integer): The distance in meters from the specified location to the nearest border of the geofence.

Description

This endpoint allows users to add a new asset to the system. An asset represents an entity that needs to be tracked. The asset details provided will help in tracking and managing the asset effectively.

Request Body Parameters

• p_id (string | optional): A unique identifier for the asset. If not provided, an unique ID will be generated in UUID format.

• p_name (string | optional): The name of the asset. This should provide a clear indication of what the asset is.

• p_description (string | optional): A detailed description of the asset. This can include information about the asset's purpose and features.

• p_properties (object | optional): A JSON object containing specific properties of the asset. By assigning properties to assets and monitors, users can conveniently track assets that share common properties, enabling collective monitoring of assets. For example, properties such as "department": "logistics" or "zone": "downtown" can be used to group assets and efficiently monitor their activities.

• p_state (string | optional): The current state of the asset (e.g., active - location changed in the last 7 days, inactive). If not specified, the default state is "inactive".

• p_type (string): The type of asset being added. This categorizes the asset within the system. Only "user" supported at the moment.

• p_user_id (integer): The user ID that will send location updates for this asset.

Response

Upon successfully adding the asset, the API will return a JSON response containing:

• id (string): The unique identifier assigned to the newly created asset.

• error (string): In case of an error during the asset creation process, this field will contain the error message.

Description

This endpoint retrieves asset details based on the provided asset IDs. It allows users to obtain information about specific assets in the system.

Request Body

The request body must be in JSON format and should include the following parameter:

• p_ids (Array of strings): A list of asset IDs for which details are requested. Each ID should be a string representing a unique asset.

Response

The response will return a JSON object containing an array of asset details. Each asset object includes the following fields:

• id (string): The unique identifier of the asset.

• name (string): The name of the asset.

• state (string): The current state of the asset: "active" - location was updated in the last 7 days, "inactive" - last tracked location is older than 7 days.

• created_at (integer): The unix timestamp of when the asset was created.

• properties (object): Additional properties related to the asset, used for monitoring.

• updated_at (integer): The unix timestamp of the last update to the asset.

• description (string): A description of the asset.

• gps_device_id (string): The ID of the GPS device associated with the asset.

• last_location (object): An object containing the last known location details, including:

  • speed (float): The speed of the asset.

  • bearing (float): The bearing of the asset.

  • accuracy (float): Accuracy of the location data.

  • altitude (float): Altitude of the asset.

  • timestamp (integer): Unix timestamp of the last location update.

  • coordinates (array): An array containing the GPS coordinates in the form of [longitude, latitude].

Description

This endpoint retrieves a list of assets based on specified properties and filters. It allows users to paginate through the results for better management of large datasets.

Request Body Parameters

The request requires a JSON payload with the following parameters:

• p_properties (object): A JSON object that defines the properties to filter the assets.

• p_filter (string): Specifies the filtering method. It can take values all_of or any_of to indicate how the properties should be combined.

• p_page_no (integer): The page number of the results to retrieve, starting from 1.

• p_entries_per_page (integer): The number of entries to return per page.

Response

The response will be a JSON object containing the following structure:

• assets (Array of objects): A list of asset objects, each containing:

  • id (string): The unique identifier of the asset.

  • name (string): The name of the asset.

  • state (string): The current state of the asset, "active" - last tracked location is newer than 7 days, "inactive" - last tracked location is older than 7 days.

  • created_at (integer): Unix timestamp of when the asset was created.

  • properties (object): A JSON object containing various properties of the asset that can be used for monitoring.

  • updated_at (integer): Unix timestamp of the last update to the asset.

  • description (string): A brief description of the asset.

  • gps_device_id (string): Identifier of the GPS device associated with the asset.

  • last_location (object): An object containing the last known location details, including:

    • speed (float): The speed of the asset.

    • bearing (float): The bearing of the asset.

    • accuracy (float): Accuracy of the location data.

    • altitude (float): Altitude of the asset.

    • timestamp (integer): Unix timestamp of the last location update.

    • coordinates (array): An array containing the GPS coordinates in the form of [longitude, latitude].

• page (object): Pagination information including:

  • page_no (integer): The current page number.

  • has_more (boolean): Indicates if there are more entries available.

  • total_pages (integer): Total number of pages available.

  • total_entries (integer): Total number of entries available.

  • offset_entries (integer): Number of entries offset from the start.

  • entries_per_page (integer): Number of entries per page.

Description

This endpoint allows the user to delete assets from the system based on their unique identifiers.

Request Body Parameters

• p_ids (Array of Strings): This parameter is required and should contain the IDs of the assets you wish to delete.

Response

The response will be in JSON format and will include an array of deleted asset IDs:

• deleted_ids (Array of strings): When the assets are successfully deleted, the response will contain the IDs of the deleted assets in JSON format.

Notes

• The deleted_ids array in the response will list the IDs of the assets that were successfully deleted. An empty array signifies that no assets matched the provided IDs for deletion.

Description

This endpoint allows users to update the details of an existing asset in the system. It is designed to modify the properties of an asset identified by its unique ID.

Request Body

The request body must be sent in JSON format and should include the following parameters:

• p_id (string): The unique identifier of the asset that you want to update.

• p_name (string | optional): The name of the asset.

• p_description (string | optional): A description of the asset, providing additional context or details.

• p_properties (object | optional): A JSON object containing updated properties of the asset that can be used for assigning monitors.

Response

The response will also be in JSON format and may include the following fields:

• id (string): The identifier of the updated asset, which may be returned to confirm the update.

• error (string): An error message if the update fails, providing insight into what went wrong.

Description

This endpoint retrieves the most recent tracked location data for a specified asset.

Request Body

The request body must be in JSON format and should include the following parameter:

• p_asset_id (string): The unique identifier of the asset for which the last location is being requested.

Response

Upon a successful request, the response will be in JSON format and will contain the following structure:

• last_location_data (object): An object containing the latest location details of the asset.

  • speed (number): The speed of the asset at the last recorded location (m/s).

  • bearing (number): The direction the asset is facing at the last recorded location.

  • accuracy (number): The accuracy of the location data.

  • altitude (number): The altitude (in meters) of the asset at the last recorded location.

  • timestamp (number): The unix timestamp at which the last location was recorded.

  • last_location (array): An array containing the coordinates of the last recorded location.

Description

This endpoint retrieves the historical location data of a specified asset within a defined time interval. It allows users to track the movements of an asset over time, providing insights into its location history.

Request Body Parameters

The request requires the following parameters in the JSON body:

• p_asset_id (string): The unique identifier of the asset for which the location history is being requested.

• p_start_time (integer): The start timestamp (unix, in seconds) for the time interval during which the asset's locations are to be retrieved.

• p_end_time (integer): The end timestamp (unix, in seconds) for the time interval during which the asset's locations are to be retrieved.

• p_page_no (integer): The page number for pagination of results.

• p_entries_per_page (integer): The number of entries to return per page.

Response

The response will be a JSON object containing the following structure:

• locations_history (array): An array of location objects, each containing:

  • speed (integer): The speed (in m/s) of the asset at the recorded timestamp.

  • bearing (integer): The direction of travel of the asset.

  • accuracy (integer): The accuracy of the location data.

  • altitude (integer): The altitude (in m) of the asset at the recorded timestamp.

  • location (array): An array containing the latitude and longitude of the asset.

  • timestamp (integer): The unix timestamp of the location record.

• page (object): An object containing pagination details:

  • total_entries (integer): The total number of entries available for the query.

  • offset_entries (integer): The number of entries skipped for the current page.

  • total_pages (integer): The total number of pages available.

  • page_no (integer): The current page number.

  • entries_per_page (integer): The number of entries per page.

  • has_more (boolean): Indicates whether there are more entries available beyond the current page.

Description

This endpoint allows users to search for assets within a specified circular area defined by a center point and a radius. The search results can be paginated for easier navigation. Only assets with location updates in the past 7 days are considered active and returned.

Request Body Parameters

The request body should be formatted as JSON and must include the following parameters:

• p_center_lon (number): The longitude of the center point of the search area.

• p_center_lat (number): The latitude of the center point of the search area.

• p_radius_m (number): The radius of the search area in meters.

• p_properties (object): A JSON object representing additional properties to filter the assets.

• p_filter (string): A string indicating the type of filter to apply ("all_of" or "any_of").

• p_page_no (number): The page number for pagination of results.

• p_entries_per_page (number): The number of entries to return per page.

Response

The response will be in JSON format and will contain the following structure:

• assets (array): A list of asset objects that match the search criteria. Each asset object includes:

  • id (string): Unique identifier for the asset.

  • name (string): Name of the asset.

  • state (string): Current state of the asset, "active" - last tracked location is newer than 7 days, "inactive" assets are excluded from the result.

  • created_at (number): Timestamp of when the asset was created.

  • properties (object): Contains additional properties of the asset.

  • updated_at (number): Unix timestamp of the last update to the asset.

  • description (string): Description of the asset.

  • gps_device_id (string): Identifier for the GPS device associated with the asset.

  • last_location (object): Contains details about the asset's last known location, including:

    • speed (number): Speed of the asset at the last known location.

    • bearing (number): Bearing of the asset at the last known location.

    • accuracy (number): Accuracy of the last known location.

    • altitude (number): Altitude (in m) of the asset at the last known location.

    • timestamp (number): Unix timestamp of the last known tracked location.

    • coordinates (array): Array containing the coordinates of the last known tracked location.

• page (object): Contains pagination information, including:

  • total_entries (number): Total number of entries matching the search criteria.

  • offset_entries (number): Number of entries offset from the start of the results.

  • total_pages (number): Total number of pages available.

  • page_no (number): Current page number.

  • entries_per_page (number): Number of entries per page.

  • has_more (boolean): Indicates if there are more entries available beyond the current page.