Hours Of Service API

Introduction

NextBillion.ai’s Hours of Service (HOS) API enables logistics platforms to optimize trip planning while ensuring compliance with Hours of Service regulations. By integrating the driver's current activity status, accumulated duty times, and detailed trip itineraries, the service evaluates the feasibility of planned stops. It allows users to choose which regulations that need to be applied for their fleets and accordingly identifies necessary HOS breaks, providing precise timing to maintain safety and regulatory adherence throughout the trip.

POST

https://api.nextbillion.io/hos/trip-plan?key={your_api_key}

Request Parameters

Request Body

Response Schema

Current Driver State and its impact

All the different timers that determine and control HOS compliance - continuous driving, daily drive time, daily on-duty time and cycle duty time are impacted by the driver's current activity at the time of submitting an HOS request. Here is a quick summary of different driver states and its corresponding impact on different timers:

Driver Activity →	daily_drive_minutes_used	daily_duty_minutes_used	minutes_since_last_break	cycle_time
driving	⬆️ Continues increasing from API time	⬆️ Continues increasing	⬆️ Continues increasing	⬆️ Continues increasing
on_duty_not_driving	⏸️ No increase until trip starts	⬆️ Continues increasing	🔁 Reset to 0 if break qualifies, else ⬆️ continues increasing	⬆️ Continues increasing
off_duty	⏸️ No increase until trip starts	⏸️ No increase until trip starts	🔁 Reset to 0 if break qualifies, else ⬆️ Continues increasing	⬆️ Continues increasing
daily_break	🔁 Reset to 0 at trip start	🔁 Reset to 0 at trip start	🔁 Reset to 0	⬆️ Continues to accumulate after trip starts
cycle_break	🔁 Reset to 0 at trip start	🔁 Reset to 0 at trip start	🔁 Reset to 0	🔁 Clears the daily_cycle_duty_times array

Short break qualification for a given current driver state

This section covers when a off_duty or on_duty_not_driving activity by the driver qualifies as a break against continuous driving limitations. Applies only when the driver current activity is one of the following:

on_duty_not_driving
off_duty

Condition	Result
`time_elapsed >= 1800 sec (30min)`	✅ Current break qualifies as a short break→ `minutes_since_last_break = 0`
`time_elapsed < 1800 sec (30min)`	Calculated projected time in the current status. Details in the next rows.
`Projected total break time:(time_elapsed + (trip_start_time - current_time)) >= 1800 sec (30min)`	✅ Current break will qualify before trip → reset `minutes_since_last_break` to 0
`Otherwise`	❌ Does NOT qualify → `minutes_since_last_break` keeps increasing

Sample API Query

1
curl --location 'https://api.nextbillion.io/hos/trip-plan?key=<your_api_key>' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
  "poi_stops": true,
5
  "hos_break_window": 2100,
6
  "hos_regulations": {
7
    "type": "US70H8D",
8
    "include_cycle_reset": false
9
  },
10
  "driver_current_hos_state": {
11
    "daily_drive_time_used": 22000,
12
    "daily_duty_time_used": 26000,
13
    "daily_cycle_duty_times": [],
14
    "driver_current_activity": {
15
      "type": "driving",
16
      "time_elapsed": 1800
17
    }
18
  },
19
  "trip": {
20
    "routing": {
21
      "mode": "truck"
22
    },
23
    "stops": [
24
      {
25
        "stop_id": "origin",
26
        "stop_type": "origin",
27
        "stop_location": "35.2302,-100.2500"
28
      },
29
      {
30
        "stop_id": "destination",
31
        "stop_type": "destination",
32
        "stop_location": "35.4676,-97.5164"
33
      }
34
    ]
35
  }
36
}'
37

Sample API Response

1
{
2
    "status": "Ok",
3
    "warnings": [
4
        "driver is currently driving; trip_start_time is ignored, using current time instead"
5
    ],
6
    "hos_result": {
7
        "trip_stops": [
8
            {
9
                "type": "origin",
10
                "stop_id": "origin",
11
                "hos_feasible": true,
12
                "drive_duration": 0,
13
                "stop_duration": 0,
14
                "departure_time": "2026-08-10T04:38:56Z",
15
                "arrival_time": "2026-08-10T04:38:56Z",
16
                "location": [
17
                    35.2302,
18
                    -100.25
19
                ]
20
            },
21
            {
22
                "type": "off_duty",
23
                "drive_duration": 6800,
24
                "stop_duration": 1800,
25
                "departure_time": "2026-08-10T07:02:16Z",
26
                "arrival_time": "2026-08-10T06:32:16Z",
27
                "location": [
28
                    35.51826,
29
                    -98.870888
30
                ],
31
                "address": [
32
                    {
33
                        "label": "Loves; Clinton, OK; I-40",
34
                        "access": [
35
                            35.51826,
36
                            -98.870888
37
                        ],
38
                        "categories": [
39
                            "Truck Stop"
40
                        ]
41
                    },
42
                    {
43
                        "label": "10331 North 2310 Road, Clinton, OK 73601",
44
                        "countryName": "United States",
45
                        "state": "Oklahoma",
46
                        "county": "Custer",
47
                        "city": "Clinton",
48
                        "street": "North 2310 Road",
49
                        "postalCode": "73601-7557",
50
                        "access": [
51
                            35.51595,
52
                            -98.8736
53
                        ],
54
                        "categories": [
55
                            "Truck Stop"
56
                        ]
57
                    },
58
                    {
59
                        "label": "1501 North Airport Road, Weatherford, OK 73096",
60
                        "countryName": "United States",
61
                        "state": "Oklahoma",
62
                        "county": "Custer",
63
                        "city": "Weatherford",
64
                        "street": "North Airport Road",
65
                        "postalCode": "73096-3322",
66
                        "access": [
67
                            35.53612,
68
                            -98.66204
69
                        ],
70
                        "categories": [
71
                            "Truck Stop"
72
                        ]
73
                    }
74
                ]
75
            },
76
            {
77
                "type": "destination",
78
                "stop_id": "destination",
79
                "hos_feasible": true,
80
                "drive_duration": 10937,
81
                "stop_duration": 0,
82
                "departure_time": "2026-08-10T08:11:13Z",
83
                "arrival_time": "2026-08-10T08:11:13Z",
84
                "location": [
85
                    35.4676,
86
                    -97.5164
87
                ]
88
            }
89
        ],
90
        "post_trip_hos_state": {
91
            "available_drive_time_until_break": 24663,
92
            "available_drive_time": 6663,
93
            "available_on_duty_time": 13463,
94
            "cycle_duty_time_used": 10937
95
        }
96
    }
97
}
98

API Query Limits

NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries per second for continuous requests. Note: We can increase the quota if needed on request. Contact support@nextbillion.ai for more details.

API Error Codes

Response Code	Description	Additional Notes
200	Normal success case.	Normal success case.
400	Input validation failed.	There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401	APIKEY not supplied or invalid	This error occurs when the wrong API key is passed in the request or the key is missing altogether
403	APIKEY is valid but does not have access to requested resources	You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you.
404	Requested host/path not found	This error occurs when a malformed hostname is used.
422	Could not process the request.	A feasible solution could not be generated for the given set of locations or parameter configuration.
429	Too many requests.	QPM reached or API request count quota reached.
500	Internal Service error.	There was an internal issue with NextBillion.ai services. You can reach out to support@nextbillion.ai for an explanation.