Placeline

The HyperTrack mobile SDK collects location, activity and device health data for your users. This data is sent to the server where noise is filtered, and the placeline is formed by performing a JOIN operation on this data.

Placeline object

It is a list of activity segments, where each segment is defined by a start and an end timestamp, and has relevant location and health data as properties. The Placeline object includes segments like stop, walk, and drive. An example JSON representation is given below.

[
    {
        "time_aware_polyline": "aiseFr_ajVcs{ykxAAA????fA{A????LO????l@t@????r@bA????PT????HL????r@`A????`CcDA",
        "distance": 310.47333797811655,
        "user_id": "4e2a8344-9864-4473-864f-e223dec208b3",
        "type": "trip",
        "encoded_polyline": "aiseFr_ajVAA??fA{A??LO??l@t@??r@bA??PT??HL??r@`A??`CcD",
        "activity": "Walk",
        "duration": 95738.982,
        "ended_at": "2017-07-14T02:41:01.739000+00:00",
        "started_at": "2017-07-13T00:05:22.757000+00:00",
        "trip_id": "5c7a0e2e-35ce-4482-baa3-34f837146071",
        "id": "5c7a0e2e-35ce-4482-baa3-34f837146071_1499904322"
    },
    {
        "id": "885cb75c-c642-4df2-9d0e-8b9bf0d9547b",
        "user_id": "4e2a8344-9864-4473-864f-e223dec208b3",
        "place": {
            "id": "83f46d89-cacd-4a1a-9007-507dbd5a4d7c",
            "name": "",
            "location": {
                "type": "Point",
                "coordinates": [-122.3985203814826,
                    37.7869638230917
                ]
            },
            "address": "182 2nd St, San Francisco, CA 94105, USA",
            "locality": "South Beach",
            "landmark": "",
            "zip_code": "94105",
            "city": "SF",
            "state": "CA",
            "country": "US"
        },
        "started_at": "2017-07-14T02:41:02.046000Z",
        "ended_at": null,
        "duration": 3211.898782,
        "lookup_id": "D2E0C7FD-D1D3-4C1E-9307-82AD6F70BC9D",
        "step_count": 301,
        "step_distance": 210,
        "created_at": "2017-07-14T02:41:02.409459Z",
        "modified_at": "2017-07-14T02:41:02.409487Z",
        "type": "stop"
    }
]

User's placeline API

The User HTTP entity can be used to get the location and activity history of a user. This API returns a User object with the segment property containing the placeline segments.

API call HTTP method Request url
Get user Placeline https://api.hypertrack.com/api/v1/users/USER_ID/placeline/
curl "https://api.hypertrack.com/api/v1/users/41caa9f2-ad63-4a8b-98ed-1414c372e1ce/placeline/?date=2017-01-01"
  -H "Authorization: token YOUR_SECRET_KEY"

Parameters

You can pass the following parameters as arguments in the URL. If you don't pass any parameters, by default the API will return the placeline for the current ongoing day as per your account's timezone. You can pass one of the 3 types of paramters:

Date parameter

Parameter Type Description
date ISO date string Get placeline for the given calendar date as per your account's timezone

Datetime parameters

You can pass either or both of these paramters, if you want the placeline between two timestamps.

Parameter Type Description
min_recorded_at ISO datetime string Get placeline for the user starting with this timestamp. If you pass max_recorded_at without this parameter, default of this parameter is the time when user was created
max_recorded_at ISO datetime string Get placeline for the user ending with this timestamp. If you pass min_recorded_at without this parameter, default of this parameter is the current time

Action parameters

If you want a user's placeline for multiple actions, use these params. You can pass either one of the below parameters. Ensure that the actions corresponding to the parameters you pass, are assigned to the user whose placeline you are querying. Otherwise, an error will be raised.

Parameter Type Description
action_id UUID String Get placeline for the action that has this id. For multiple actions, use a comma separated list of ids
action_lookup_id String Get placeline for the action that has this lookup_id. For multiple actions, use a comma separated list of lookup ids
action_collection_id String Get placeline for the actions that have this collection_id. Only one collection id can be passed as param

Action's placeline API

The Action HTTP entity can be used to represent Placelines that are useful for your workflow. For example, a sales visit can be an action, and for this action, you can obtain the user's Placeline. This API returns a paginated list of Action objects with each object's segment property containing the placeline segments.

API call HTTP method Request url
Get action Placeline https://api.hypertrack.com/api/v1/actions/placeline/
curl "https://api.hypertrack.com/api/v1/actions/placeline/?id=41caa9f2-ad63-4a8b-98ed-1414c372e1ce,4e2a8344-9864-4473-864f-e223dec208b3"
  -H "Authorization: token YOUR_SECRET_KEY"

Filter parameters

You can pass any of the action filter parameters as arguments in the URL. If you don't pass any parameters, all actions each with their placeline will be returned. The following are the most useful parameters for this API.

Parameter Type Required Description
id UUID String No Get placeline for the action that have this id. For multiple actions, use a comma separated list of ids
lookup_id String No Get placeline for the action that has this lookup_id. For multiple actions, use a comma separated list of lookup ids
collection_id String No Get placeline for the actions that have this collection_id. Only one collection id can be passed as param

Get placeline as a visual

You can see a user's placeline as a chronological timeline and on a map with the entire history of the user's location shown as polylines. You can see this in 3 different ways:

  • on the HyperTrack dashboard
  • on your own dashboard, with some customisation options, by embedding this view using widgets
  • on your own dashboard, with full customisation capability, by using JS library

Next up

Read about other building blocks, or learn what you can build with them.

results matching ""

    No results matching ""