Introduction: Create vehicles

For general information about how vehicles work in Fleet Engine, see the following guides in the Fleet Engine essential section:

The documentation in this section describes how to create and manage vehicles in Fleet Engine. You create vehicles in the Fleet Engine server environment to mirror the actual vehicles in your real-world operation. Your Fleet Engine vehicles should also correspond to those used in your backend system that you use for vehicle assignments and routing.

You use a create method to create a vehicle resource, either using gRPC or REST. The field names in this guide use gRPC notation for simplicity.

On-demand trips

CreateVehicleRequest (gRPC)
providers.vehicle.create (REST)
Vehicle resource (REST, gRPC)

Scheduled tasks

CreateDeliveryVehicleRequest (gRPC)
providers.deliveryVehicles.create (REST)
DeliveryVehicle (REST, gRPC)

Vehicle requests

For both on-demand and scheduled task capabilities, you create and update a vehicle by issuing a request message with fields, summarized as follows:

The parent: a string associated with your Google Cloud project ID, used to populate the name field of the vehicle instance.
The ID for the vehicle: a unique string used to populate the name field of the vehicle.

Note: Vehicle ID strings have certain character restrictions. Avoid auto-incrementing IDs and ensure they contain no personally-identifiable information. For details on character restrictions, see the vehicle ID field for CreateVehicleRequest or CreateDeliveryVehicleRequest.
A vehicle instance with its required fields. These fields depend on the Fleet Engine capability you use.

The information in the request body varies with the nature of the request. See those details under their respective guides.

Authentication and authorization tokens

Requests to Fleet Engine must also provide the correct access credentials. The examples in this guide have the following assumptions:

gRPC examples assume the use of the Authorization library for Java.
REST examples illustrate an HTTP request header, which must contain the field Authorization with a value of Bearer <token> where <token> is a JSON Web Token you issue.

For more details, see the Set up Fleet Engine guides.

Vehicle resource fields

A vehicle resource has the following kinds of fields:

Output only fields. Fields that are set by the service as an output of another method and cannot be directly set. An important field of this type is the name field. Fleet Engine ignores any supplied value for the name field of the vehicle per guidance from Google AIP for user-specified IDs. If you supply values for these fields, Fleet Engine returns an error.
Required fields. Vehicles created in the on-demand trip service require that certain fields be set on creation. Vehicles created in the scheduled tasks service have no required vehicle resource fields.
Optional fields. Both services have fields which you can set on creation or afterwards. These can be found in the respective reference guide for the service you use.

Vehicle name (output only)

The name field is exactly the same for on-demand trips and scheduled task services. Fleet Engine defines the field when you create the vehicle, based on two fields you set at vehicle creation:

The parent: a string associated with your Google Cloud project ID of the form providers/{provider} where {provider} is the ID of your Cloud project. Each vehicle you create for a given project will have the same parent path.

The Cloud project you reference here must also contain the Fleet Engine service account roles for the service you use. See Service Accounts for a list of those service accounts. Fleet Engine does not support access from multiple Google Cloud projects.
The ID for the vehicle, which must be unique across all vehicles in your fleet and be a valid Unicode string. This is the resource ID for the vehicle. Both on-demand trips and scheduled stops use this to associate a trip or a task with the vehicle that completes it.

In Google Cloud-based services, all APIs must represent resources as strings. See Resource naming in Fleet Engine for more details.

Unique entity identifiers

The format and value of the unique entity identifiers used in resource calls are opaque to Fleet Engine. Make sure that the identifier does not contain any personally-identifiable information (PII), such as the driver's phone number.

Vehicle re-use

After a vehicle completes all stops for a given itinerary, it remains available for re-use in Fleet Engine for 7 days, which means you can reuse a vehicle on subsequent business days without having to create a new one. Each time you reuse a vehicle, Fleet Engine resets its availability, at which point the 7-day countdown begins anew.

The recommended approach to keep a vehicle available in Fleet Engine is to update its location at regular intervals. Updates to most other fields in the Vehicle entity will also extend its life, provided that the new field value is different from the existing one.

NOTE: Some fields on Vehicle entity like device_settings are purely debug information that are not persisted by Fleet Engine. Updating them does not extend the life of the Vehicle entity.

For improved system analytics, it's best to re-use the same driver-vehicle ID pairing from day to day. Do this by using the same vehicle ID associated with the driver for previous scheduled stops or on-demand trips.