# Get cursor-based vehicle

Retrieve vehicle in bulk using cursor-based paging (see the Cursor-based pagination documentation on the PTV Developer Portal).

Endpoint: GET /vehicles
Version: 1.1.1
Security: clientCredentials

## Query parameters:

  - `cursor` (string)
    The cursor of the page to return. No cursor is expected for the initial request. The cursors returned by this endpoint can be used for subsequent requests.

  - `limit` (integer)
    Number of results to return per page.

## Response 200 fields (application/json):

  - `data` (array)
    The set of results for the current page.

  - `data.id` (string)
    Unique identifier for this `Vehicle`.
    Example: truck-42

  - `data.description` (string)
    Description of the vehicle.
    Example: Horn plays La Cucaracha - use sparingly in residential areas

  - `data.mandatory` (boolean)
    Whether OptiFlow must use this vehicle in a planning or not. If false, OptiFlow will only use this vehicle when it makes sense to do so.
    Example: true

  - `data.driver` (object)

  - `data.driver.name` (string)
    Name of the driver.
    Example: John Doe

  - `data.driver.efficiency_factor` (number)
    Factor applied to service times and location stop times. A value of 1.0 (the default) does not alter the timings. Values < 1.0 increase the timings (lower efficiency), values > 1.0 decrease the timings (higher efficiency).
    Example: 1.2

  - `data.start` (object, required)

  - `data.start.location` (object, required)

  - `data.start.location.address` (object)

  - `data.start.location.address.id` (string, required)
    Unique identifier for this address.
    Example: 50.9514048-3.8067878

  - `data.start.location.address.name` (string)
    Human-readable name for the location.
    Example: The office

  - `data.start.location.address.address_line` (string)
    The part of the address that includes the street name, house number, bus number etc. Required when omitting `geo_point`.
    Example: Voordries 41

  - `data.start.location.address.city` (string)
    City name. Required when omitting `geo_point`.
    Example: Oosterzele

  - `data.start.location.address.zip_code` (string)
    Postal code. Required when omitting `geo_point`.
    Example: 9860

  - `data.start.location.address.country_code` (string)
    A ISO3166-1 alpha-2 two letter country code. Required when omitting `geo_point`.
    Example: BE

  - `data.start.location.address.geo_point` (object)

  - `data.start.location.address.geo_point.latitude` (number, required)
    Example: 50.9514048

  - `data.start.location.address.geo_point.longitude` (number, required)
    Example: 3.8067878

  - `data.start.location.address.geo_point.resolved` (object)
    Geocoding resolution information.

  - `data.start.location.address.geo_point.resolved.geocoded` (boolean)
    Indicates if the provided address was geocoded or not.
Geocoding only happens when the provided address does not yet have a geo-point.
    Example: true

  - `data.start.location.address.geo_point.resolved.address` (string)
    The address that matches the resolved geo-point. Only present when `geocoded` is `true`.
    Example: Voordries 41, 9860 Oosterzele

  - `data.start.location.address.geo_point.resolved.precision` (integer)
    Geocoding confidence score from 0-10.
10 indicates 100% confidence that the coordinates match the provided address. 0 indicates no confidence in the match.
Only present when `geocoded` is `true`.
    Example: 9

  - `data.start.location.at_first_activity` (boolean)
    When true, the vehicle starts at the location of its first activity.
    Example: false

  - `data.start.service_time` (string)
    Service time at the start location, formatted as ISO-8601 duration.
    Example: PT20M

  - `data.start.orders_to_deliver_available` (boolean)
    Indicates whether the orders to deliver are already available at the start location.

When true, the vehicle can begin deliveries immediately.

When false, the vehicle must first drive to a depot to pick up orders before it can start delivering.

Note: When the planning is a multi-tour VRP planning, only the orders to deliver on the first sub-tour are available at the start location.
    Example: true

  - `data.end` (object, required)

  - `data.end.location` (object, required)
    End location for the vehicle. Only one of the properties should be set.

  - `data.end.location.at_last_activity` (boolean)
    When true, the vehicle ends at the location of its last activity.
    Example: false

  - `data.end.location.same_as_start` (boolean)
    When true, the vehicle returns to its start location.
    Example: false

  - `data.end.service_time` (string)
    Service time at the end location, formatted as ISO-8601 duration.
    Example: PT15M

  - `data.end.allow_picked_up_orders` (boolean)
    Indicates whether the vehicle can end its route with picked-up orders still on board.

When true, the vehicle can drive directly to the end location with picked-up orders remaining on board.

When false, the vehicle must visit a depot to unload all picked-up orders before driving to the end location.
    Example: true

  - `data.deployability` (object, required)

  - `data.deployability.window` (object, required)

  - `data.deployability.window.start` (object, required)

  - `data.deployability.window.start.earliest` (string, required)
    Earliest time the vehicle can start.
    Example: 2025-01-01T08:00:00Z

  - `data.deployability.window.start.latest` (string)
    Latest time the vehicle can start.
    Example: 2025-01-01T10:00:00Z

  - `data.deployability.window.end` (object, required)

  - `data.deployability.window.end.latest` (string, required)
    Latest time the vehicle must end.
    Example: 2025-01-01T18:00:00Z

  - `data.deployability.duration` (object)
    When specified, one of both durations must be > PT0S

  - `data.deployability.duration.at_most_without_overtime` (string, required)
    Maximum deployment duration, without overtime, formatted as ISO-8601 duration.
    Example: PT8H

  - `data.deployability.duration.allowed_overtime` (string, required)
    Additional overtime allowed, formatted as ISO-8601 duration. When specified and > PT0S, the `overtime_per_hour` cost must also be provided.
    Example: PT2H

  - `data.capabilities` (array)
    Capabilities this vehicle provides.
Used to make sure that orders requiring a specific capability, are only handled by vehicles with that capability.
Note: if a capability contains a dash, it will be split into two capabilities upon exporting and re-importing the vehicle set in PTV OptiFlow Route Optimization.
    Example: ["refrigerated","hazmat"]

  - `data.transport_resource` (object)

  - `data.transport_resource.license_plate` (string)
    License plate of the transport resource.
    Example: 1-ABC-234

  - `data.transport_resource.capacities` (array)
    Capacity specifications for the transport resource.
    Example: [{"type":"weight","value":3500},{"type":"volume","value":25.5}]

  - `data.transport_resource.capacities.type` (string, required)
    Type of capacity measurement
    Enum: "volume", "weight", "loadingMeters", "capacity1", "capacity2", "capacity3", "capacity4", "capacity5"

  - `data.transport_resource.capacities.value` (number, required)
    Capacity value.
    Example: 100

  - `data.labels` (array)
    Labels for categorizing vehicles. Can be used for facility filtering or defining constraints.
Note: if a label contains a dash, it will be split into two labels upon exporting and re-importing the vehicle set in PTV OptiFlow Route Optimization.
    Example: ["priority","express"]

  - `data.cost` (object)

  - `data.cost.fixed` (number)
    Fixed cost for using this vehicle.
    Example: 50

  - `data.cost.per_hour` (number)
    Hourly cost applied when this vehicle is in use, including drive time, wait time, and service time.
    Example: 25

  - `data.cost.per_kilometer` (number)
    Cost per kilometer.
    Example: 0.5

  - `data.cost.per_stop` (number)
    Cost per stop this vehicle makes. Note that stops at depots or breaks are not considered as separate stops.
Deprecated in favor of vehicle stop rule sets in plan profiles.
    Example: 12

  - `data.cost.overtime_per_hour` (number)
    Cost per hour overtime. When specified, the `deployability` durations must also be provided and `allowed_overtime` must be > PT0S.
    Example: 30

  - `data.route_settings` (object)

  - `data.route_settings.routing_group` (string)
    Routing group for this vehicle. Allows bulk assignment of routing profiles to all vehicles in the group during planning.
    Example: medium-truck

  - `data.route_settings.max_distance_in_kilometers` (number)
    Maximum total distance for this vehicle's route, calculated as the sum of all subtour distances.
    Example: 450

  - `data.route_settings.max_stops` (integer)
    Maximum number of stops allowed per route for this vehicle. Deprecated in favor of vehicle stop rule sets in plan profiles.
    Example: 10

  - `data.route_settings.driving_speed_factor` (number)
    Multiplier applied to this vehicle's default speed.
    Example: 1.5

  - `data.route_settings.preferred_route_duration` (object)

  - `data.route_settings.preferred_route_duration.duration` (string)
    The preferred duration of the route assigned to the vehicle.
If omitted, the preferred route duration of this vehicle is the average route duration.
    Example: PT8H

  - `data.route_settings.preferred_route_duration.importance` (number, required)
    A scale between 0 and 1 resembling a tradeoff between minimizing the total hour cost and steering towards the preferred duration of the vehicle.
Higher values indicate a stronger preference for a route duration close to the preferred one.
As the cost per hour increases, the influence of this tradeoff becomes more significant.
    Example: 0.5

  - `data.color` (string)
    The color used to display this vehicle's route in the planning overview.
Accepts CSS color names (e.g., "red", "blue") or hexadecimal color codes (e.g., "#FF5733", "#123DEF").
    Example: #FF5733

  - `data.break_rule_group` (string)
    Break Rule group for this vehicle. Allows bulk assignment of break rules to all vehicles in the group during planning.
    Example: BELGIUM-LEGAL

  - `data.plan_group` (string)
    Plan group for this vehicle. Can be used for filtering.
    Example: PLAN-GROUP-1

  - `data.battery` (object)
    Early Access

  - `data.battery.capacity` (integer, required)
    Battery capacity in kWh.

  - `data.battery.consumption` (object, required)

  - `data.battery.consumption.per_hundred_kilometers` (number, required)
    Battery consumption per 100 km in kWh.

  - `data.battery.state_of_charge` (object)

  - `data.battery.state_of_charge.initial` (number)
    The initial battery energy level as a fraction of total capacity (0.0 = empty, 1.0 = fully charged).

  - `data.battery.state_of_charge.minimum` (number)
    The minimum allowed battery energy level as a fraction of total capacity (0.0 = empty, 1.0 = fully charged).

  - `data.etag` (string)
    Example: W/"25"

  - `cursors` (object)
    Pointer(s) to related result pages.

  - `cursors.next` (string)
    Pointer to the next page of results.

## Response 400 fields (application/problem+json):

  - `title` (string)
    A short, summary of the problem.
    Example: Validation exception

  - `detail` (string)
    A detailed explanation specific to this problem.
    Example: The field contains invalid business formatting.

  - `violations` (array)

  - `violations.field` (string)
    Example: path.to.field

  - `violations.message` (string)
    Example: Field is required