KVH API

IMPORTANT! KVH API is available only to authorized users on the account by request. See Step 1 below.

KVH API allows you to access API data such as terminal status and usage, as well as available telemetry data.

Note: KVH API calls are rate-limited to 300 requests per minute for a single user. Peak data accuracy is achieved at an update frequency of once every ten minutes. Faster rates will not produce better information, as most data sources themselves do not report more frequently than once every ten minutes.

Getting Started

Before your designated users can start using the KVH API, the following essential steps must be completed.

Step 1: Request API Permissions

Contact KVH’s Airtime Services Department and ask them to apply API ACCESS permission to your account. If you have multiple accounts, choose the highest-level account in your account hierarchy that contains all the sub-accounts and terminals that you want to access via the API. The API ACCESS permission is inherited by all its child accounts.

In addition, request the following permission levels for each KVH Manager user that you would like to grant access to the API:

API USER
FLEET ADMIN

Provide KVH with the email address for each designated user. For example, if you manage multiple sub-accounts, one for each of your customers, you might grant API permissions to the manager of each sub-account.

IMPORTANT! Each designated user must already be an authorized user for their account or sub-account(s) in KVH Manager. Users will only have API access to the terminals associated with those accounts.

Step 2: Identify the Account ID(s)

To make an API request, you will need the Salesforce account ID for the account that contains the desired terminal(s). You can find this account ID in your web browser's address bar when you select the account in KVH Manager. In the example below, if you need API data for the "Starlink Kit Demo" terminal (15379866-SLK), you would use the account ID for the "KVH Manager Testing" sub-account (0014X00142ZMtjPMAT). You would NOT use the account ID for the parent account "KVH Industries, Inc. - World Headquarters" because the desired terminal is not located directly under that top-level account; it is under the sub-account.

Note: If you know the top-level account ID, you can use the API to view all of its sub-account IDs and all of the terminals associated with them. See Retrieving Terminal IDs from Account Information below for details.

Step 3: Generate API Credentials

Once your designated user(s) have API permissions, they will have access to the KVH API page the next time they log into KVH Manager. Each user must then follow these steps to generate their own unique API access keys:

Go to the KVH API page of KVH Manager.
Select Generate Access Keys. These consist of a Client ID (user's email address) and a Client Secret.
Copy and paste the Client Secret to a text editor, such as Notepad, for later use.

IMPORTANT! Do not share your Client Secret with anyone, as it is confidential and can be used to generate access tokens for retrieving sensitive account information, such as terminal usage.

Step 4: Request Access Token(s)

Now each designated user can apply their unique Client ID and Client Secret to request access tokens for their associated account or sub-account(s). Each account or sub-account requires a unique access token to authorize access to its terminals' data. To request an access token, enter the following sample curl command into a shell script program such as Bash, making sure to replace the Client ID and Client Secret with your credentials, and the scope with your account ID:

curl -sSL 'https://mapi.mykvh.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "username@example.com",
"client_secret": "your-client-secret-is-here",
"audience": "https://api.mykvh.com",
"grant_type": "jwt_bearer",
"scope": "account#1234567890aBcD5ABC"
}'

The above curl command will return the following sample payload, containing your access token for that account's data:

{
"access_token":"eyJ0eXAiOiJKV1QiL...JhbGciOiJIUzI1NiJ",
"scope": "account#1234567890aBcD5ABC",
"expires in": 3600,
"token_type": Bearer"
}

Note: Access tokens are valid for up to one hour. If your access token expires, repeat the steps above to request a new one.

Note: If you are using a Windows PC instead of Linux, you may copy and paste this curl command in Notepad, remove all carriage returns, and paste it into the Windows Command prompt. Then you may use the returned "access token" field in the Swagger API interface.

Step 5: Exercise the API

Your designated users now have everything they need to use the KVH API. Before writing any code to integrate it into your application, exercise the API using KVH's Swagger interface at https://api.mykvh.com/v3/docs/. Follow the steps below to view terminal usage, status, and telemetry data.

IMPORTANT! You will need to enter the unique access token for the account that includes the requested terminal.

Viewing Terminal Usage Data

To view terminal usage data, follow these steps:

Go to https://api.mykvh.com/v3/docs/.
Select Authorize in the upper-right corner of the page and enter your access token.
Select GET/v3/terminals/{terminal_id}/usage > Try it out.
Enter your terminal ID and select Execute.

Interpreting Terminal Usage Data

The following key information is included in the KVH API terminal usage payload:

Plan: Name of data plan and its associated data allowance
Traffic ID: Traffic identifier used internally by KVH
Allowance: Prorated or full allowance of data plan
Overage: Data usage outside of allowance for current billing cycle (always 0 if unlimited); Opt-In or Opt-Out
Usage: Current data usage
Service Code: Billing code associated with terminal type

Note: Refer to the table below for a more detailed description of service codes.

Service Code Definitions

Service code	terminal Type
CZ#	Coastal
HTS	Any KVH VSAT
ICD or ICV	Iridium
LTE	LTE-1
LTV	LTE Global
SLK	Starlink (Priority, Rated)
SLO	Starlink (Non-Priority Free Overage)
SLP	Starlink (Priority, Unrated)
SLD	Starlink (Priority Data Block, Rated)

Note: Service codes are subject to change without notice.

Viewing Terminal Status Data

To view terminal status data, follow these steps:

Go to https://api.mykvh.com/v3/docs/.
Select Authorize in the upper-right corner of the page and enter your access token for the associated account/sub-account.
Select GET/v3/terminals/{terminal_id}/status > Try it out.
Enter your terminal ID and select Execute.

Interpreting Terminal Status Data

The following key information is included in the KVH API terminal status payload:

Latitude and Longitude: Vessel's current position
Heading: Vessel's current heading (null if unavailable)
Alerts: Any active system errors or warnings
Uptime in seconds: Length of time system has been online since it was booted
System type: Type of terminal (STARLINK, or UNDEFINED if not given)
Kit number: Starlink system (KIT) serial number
Device ID: Starlink terminal ID
Service line ID: Starlink service line ID (associates a service address and a subscription)
Availability: See chart below

Terminal Availability Status Definitions

status	description
Online	Last update < 2 hours (< 1 hour for Iridium terminals)
Available	Last update < 24 hours (only visible for Iridium terminals)
Offline	Last update < 48 hours (< 24 hours for Iridium terminals)
Aged	Last update < 30 days
Unknown	Not known

Viewing Telemetry Data

To view the Starlink telemetry data available for a given terminal, follow these steps:

Go to https://api.mykvh.com/v3/docs/.
Select Authorize in the upper-right corner of the page and enter your access token.
Select POST/v3/terminals/{terminal_id}/telemetry/timeline > Try it out.
Enter your terminal ID.
Enter the start and end UNIX timestamps for the desired time period within the past 30 days.
Select Execute.

Note: Telemetry information is only reported during periods when system is online and data is being transferred.

Interpreting Telemetry Data

The following key information is included in the telemetry payload:

Downlink Throughput: Average download speed
Uplink Throughput: Average upload speed
Latency: Average latency measured to the Starlink point of presence (POP)
Ping Drop Rate: Percentage of pings that have dropped
Signal Quality: Signal to noise ratio (SNR) expressed as a percent from 0 dB to 10 dB
Obstruction: Percent of time the antenna is obstructed

The following elements are included for each telemetry object:

Definitions of Telemetry Elements

Field	description
Scope	Telemetry object (see above)
Min	Minimum recorded value in requested time period
Max	Maximum recorded value in requested time period
Last	Last recorded value in requested time period
Unit	Units in which reported values are measured (e.g., bps, ms, or percent)
Fixed parts	Average values reported in 14-minute intervals spanning the requested time period

Retrieving Terminal IDs from Account Information

KVH API enables you to automate the creation of a terminal ID list. Start by retrieving the sub-account IDs from the top-level account, then use these IDs to view additional sub-account IDs. You can then use these sub-account IDs to generate a list of associated terminal IDs.

Follow these steps to generate a list of sub-accounts:

Go to https://api.mykvh.com/v3/docs/.
Select Authorize in the upper-right corner of the page and enter your access token.
Select GET/v3/terminals/{account_id}/accounts > Try it out.
Enter your top-level account ID and select Execute.
Repeat steps 1-4 for each sub-account to view additional sub-accounts.

Follow these steps to generate a list of terminals associated with a sub-account:

Go to https://api.mykvh.com/v3/docs/.
Select Authorize in the upper-right corner of the page and enter your access token.
Select GET/v3/terminals/{account_id}/terminals > Try it out.
Enter your account ID and select Execute.

Was this topic helpful? Please share your feedback.