REST API for Oracle Fusion Field Service Cloud Service

Get airline distance based travel

get

/rest/ofscStatistics/v1/airlineDistanceBasedTravel

This operation retrieves a collection of statistically estimated and override values of airline distance based travel time (in minutes) at the company as well as the travel key level for the specified distances (in km). Up to five distances can be specified in the request. If no distances are specified, the operation retrieves data for 1 km, 5 kms, 10 kms, 20 kms and 50 kms. The level at which the data needs to be retrieved - either company or travel key - can also be specified in the request. If the level is set as travel key and no travel key is specified, the operation retrieves data for all possible travel keys. The maximum number of records that can be retrieved in a single response is 10000. If there are more than 10000 records, you can use the 'next' link available at the bottom of the response to access the remaining records.

Before you use this operation, ensure that:

You have a subscription to Oracle Field Service Professional or Enterprise Cloud Service.
The application has the permission to access the Statistics API. To grant the permission, navigate to Configuration > Applications screen. For the required application, in the API access section, click Add new and select Statistics API.

Request

Query Parameters

distance: string

Allow Empty value: true

Pattern: ^$|^(\d+(,\d+)*)$

The list of comma separated distances (in km) for which the statistically estimated and override travel time at the travel key level has to be retrieved. Maximum number of distances allowed is 5. If no distance is specified, the application retrieves values for the distances 1, 5, 10, 20, 50.
key: string
Allow Empty value: true

Maximum Length: 50
The value of the travel key. It appears as 'Start Location' and 'End Location' in the Travel Statistics report.
If 'key' is provided in request and :
- If 'key' is present in the application, the application estimated and override values for travel time of the travel key is retrieved.
- If 'key' is not present in the application, HTTP Code 404 response is displayed.
If 'key' is not provided in request, the application estimated and override values for travel time of all the travel keys are retrieved. If none of the travel keys have application estimated or override values, then HTTP Code 404 response is displayed.
This parameter is not applicable if the level is specified as 'company'.
keyId: integer
Minimum Value: 1
Key ID of one of the configured travel keys.
- If the parameter 'keyId' is not specified, data for all travel keys will be retrieved.
- If 'keyId' is specified and if it exists in the system, data will be retrieved for the travel keys of the corresponding Key ID.
- If 'keyId' is specified but if it does not exist in the system, an error message will be returned
If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this parameter will be ignored.
This parameter is not applicable if the level is specified as 'company'.
level: string

Allow Empty value: true

Specifies where the data needs to be retrieved at the company level or travel key level. For company level use 'company' and for travel key level use 'travelkey' as the value for this parameter.
If no value is provided, data for both company as well as travel key level will be retrieved.

Allowed Values: [ "company", "travelkey" ]
limit: integer

Minimum Value: 1

Maximum Value: 10000

The number of records to be returned in the response.
offset: integer

Minimum Value: 0

The record number from which the retrieval starts. The default value is zero. If no value is specified, then it defaults to zero. The value zero indicates that the retrieval will start from the beginning of the collection.

Response

Supported Media Types

application/schema+json
application/json

200 Response

This section describes the 200 status response for this operation. The response contains the collection of application estimated and override values for travel time for the specified list of distances. If 'key' is not specified as a parameter, the application returns company level record and the records for all the travel keys that have either application estimated or override values or both for travel time.

Root Schema : airlineDistanceBasedTravelList

Type: object

The array of items containing the statistically estimated and override travel time at travel key level for the specified distances.

Show Source

items: array items

{
    "description":"The array of items containing the statistically estimated and override travel time at travel key level for the specified distances.",
    "properties":{
        "items":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/airlineDistanceBasedTravel"
            }
        }
    }
}

Nested Schema : items

Type: array

Show Source

Array of: object Travel Key Level estimated and override Travel Time Response

Title: Travel Key Level estimated and override Travel Time Response

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/airlineDistanceBasedTravel"
    }
}

Nested Schema : Travel Key Level estimated and override Travel Time Response

Type: object

Title: Travel Key Level estimated and override Travel Time Response

Show Source

data: array Travel Key level estimated and override values of travel time (in minutes).

Title: Travel Key level estimated and override values of travel time (in minutes).
key: string

Title: Travel Key

The value of the travel key. It appears as 'Start Location' and 'End Location' in the Travel Statistics report.
keyId: integer

Title: Key ID

Key ID of one of the configured travel keys.
If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.

Example: 100
level: string

Title: Level

Allowed Values: [ "company", "travelkey" ]

Specifies whether the data needs to be retrieved at the company level or travel key level.

Example: travelkey
org: array List of Organizations

Title: List of Organizations

An array of all the Organizations(labels) for which the key is applicable.
If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.

{
    "type":"object",
    "title":"Travel Key Level estimated and override Travel Time Response",
    "properties":{
        "level":{
            "type":"string",
            "title":"Level",
            "enum":[
                "company",
                "travelkey"
            ],
            "example":"travelkey",
            "description":"Specifies whether the data needs to be retrieved at the company level or travel key level."
        },
        "key":{
            "type":"string",
            "title":"Travel Key",
            "description":"The value of the travel key. It appears as 'Start Location' and 'End Location' in the Travel Statistics report."
        },
        "data":{
            "type":"array",
            "title":"Travel Key level estimated and override values of travel time (in minutes).",
            "items":{
                "$ref":"#/definitions/airlineDistanceBasedTravelDataResponse"
            }
        },
        "keyId":{
            "type":"integer",
            "title":"Key ID",
            "example":100,
            "description":"<p>Key ID of one of the configured travel keys.</p><p>If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.</p>"
        },
        "org":{
            "type":"array",
            "title":"List of Organizations",
            "description":"<p>An array of all the Organizations(labels) for which the key is applicable.</p><p>If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.</p>",
            "items":{
                "type":"string",
                "title":"Organization label"
            }
        }
    }
}

Nested Schema : Travel Key level estimated and override values of travel time (in minutes).

Type: array

Title: Travel Key level estimated and override values of travel time (in minutes).

Show Source

Array of: object Travel Key level estimated and override travel time (in minutes) for the list of specified distances.

Title: Travel Key level estimated and override travel time (in minutes) for the list of specified distances.

{
    "type":"array",
    "title":"Travel Key level estimated and override values of travel time (in minutes).",
    "items":{
        "$ref":"#/definitions/airlineDistanceBasedTravelDataResponse"
    }
}

Nested Schema : List of Organizations

Type: array

Title: List of Organizations

An array of all the Organizations(labels) for which the key is applicable.

If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.

Show Source

Array of: string

Title: Organization label

{
    "type":"array",
    "title":"List of Organizations",
    "description":"<p>An array of all the Organizations(labels) for which the key is applicable.</p><p>If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.</p>",
    "items":{
        "type":"string",
        "title":"Organization label"
    }
}

Nested Schema : Travel Key level estimated and override travel time (in minutes) for the list of specified distances.

Type: object

Title: Travel Key level estimated and override travel time (in minutes) for the list of specified distances.

Show Source

distance: integer

Title: Distance

Maximum Value: 999

The distance (in km) for which the override value of travel time is specified at travel key level.

Example: 15
estimated: integer

Title: Statistically estimated Travel Time

The statistically estimated value for the travel time (in minutes) for the distance at travel key level.

Example: 25
override: integer

Title: Override Travel Time

The override value for the travel time (in minutes) for the distance at travel key level.
If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.

Example: 28

{
    "type":"object",
    "title":"Travel Key level estimated and override travel time (in minutes) for the list of specified distances.",
    "properties":{
        "distance":{
            "type":"integer",
            "title":"Distance",
            "example":15,
            "maximum":999,
            "description":"The distance (in km) for which the override value of travel time is specified at travel key level."
        },
        "estimated":{
            "type":"integer",
            "title":"Statistically estimated Travel Time ",
            "example":25,
            "description":"The statistically estimated value for the travel time (in minutes) for the distance at travel key level."
        },
        "override":{
            "type":"integer",
            "title":"Override Travel Time",
            "example":28,
            "description":"<p>The override value for the travel time (in minutes) for the distance at travel key level.</p><p>If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this field will not be returned as part of the response.</p>"
        }
    }
}

Default Response

This section describes the default error response for this operation.

Root Schema : Error

Type: object

Show Source

detail: string

The detailed description of this error.
status: string

The HTTP status code of this error.
title(required): string

The brief description of this error.
type(required): string

The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Examples

The following example shows how to get airline distance based travel by submitting a GET request on the REST resource using cURL:

cURL command Example

curl 'clientId@instance:clientSecret' \
-X GET \
https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscStatistics/v1/airlineDistanceBasedTravel \
  -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' \
  -H 'content-type: application/json' \

Response Header Example

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Mon, Wed, 31 May 2021 11:53:49 GMT
Content-Type: application/json; charset=utf-8

Response Body Example

{
    "totalResults": "1",
    "limit": 10000,
    "offset": 0,
    "items": [
        {
            "key": "32771",
            "keyId": 2,
            "org" : ["Org1", "Org3"],
            "data": [
                {
                    "distance": 1,
                    "estimated": 11,
                    "override": 7
                },
                {
                    "distance": 5,
                    "estimated": 15,
                    "override": 15
                },
                {
                    "distance": 10,
                    "estimated": 20,
                    "override": 25
                },
                {
                    "distance": 20,
                    "estimated": 30,
                    "override": 45
                },
                {
                    "distance": 50,
                    "estimated": 60,
                    "override": 105
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscStatistics/v1/airlineDistanceBasedTravel?key=32771"
        },
        {
            "rel": "describedby",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscStatistics/v1/airlineDistanceBasedTravel"
        }
    ]
}