This endpoint enables data providing type of companies (ie. carriers, logistics-service-providers) to

check which vehicles are available for allocation
- List vehicles: This will list all own vehicles and vehicles from subcontractors with 24/7 permission.
- Search for a specific vehicle: This will return one or multiple vehicles that match the search criteria, even if this vehicle is not an own or granted one with 24/7 permission.
find a vehicle with a license plate notation difference between your inhouse system and how it's received by Transporeon.
see the latest position/direction/speed of the vehicle.

Note that:

Not all data might be available, as it's dependent on what Visibility Hub receives from it's data sources, which are usually telematics providers.
Besides own vehicles, only vehicles from subcontractors, which are in your visibility network, can be search on. To learn more about your visibility network, see here.

List All Own Vehicles and Vehicles from Subcontractors with 24/7 Permission

To lookup vehicles, that are connected to your account in Visibility Hub, make an authenticated GET request as shown in the example below.

The response will contain all

own vehicles (that you added via an telematics integration to your account) and
subcontractor vehicles, that have 24/7 visibility permission enabled (learn more here).

The example below shows a list of vehicles with the following parameters:

license_plate_number: The license plate number of the vehicle
is_own_vehicle: If the vehicle belongs to the requestor (true) or if it's a subcarrier vehicle (false)
integration_vehicle_id: The unique id of the vehicle from the telematics provider
integration_id: The Visibility Hub internal ID of the telematics provider integration
vehicle_position: The latest position known for this vehicle based on telematics provider updates

https://api.transporeon.com/rtv/v1/vehicles

{
    "vehicles": [
        {
            "license_plate_number": "AB 12 CD",
            "is_own_vehicle": true,
            "integrations": [
                {
                    "integration_vehicle_id": "85192",
                    "integration_id": "59"
                }
            ],
            "vehicle_position": {
                "timestamp": "2022-05-24T10:28:27.449Z",
                "position": {
                    "lat": 52.5200154,
                    "lng": 13.4049545
                }
            }
        },
        {
            "license_plate_number": "GF 88 BD",
            "is_own_vehicle": true,
            "integrations": [
                {
                    "integration_vehicle_id": "85193",
                    "integration_id": "59"
                }
            ],
            "vehicle_position": {
                "timestamp": "2022-05-25T10:28:27.765Z",
                "position": {
                    "lat": 52.5200154,
                    "lng": 13.4049545
                }
            }
        },
        {
            "license_plate_number": "AL 65 JE",
            "is_own_vehicle": false,
            "integrations": [
                {
                    "integration_vehicle_id": "65478",
                    "integration_id": "77"
                }
            ],
            "vehicle_position": {
                "timestamp": "2022-05-31T13:29:12.637Z",
                "position": {
                    "lat": 52.5200154,
                    "lng": 13.4049545
                }
            }
        },
	...
    ],
    "page_info": {
        "cursor": "YXJyYXljb25uZWN0aW9uOjk5"
    }
}

Note that based on the page_info field at the bottom, more vehicles are available in the response. To read more about how pagination is implemented in the Visibility APIs, click here.

Search for a Specific Vehicle

You can lookup a specific vehicle by appending the license_plate_number in the URL of the request

Note that the provided license plate must have a normalized length of 3 or above. Normalization retains only alphanumeric characters. A request with less than 3 characters will fail.

Make an authenticated GET request as shown in the example below:

https://api.transporeon.com/rtv/v1/vehicles/AB%2012%20CD

Response

{
    "vehicles": [
        {
            "license_plate_number": "AB 12 CD",
            "is_own_vehicle": false,
            "integrations": [
                {
                    "integration_vehicle_id": "74986",
                    "integration_id": "59"
                }
            ],
        }
    ],
    "page_info": {}
}

Note that the result is still a list of vehicles. The reason is that the license_plate_number lookup supports partial match. Means that if the search string matches multiple license plates, even only partially, all are returned.

This is especially helpful if the notation of the license plate that you have in your inhouse system does not exactly match the license plate known to Transporeon (which is defined by the telematics provider).

Note that in the example above, the vehicle_position field is not shown. Reason: It's only shown for own vehicles and granted vehicles from subcontractors 24/7 visibility permission enabled (learn more here).

For the vehicle "AB 12 CD" above it means that it's not an own vehicle ("is_own_vehicle": false) and the 24/7 visibility permission is not enabled (because the vehicle_position is not shown).

Please note that for vehicles that have never transmitted a vehicle position, the field is also not shown.

Example with Partial Match

Make an authenticated GET request as shown in the example below:

https://api.transporeon.com/rtv/v1/vehicles/AB%2012%20CD

{
    "vehicles": [
        {
            "license_plate_number": "AB 12 CD Harry",
            "is_own_vehicle": true,
            "integrations": [
                {
                    "integration_vehicle_id": "85192",
                    "integration_id": "59"
                }
            ],
            "vehicle_position": {
                "timestamp": "2022-05-24T10:28:27.449Z",
                "position": {
                    "lat": 52.5200154,
                    "lng": 13.4049545
                }
            }
        }
     ],
     "page_info": {}
}

The vehicle is still found, even if the license plate contains "Harry" as a suffix.