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 "X-Planado-API-Key:XXX" 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 "X-Planado-API-Key:XXX" 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 "X-Planado-API-Key:XXX" 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.