Listing job-linked locations

When a job is in progress, the mobile app captures current location and links it to the job. Locations are uploaded in background to the server and are shown on the map (see how locations are captured).

Job locations can be retrieved via API in batches of 100. Records are listed in the order they were uploaded.

Example of a request accessing job locations:

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/jobs/f93f9291-7823-4092-b5db-ed5eb26d4e75/locations | jq
{
  "locations": [
    {
      "uuid": "a43ae74c-5b10-4551-9ca5-ad0d8393f8a3",
      "user_uuid": "c063588e-f56a-4105-b4ab-2a13fa8f8f10",
      "accuracy_m": 15.34,
      "longitude": -0.1422422,
      "latitude": 51.5009815,
      "uploaded_at": "2020-06-01T07:17:28.843+00:00",
      "catured_at": "2020-06-01T07:14:39.225+00:00",
      "events": [
        {
          "uuid": "176330b7-6c5d-4982-b1a0-e5ba1a4e79a8",
          "type": "status_updated",
          "job_uuid": "f93f9291-7823-4092-b5db-ed5eb26d4e75",
          "job_version": 7
        }, {
          "uuid": "bb8ef91f-d653-4c80-a4f9-eb4eb24c840e",
          "type": "field_updated",
          "job_uuid": "6aa41838-2489-4fd0-bbce-6e832c708397",
          "job_version": 14
        }
      ]
    },
    ... // up to 99 more locations
  ]
}

Table 1. Fields of `locations` elements
Field	Type	JSON type	Can be `null`	Description
`uuid`	UUID	String	No	Unique location identifier
`user_uuid`	UUID	String	No	User identifier
`longitude`	Float	Float	No	Longitude
`latitude`	Float	Float	No	Latitude
`accuracy_m`	Float	Float	No	Location accuracy, meters
`uploaded_at`	Datetime	String	No	Time when data was uploaded to the server
`captured_at`	Datetime	String	No	Time when location was captured
`events`	Events	Array	No	List of linked job events. Can be empty, cannot be `null`

Table 2. Fields of `events` elements
Field	Type	JSON type	Can be `null`	Description
`uuid`	UUID	String	No	Event uuid
`type`	String	String	No	Event type
`job_uuid`	UUID	String	No	Job identifier
`job_version`	UUID	String	No	Job version associated with the event

Listing next locations

Listing next locations uploaded after one with id 72ae2d43-d3ac-4b5d-b3f8-bc6a4421a502:

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/jobs/f93f9291-7823-4092-b5db-ed5eb26d4e75/locations?after=72ae2d43-d3ac-4b5d-b3f8-bc6a4421a502 | jq
{
  "locations": [
    ...
  ]
}

Filtering locations by event uuids

This request filters job locations linked to particular events, such as status changes (see history API).

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/jobs/f93f9291-7823-4092-b5db-ed5eb26d4e75/locations?events[0][uuid]=7b18a228-1fed-4f6b-96e7-29d0de3e1af5&events[1][uuid]=2ac9fd45-1b46-443c-ab64-b6803eaa37bd | jq
{
  "locations": [
    ...
  ]
}

How locations are captured

Due to technical reasons, location information cannot be captured instantly and perfectly precise. The mobile application uses the following logic for capturing current device location:

There’s a job in progress (either en route or started).
When device is moving, location is captured more aggressively.
When device is stationary, no location is captured. Thus, there can be significant delays between points, this is expected.
When job status changes, location is forcibly requested.
Events are linked to location using best-effort mechanism. If the lag between an event and location info is less than a few minutes, they are linked. Thus, it is possible and expected that one location can be linked to several jobs.

Location data is not reliable for the following reasons:

Usually, there’s a delay between location request made by the mobile app and response returned by the operating system.
Location accuracy may vary greatly. Resulting accuracy is always a combination of many factors.
User can disable tracking at any time.
Some devices can’t be relied upon or require significant efforts to configure them properly (see https://dontkillmyapp.com/).
Operating system may switch to low power mode when battery level drops below a certain level.