Pagination and time windows

Several Headcode endpoints share common pagination and time window parameters.

Pagination

List and search endpoints use limit and offset for pagination:

Parameter	Default	Description
limit	20	Maximum number of results to return
offset	0	Number of results to skip

Paginated responses include total, limit and offset fields so you can calculate page counts:

{
  "stations": [ ... ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Endpoints that support pagination

• GET /v1/stations (station search)
• GET /v1/locations (location search)
• GET /v1/operations/alarms (active alarms)
• GET /v1/services (service list / historical discovery)

Maximum limits

Most endpoints cap limit at 100. Station board endpoints also default to 20 with a maximum of 100.

Time windows

Station board endpoints (/departures, /arrivals, /board) support time window parameters that control which period of services is returned:

Parameter	Default	Description
time_offset	0	Shift the query window start by this many minutes from now. Supports negative values.
time_window	120	Duration of the query window in minutes

Examples

Get departures in the next two hours (default):

GET /v1/stations/KGX/departures

Get departures starting 30 minutes from now:

GET /v1/stations/KGX/departures?time_offset=30

Get departures from 15 minutes ago (useful for recently departed services):

GET /v1/stations/KGX/departures?time_offset=-15

Get departures in a narrow 30-minute window:

GET /v1/stations/KGX/departures?time_window=30

Combine both to look at a specific future window:

GET /v1/stations/KGX/departures?time_offset=60&time_window=30

This returns departures between 60 and 90 minutes from now.