> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt
> Use this file to discover all available pages before exploring further.
# Nearest vehicles
> Find vehicles nearest to a coordinate, with optional count and radius.
### Overview
Finds vehicles with recent snapshots nearest to a coordinate, optionally limited by count and radius (meters; implementation rounds distance to 100 m buckets for sorting/filtering).
A V2 version of this endpoint is available: [Nearest vehicles](/v2/api-reference/get-companies-id-vehicles-nearest). New integrations should prefer V2.
### Endpoint
`POST /api/GetNearest`
### Query parameters
Latitude in degrees.
Longitude in degrees.
Company id to scope vehicles.
Max results (default: unlimited in practice via `int.MaxValue` when omitted).
Max distance filter (default: unlimited when omitted).
### Response
**200 OK** — `NearestVehiclesDto`
| Field | Type | Description |
| ------ | ------ | ----------------------------------------------------------------------------------- |
| Status | string | e.g. `Ok` |
| result | array | Each item: `vehicle` (`PositionDto`), `distance` (rounded), `realDistance` (meters) |
### Error responses
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------- |
| 401 | Company not in tree or error object `{ "error": "Company {compId} not found" }` |
## OpenAPI
````yaml openapi.yaml POST /api/GetNearest
openapi: 3.1.0
info:
title: Telemax External API (V1)
version: '2026-04-14'
description: >
Telemax External API — fleet telemetry, vehicle commands, and integrations.
**Base URL:** `https://api.telemax.com.au`
**Authentication:** All routes require a `Bearer` JWT unless marked
`[AllowAnonymous]`.
Obtain tokens via `/api/Authentication/token/api-key` or
`/api/Authentication/token/user`.
**POST-first architecture:** Almost all data endpoints use `POST` with
query-string parameters.
The two exceptions using `GET` are `GetDeviceId` and `GET
/api/devices/{id}/dtc-codes`.
**API versioning:** All responses will include an `X-API-Version` header
containing the
date-based version string (e.g. `2026-04-14`). See the
[Changelog](/v1/changelog) for
the deprecation policy and version history.
For full documentation including error handling, pagination, and known field
quirks, see [docs.telemax.com.au](https://docs.telemax.com.au).
servers:
- url: https://api.telemax.com.au
security:
- BearerAuth: []
paths:
/api/GetNearest:
parameters: []
post:
summary: Get Nearby Vehicles
description: Get vehicles within a specified radius, based on a point specified.
parameters:
- name: lat
description: Latitude
in: query
required: true
example: -26.853388
schema:
type: number
- name: lng
description: Longitude
in: query
required: true
example: 133.275154
schema:
type: number
- name: compId
description: Company ID.
in: query
required: true
example: 85
schema:
type: integer
- name: num
description: Number of vehicles to get.
in: query
required: false
example: 10
schema:
type: integer
- name: radius
description: >
Search radius in **metres** (not kilometres). Example: `5000` = 5 km
radius. Omit to search without a radius constraint.
in: query
required: false
example: 5000
schema:
type: number
- name: Content-Type
in: header
required: false
description: Standard and must keep as it is.
example: application/x-www-form-urlencoded
schema:
type: string
- name: Authorization
in: header
required: true
description: Bearer your_token
example: Bearer {token}
schema:
type: string
responses:
'200':
description: Successful response with array of vehicle records and distances
content:
application/json:
schema:
type: object
properties:
Status:
type: string
example: OK
result:
type: array
items:
type: object
properties:
vehicle:
type: object
properties:
Id:
type: integer
example: 1305200
UtcTime:
type: string
format: date-time
description: Time in UTC
example: '2024-01-15T10:30:00Z'
UserTime:
type: string
format: date-time
description: Time in user timezone
example: '2024-01-15T12:30:00+02:00'
UserTimeFormated:
type: string
description: >
Timestamp in the user's configured date-time
format (e.g. "15/01/2024 12:30:00"). **Note:**
The field name is intentionally misspelled
(`UserTimeFormated`, single 't') to preserve
backward compatibility.
x-legacy-note: >-
Intentional misspelling preserved for backward
compatibility.
example: 15/01/2024 12:30:00
Lat:
type: number
format: double
description: Latitude
example: 40.7128
Lng:
type: number
format: double
description: Longitude
example: -74.006
Speed:
type: number
format: double
description: 'Unit: km/h. Current vehicle speed.'
example: 65.5
Course:
type: integer
description: >-
Direction, degrees (N - 0, E - 90, S - 180, W -
270)
example: 90
Ignition:
type: boolean
description: Ignition status
example: true
Odometer:
type: number
format: float
nullable: true
description: >-
Unit: km. Total distance travelled (odometer
reading).
example: 125000.5
Voltage:
type: number
format: float
nullable: true
description: 'Unit: V (volts). Vehicle battery voltage.'
example: 12.6
Fatigue:
type: string
format: duration
description: >-
ISO 8601 duration string representing continuous
driving time (fatigue monitoring).
example: PT2H30M
EngineHours:
type: number
format: double
description: >-
Unit: hours (decimal). Cumulative engine-on
time. This is a plain number, not an ISO 8601
duration.
example: 30.5
SatSignal:
type: string
description: Satellite signal status
example: Good
Satellites:
type: integer
description: Number of satellites
example: 8
ConnectionStrengh:
type: string
description: >
Connection strength category (e.g. "Excellent",
"Good", "Poor"). **Note:** The field name is
intentionally misspelled (`ConnectionStrengh`,
missing 'd') to preserve backward compatibility
with the legacy API. Use this exact spelling in
your integration.
x-legacy-note: >-
Intentional misspelling preserved for backward
compatibility.
example: Excellent
DeviceId:
type: integer
description: Vehicle ID
example: 12345
IgnitionTime:
type: number
format: double
nullable: true
description: >-
Unit: seconds. Elapsed time since ignition
turned on (trip duration).
example: 3600.5
DeviceName:
type: string
description: Name of the vehicle
example: Fleet Vehicle 001
IMEI:
type: string
description: IMEI of the tracker
example: '123456789012345'
Vin:
type: string
nullable: true
description: VIN of the vehicle
example: 1HGBH41JXMN109186
StartMovingTime:
type: string
format: date-time
nullable: true
description: Time when vehicle started to move, UTC
example: '2024-01-15T08:00:00Z'
StartMovingTimeUser:
type: string
format: date-time
nullable: true
description: Time when vehicle started to move, user timezone
example: '2024-01-15T10:00:00+02:00'
LastMovementTime:
type: string
format: date-time
nullable: true
description: Time when vehicle stopped, UTC
example: '2024-01-15T16:00:00Z'
LastMovementTimeUser:
type: string
format: date-time
nullable: true
description: Time when vehicle stopped, user timezone
example: '2024-01-15T18:00:00+02:00'
LastMovementTimeUserFormated:
type: string
nullable: true
description: >
Time when vehicle stopped, in the user's
timezone and date-time format. **Note:** The
field name is intentionally misspelled
(`LastMovementTimeUserFormated`, single 't') to
preserve backward compatibility.
x-legacy-note: >-
Intentional misspelling preserved for backward
compatibility.
example: 15/01/2024 18:00:00
DrivingTime:
type: integer
description: >-
Unit: seconds. Total driving time within the
current trip.
example: 3000
Driver:
type: string
nullable: true
description: Driver name if any
example: John Smith
FuelLevel:
type: integer
description: Fuel level, %
minimum: 0
maximum: 100
example: 75
DTC:
type: string
nullable: true
description: DTC code
example: P0301
IsDoorLocked:
type: boolean
description: Is the door locked (Deprecated)
example: true
deprecated: true
Address:
type: string
description: Address of the vehicle
example: 123 Main St, New York, NY 10001
EngineEnabled:
type: boolean
description: Whether the engine is enabled
example: true
timeElapsed:
type: number
format: double
description: >
Unit: seconds. Server-side time taken to process
this request. **Note:** This field uses
camelCase (intentional) while most other fields
use PascalCase.
example: 0.125
startedTime:
type: string
format: date-time
description: >
UTC timestamp when this request was received by
the server. **Note:** This field uses camelCase
(intentional) while most other fields use
PascalCase.
example: '2024-01-15T10:30:00Z'
endTime:
type: string
format: date-time
description: >
UTC timestamp when this request completed.
**Note:** This field uses camelCase
(intentional) while most other fields use
PascalCase.
example: '2024-01-15T10:30:01Z'
distance:
type: number
format: double
description: Distance traveled in meters, rounded
example: 10500.0,
realDistance:
type: number
format: double
description: Distance traveled in meters
example: 10500
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
Unauthorized:
description: >
**401 Unauthorized** — JWT is missing, expired, or malformed.
The JWT bearer middleware rejects the request before it reaches the
controller.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: AUTHENTICATION
code: TOKEN_EXPIRED
description: >-
The access token has expired. Request a new token using
/api/authentication/token/user or
/api/authentication/token/api-key.
requestId: req_7f3a2b1c
docUrl: https://docs.telemax.com.au/errors#token-expired
Forbidden:
description: >
**403 Forbidden** — Token is valid but the caller does not have access
to the requested company or vehicle.
Tokens issued for one company cannot access resources scoped to a
different company in the hierarchy.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: AUTHORIZATION
code: COMPANY_ACCESS_DENIED
description: >-
Your token does not grant access to company 99. Ensure you are
using a token issued for this company.
requestId: req_4a1d9e2f
docUrl: https://docs.telemax.com.au/errors#company-access-denied
NotFound:
description: >
**404 Not Found** — The requested vehicle ID, company ID, or IMEI does
not exist or is not accessible.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: NOT_FOUND
code: VEHICLE_NOT_FOUND
description: Vehicle with ID 9999 was not found.
requestId: req_2b8c1a5d
docUrl: https://docs.telemax.com.au/errors#not-found
TooManyRequests:
description: >
**429 Too Many Requests** — Rate limit exceeded. Check the Retry-After
header for the number of seconds to wait before retrying.
Use exponential backoff: wait Retry-After seconds, then double the
interval on each subsequent 429.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: RATE_LIMIT
code: RATE_LIMIT_EXCEEDED
description: Too many requests. Wait 30 seconds before retrying.
requestId: req_6d2f8b4a
docUrl: https://docs.telemax.com.au/errors#rate-limit
InternalServerError:
description: >
**500 Internal Server Error** — An unexpected error occurred. Include
the requestId when contacting support.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: SERVER_ERROR
code: INTERNAL_ERROR
description: >-
An unexpected error occurred. Please try again or contact support
with the requestId.
requestId: req_1e5a3c7d
docUrl: https://docs.telemax.com.au/errors#server-error
headers:
X-RateLimit-Limit:
description: Maximum number of requests allowed per minute for this token.
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Number of requests remaining in the current rate limit window.
schema:
type: integer
example: 47
X-RateLimit-Reset:
description: Unix timestamp (seconds) at which the current rate limit window resets.
schema:
type: integer
example: 1746000060
Retry-After:
description: Number of seconds to wait before retrying after a 429 response.
schema:
type: integer
example: 30
schemas:
ApiError:
type: object
description: Standard error response returned by all API endpoints.
properties:
type:
type: string
description: >-
Error category (e.g. AUTHENTICATION, AUTHORIZATION, NOT_FOUND,
VALIDATION, RATE_LIMIT, SERVER_ERROR).
example: AUTHENTICATION
code:
type: string
description: Machine-readable error code within the category.
example: TOKEN_EXPIRED
description:
type: string
description: Human-readable explanation of the error and how to resolve it.
example: The access token has expired. Request a new token.
requestId:
type: string
description: Unique request identifier for support correlation.
example: req_7f3a2b1c
docUrl:
type: string
format: uri
description: Link to the relevant error documentation page.
example: https://docs.telemax.com.au/errors#token-expired
required:
- type
- code
- description
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
JWT Bearer token obtained from `POST /api/authentication/token/user` or
`POST /api/authentication/token/api-key`.
**Lifetime:** ~24 hours (86,399 seconds). Cache the token and reuse it.
Re-authenticate 5 minutes before expiry.
**Scoping:**
- User tokens are scoped to a single company.
- API key tokens may restrict access to a vehicle allowlist and/or
action set (see token claims).
**No refresh endpoint** — re-authenticate with your credentials when the
token expires.
````