> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mileapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Create location history
> Location history has three types of payloads:
**General**: This payload is sent without any specific business process. All payloads sent will be saved and can be visualized.
**Start - Finish**: This payload tracks a user's movement, both during general online activity and while performing a specific task. The 'Finish' payload cannot be saved unless it is preceded by a 'Start' payload, and a new 'Start' payload cannot be saved until the previous one has been completed.
**Custom Data**: This payload is typically used by integrators. MileApp provides a 'data' key with an object data type. This key can store dynamic data according to user needs. For example, users can store data such as fuel levels, vehicle temperature, and more.
** Related Guide [ Introduction to Tracking ](/task/tracking/introduction-to-tracking)**
## OpenAPI
````yaml /openapi/public/openapi-task.json post /location-history
openapi: 3.0.0
info:
title: MileApp API - Task
version: 3.0.0
description: MileApp API Documentation - RESTful API for field operations management.
servers:
- url: https://apiweb.mile.app/api/v3
security:
- bearerAuth: []
tags:
- name: Task
description: >-
A task is an item of work intended for completion by an assignee. It can
embody activities like pickups, deliveries, planning, inspections, sales
visits, or other work-related actions within your organization. Tasks
encompass essential attributes, including IDs, flow, time, status
indicators, assignee information, order index, and other pertinent data.
The content of a task is configurable based on your specified flow
settings. For instance, tasks can serve as visits during the route
optimization process, functioning as pivotal elements. The task can also
represent a visit in route optimization, please follow [this
link](#tag/Routing) to read more detail.
**To see the details of task object, please follow [this
link](#tag/task_model)**
- name: Location History
description: >-
Location history is data that stores the user's location points that are
sent periodically from the MileApp mobile application if the user
activates the tracking feature. However, this endpoint can also be useful
for integration into the user's IoT devices such as GPS or other mobile
trackers. All location data sent can be visualized in MileApp in real time
and makes it easier for users to monitor field activities more accurately.
**Related Guide:** [Start Finish
Feature](/configuration/start-trip-end-trip-feature)
- name: Task Schedule
description: >-
Task Schedule is a mechanism to generate tasks according to the schedule
that is set by you. The task schedule attributes consist of IDs,
repetition period data (daily, weekly, etc.), flow structure, task
content, and time of the schedule's start & end. This schedule could help
you to set a task that will be repeated at a certain period.
**To see the details of task schedule object, please follow [this
link](#tag/task_schedule_model)**
- name: Activity
description: >-
An Activity is a multi-step task group created from a Workflow template.
When you create an Activity, MileApp automatically creates one parent task
(with `taskType = activityMaster`) plus one child task (with `taskType =
activityChild`) per Workflow step, and copies field values forward between
steps according to the Workflow's field mappings. Activities are stored
alongside regular tasks — the parent's `_id` is also the Activity ID, and
its `subId` array lists every child task in Workflow-step order.
After creation, retrieve, update, or delete an Activity through the
standard Task endpoints using the Activity master task's ID.
**To see the details of Activity object, please follow [this
link](#tag/activity_model)**
paths:
/location-history:
post:
tags:
- Location History
summary: Create location history
description: >-
Location history has three types of payloads:
**General**: This payload is sent without any specific business process.
All payloads sent will be saved and can be visualized.
**Start - Finish**: This payload tracks a user's movement, both during
general online activity and while performing a specific task. The
'Finish' payload cannot be saved unless it is preceded by a 'Start'
payload, and a new 'Start' payload cannot be saved until the previous
one has been completed.
**Custom Data**: This payload is typically used by integrators. MileApp
provides a 'data' key with an object data type. This key can store
dynamic data according to user needs. For example, users can store data
such as fuel levels, vehicle temperature, and more.
** Related Guide [ Introduction to Tracking ](/task/tracking/introduction-to-tracking)**
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/baseBodyLocationHistory'
required: true
x-examples:
application/json:
generalRequest:
summary: General Request
value:
email: example@mile.app
taskId: 634e98098ce69d29474a7e11
speed: 40
distance: 50
duration: 50
lat: '-6.1771046'
lon: '106.9240199'
createdTime: '2022-10-07 03:00:58'
notes: Example notes
StartRequest:
summary: Start Request
value:
email: example@mile.app
taskId: 634e98098ce69d29474a7e11
speed: 40
distance: 50
duration: 50
lat: '-6.1771046'
lon: '106.9240199'
createdTime: '2022-10-07 03:00:58'
startTime: '2022-10-07 03:00:58'
notes: Example notes
finishRequest:
summary: Finish Request
value:
email: example@mile.app
taskId: 634e98098ce69d29474a7e11
speed: 40
distance: 50
duration: 50
lat: '-6.1771046'
lon: '106.9240199'
createdTime: '2022-10-07 03:00:58'
finishTime: '2022-10-07 03:10:58'
notes: Example notes
customDataReqest:
summary: Custom Data Request
value:
email: example@mile.app
taskId: 634e98098ce69d29474a7e11
speed: 40
distance: 50
duration: 50
lat: '-6.1771046'
lon: '106.9240199'
createdTime: '2022-10-07 03:00:58'
notes: Example notes
createdFrom: GPS
data:
temperature: 31
anotherKey: anotherValue
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
examples:
response:
value:
status: true
message: Success
location_history:
email: example@mile.app
taskId: 634e98098ce69d29474a7e11
speed: 40
distance: 50
duration: 50
lat: -6.1771046
lon: 106.9240199
_id: 634e98098ce07d29474a7e22_example@mile.app_1675224349343
time: 1675224349343
organizationId: 634e98098ce07d29474a7e22
createdTime: '2022-10-07 03:00:58'
updatedTime: '2022-10-07 04:00:58'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
status:
type: boolean
description: Shows if the request was successful.
message:
type: string
description: A short message explaining what went wrong.
example:
status: false
message: Bad request - invalid parameters provided.
'500':
description: Server error
content:
application/json:
schema:
type: object
properties:
status:
type: boolean
description: Shows if the request was successful.
message:
type: string
description: A short message explaining what went wrong.
example:
status: false
message: Internal server error, please contact support@mile.app.
deprecated: false
security:
- bearerAuth: []
components:
schemas:
baseBodyLocationHistory:
x-discriminator: baseLocationHistory
type: object
properties:
email:
type: string
description: >-
Required, User's email assigned to the monitored task. **Example:**
`example@mile.app`
lat:
type: string
description: >-
Required, Latitude coordinate position or location of any place on
Earth's surface. **Example:** `-6.1771046`
lon:
type: string
description: >-
Required, Longitude coordinate position or location of any place on
Earth's surface. **Example:** `106.9240199`
ApiResponse:
type: object
properties:
status:
type: boolean
description: Indicates whether the request was successful.
code:
type: integer
description: HTTP status code.
message:
type: string
description: A message providing additional information about the response.
location_history:
$ref: '#/components/schemas/LocationHistoryResponse'
LocationHistoryResponse:
type: object
properties:
email:
type: string
description: User's email assigned to the monitored task.
lat:
type: number
description: Latitude coordinate position.
lon:
type: number
description: Longitude coordinate position.
speed:
type: integer
description: Vehicle speed in kilometers per hour.
distance:
type: integer
description: Distance traveled from the previous location.
distanceToDest:
type: number
description: Distance estimated from the next location.
duration:
type: integer
description: Time duration spent at this location in milliseconds.
createdTime:
type: string
description: Time at which the location history was created.
_id:
type: string
description: Unique identifier for the location history entry.
taskId:
type: string
description: Unique ID to identify the task.
time:
type: integer
description: A timestamp indicating the time of the location history entry.
organizationId:
type: string
description: Unique identifier for the organization.
eventName:
type: string
description: A flagging of location history with value otw, nearBy and done.
isLatest:
type: boolean
description: Identifier for flagging the latest location history
createdFrom:
type: string
description: >-
A flagging for describe location history created from, default value
generated by system is `mileAppField`.
**Example:**
`GPS`.
**Default:** `mileAppField`
updatedBy:
type: string
description: Email of the user who last updated the location history entry.
createdBy:
type: string
description: Email of the user who created the location history entry.
updatedTime:
type: string
description: Time at which the location history entry was last updated.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Use a valid Bearer token to authenticate.
````