Tracking Quality & Analytics

7 min

This documentation provides information on how to use Insights APIs. This is a REST API documentation and contains most technical information required for using Insights APIs. For more clarification and feedback on API, please contact your Customer success manager.

If a parent company extracts data from the Tracking Quality API, it will also get the data of its child companies. Note that the child companies will not be able to get the parents' data or other child’s data.

Note: Shared loads are now not included in Insights API.

Rate Limit

Fourkites Insights APIs have rate limits that cap the number of responses that can be provided. If you exceed the specified rate limit, your request will be throttled and you will receive HTTP 429 Too Many Requests responses from the API. The rate limits will be applied across all Insights users within the company. Please get in touch with your Customer Success Manager to understand more about rate limits. We will soon provide a usage measurement portal to easily understand your API usage pattern.

For the current version, the limit is 1 API request per 5 seconds. Each API request would provide load details of upto 200 loads. The overall throughput for the response translates to 4 loads per second. Please note that this limit includes requests from all users within a company.

Pagination

Pagination lets you list multiple objects from the API by using more than one request. For the loads endpoint, we mention the total number of loads for the given load termination date in the metadata response. The API can provide details of upto 200 loads for a single API request. You could use the offset and l imit parameters in the API request to indicate the set of loads that are needed.

Performance

The average response time for the API is around 2 seconds. There could be multiple reasons that might affect the performance including concurrent users, load volume and network issues. The timeout for the response is advised to be set at 30 seconds.

Authenticated Resource

Insights API endpoints are protected by the same restrictions that are provided via Fourkites standard web interface. This means that if you log in and do not have permission to view something in Fourkites Insights web interface, you will not be able to view it using this REST API either.

In most cases, the first step in using the Insights API is to authenticate your credentials. If you need, you can construct and send Basic auth headers yourself.

Perform the following steps:

Build a string of the form username:password

Base64 Encode the above string.

Supply an “Authorization” header with content “Basic” followed by the encoded string. For example, the string “[email protected]:password” (email:password) encodes to “ZnJlZEBmb3Vya2l0ZXMuY29tOnBhc3N3b3Jk” in base64, so you would make the request as follows:

Sample Authentication Header

HeaderAuthorization: Basic ZnJlZEBmb3Vya2l0ZXMuY29tOnBhc3N3b3Jk

HTTPS Support

The REST API supports Basic Authentication, and all requests require a base64-encoded username and password included in the Authorization header. Since the transactions are confidential, we support only HTTPS and not HTTP.

Version Control

Each Fourkites Insights API is versioned with a version string specified in the base URL that can be incremented independently from other APIs. Using the newest available API is always encouraged.

Version Example: api/v1/consistency

The following items are backwards compatible and will not require the version string to be incremented:

Adding properties to JSON objects.

Changing the number of items returned in a single listing request.

Changing rate limiting thresholds.

The structure or length of identifiers generated by the API.

Changing error or status code messages.

The following items are considered backwards incompatible and will require the version string to be incremented:

Removing properties from JSON objects.

Changing an API's URL structure

In the event that certain functionality or a data property is deprecated, we will ensure that you are notified at least 90 days notice.

Tracking Quality & Analytics

GET

https://insights-api.fourkites.com/api/v1/consistency?terminated_date=2024-02-24&offset=1&limit=10

curl --location --request GET 'https://insights-api.fourkites.com/api/v1/consistency?terminated_date=2024-02-24&offset=1&limit=10' \
--header 'Authorization: Basic cmFqa2lyYW4ubWFub2hhcmFuQGZvdXJraXRlcy5jb206UmFqa2lyYW5tMg=='

Response Format

Name	Description	Format / Data Type	Max. Length	Mandatory?
load_number	Load number	String	255	Yes
load_mode	Load mode (Most recent if multiple provided)	String	30	Yes
carrier_name	Managing carrier name	String	255	Yes
carrier_scac	Managing carrier SCAC	String	50	Yes
shipper_name	Shipper Name	String	255	Yes
tpl_name	3PL Name	String	255
created_at_utc	Load creation date and time in UTC	Time		Yes
tags	Array of tags associated with the load	Array of string	2048
delayed_by_mins	Time difference between load arrival time and appointment time at the last stop	Integer		Yes
status	Load status: Delivered / Expired	String	50	Yes
is_tracked	Integer representing if the load was tracked	Integer	50
delivered_at_utc	Delivery time of the load	Time		Yes
exclude_from_reporting	Boolean representing if the load should be excluded from reporting and insights dashboards	Boolean
stops	Structured data for each stop associated with the load	Struct
truck_number	Refers to the Truck Number	String	50
trailer_number	Refers to the Trailer Number	String	50
load_timezone	Timezone for the load	String
load_timezone_offset	Timezone offset from UTC in seconds	Integer
Stops
stop_type	Stop type: Pickup / Delivery	String	10	Yes
name	Stop name	String	100	Yes
customer_name	Customer associated with the stop	String	50
address	Street address of the stop	String	500	Yes
city	City	String	100	Yes
state	State	String	100	Yes
country	Country	String	5	Yes
postal	Postal / ZIp code	String	20	Yes
lat	Latitude	String		Yes
lng	Longitude	String		Yes
loading_type	Loading type: Drop/Hook or Live	String
want_time_utc	Want time associated with the stop; Not applicable for pickup stops	Time
actual_arrival_utc	Actual arrival time of the load into the stop in UTC	Time
actual_departure_u tc	Actual departure time of the load from the stop in UTC	Time
dwell_mins	Dwell time of the load in the stop in minutes	Integer
appointment_time_ utc	Planned appointment time of the stop in UTC	Time		Yes
stop_timezone	Timezone for the stop	String
stop_timezone_offset	Timezone offset from UTC in seconds	Integer
auto_completed	Boolean indicating if Fourkites determined stop completion based on its internal logic	Boolean
sequence	Sequence of the stop for the load	Integer		Yes
reschedule_count	Count of no. of times the appointment time for the stop is revised	Integer
ship_to	Any 'Ship To' value you would like to associate with all delivery stop	String	50
reference_number	Reference numbers associated with the load	Comma separated values	255
po_numbers	PO numbers associated with the stop
arrival_status	Late, Early, Ontime etc.,	String	20	Yes
shipper_part_numbers	Comma-separated array of Shipper part numbers	String	2500
customer_part_number	Comma-separated array of Customer part numbers	String	2500
pallets_quantity	Comma-separated array of pallet quantities	String	2500
pallets_weight	Comma-separated array of pallet weights	String	2500
late_reason_code	Primary reason code associated with the stop.- Reason code with maximum weightage	String
late_reason_code_time_impact_mins	The delay time impact of the reason code in minutes	Integer
recommended_departure_time	Fourkites recommended departure time from the stop, so that the shipment could be delivered at the destination on-time	Time
last_updated_at	Data last refreshed at			Yes

Request Format

403	Forbidden	When the authentication succeeded but authenticated user doesn't have permission to the request resource
404	Not Found	When a non-existent resource is requested
429	Too Many Requests	The error is used when there may be DOS attack detected or the request is rejected due to rate limiting. Please try after 5 seconds
500	Internal Server Error	An unexpected condition prevented the server from fulfilling the request.
502	Bad Gateway	Indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server.
504	Gateway Timeout	Indicates that the server, while acting as a gateway or proxy, cannot get a response in time.

Points to Note:

The scope of the API is only for terminated (delivered / expired) loads for now and the request is based on termination date for the load . Termination date could indicate delivery date or expiration date of the load

For the pre-built Analytics dashboards on Fourkites, Insights includes only the loads that are tracked and delivered loads. All loads are included in the consistency dashboard.

Further, the following cases are also excluded from the pre-built Analytics dashboards:

Test loads

Demo loads

Deleted loads

If the data is missing for any property, then we omit the property in the json response to

The API will support only the loads that are created up to one year back

Tracking Quality API will only work for Non-SSO users that are licensed for Insights API