Introduction

HyperTrack provides the Places API to help you manage your places of interest. These are specific locations your workers visit to perform their shift activities. You can define all your places using this API. For each place, specify whether visits need to be recorded or if the location simply provides contextual information for shifts. Places can be designated either as point locations with a defined radius or as custom shapes (polygons). Additionally, you can specify parking locations, check-in and check-out points, and the timings for each place to enhance your workers' experience during their shifts.

Places created on HyperTrack and used in your Orders or Visits enable us to offer intelligent insights and continually improve the accuracy of place boundaries based on actual on-ground activities. This enhances entry/exit detection and optimizes routing over time.

Follow these quick steps to start creating and managing your places effectively.

1. Create your first place

Create a place with known coordinates

Let's consider one place for this example where we'd like to define a geofence boundary and detect the visits when a worker is assigned a shift to that location.

POST https://v3.api.hypertrack.com/places/v1/

// Body
{
  "place_handle": "safeway_2441122", // Your unique identifier for a place
  "geometry": {
    "type": "Point",
    "coordinates": [-122.311965,47.718096]
  },
  "radius": 200,
  "address": "Safeway, 12318, 15th Avenue Northeast, Northgate, Seattle, King County, Washington, 98125, United States",
  "metadata": {
    "customerId": 2441122,
    "zoneId": 1,
    "vendor_name": "Safeway"
    
  },
  "detect_visits": True
}

The above API call will help you get started with your first place. There are more properties that can be defined for a place to provide parking locations, check-in/check-out locations and so on here.

Create a place with an address

In case if geofence coordinates are not known, you can create a new Place with an address only as shown in the example below:

POST https://v3.api.hypertrack.com/places/v1/

// Body
{
  "place_handle": "safeway_2441122", // Your unique identifier for a place
  "address": "Safeway, 12318, 15th Avenue Northeast, Northgate, Seattle, King County, Washington, 98125, United States",
  "metadata": {
    "customerId": 2441122,
    "zoneId": 1,
    "vendor_name": "Safeway"
  },
  "detect_visits": True
}

This API will result in creation of the place as shown below:

{
  "address": "Safeway, 12318, 15th Avenue Northeast, Northgate, Seattle, King County, Washington, 98125, United States",
  "checkins": [],
  "completions": [],
  "detect_visits": false,
  "geometry": {
    "coordinates": [
      [
        [
          -122.3124927,
          47.7176968
        ],
        [
          -122.3124927,
          47.7183276
        ],
        [
          -122.3114428,
          47.7183276
        ],
        [
          -122.3114428,
          47.7176968
        ],
        [
          -122.3124927,
          47.7176968
        ]
      ]
    ],
    "type": "Polygon"
  },
  "inferred_geofences": [],
  "last_updated": "2024-06-19 20:31:09.320699",
  "metadata": {
    "customerId": 2441122,
    "zoneId": 1,
    "vendor_name": "Safeway"
  },
  "parkings": [],
  "place_handle": "safeway_2441122",
  "place_id": "2c988552-c57e-4e16-a297-feeed9d4ce55",
  "service_areas": [],
  "timings": []
}

2. Retrieve your places

Now that we created our first place, let's retrieve it.

GET https://v3.api.hypertrack.com/places/v1/

// Response
{
  "places":[{
    "place_handle": "Safeway - 77656", //Your unique identifer for a place
    "geometry": {
      "type": "Point",
      "coordinates": [-122.311965,47.718096]
    },
    "radius": 200,
    "address": "Safeway, 12318, 15th Avenue Northeast, Northgate, Seattle, King County, Washington, 98125, United States",
    "metadata": {
      "customerId": 77656,
      "vendor_name": "Safeway"

    },
    "detect_visits": True
  }]
}

You additionally always have an option to update any information provided to your place using the Place Update API.

3. Places Intelligence

Now that we have a place, let's take a look at what this would look like when used with the Orders API. As mentioned earlier, we provide intelligent insights and suggestions to improve the place boundaries. You can view this suggestion in your Places UI as shown below.

In the image above, you see an example of how inferences from the actual work area provides a clear recommendation of a better place boundary. In this example, based on 10 visits, HyperTrack detected a much more precise colored geofence area for the place instead of a larger gray circle that is defined as an orders' destination geofence.

We continue to improve our places experience. Please reach out to us for more information.