Getting Started

Getting Started#

This section outlines how to quickly get started using MOIA’s Fleet API product. More detailed information on these and other concepts of the Fleet API, can be found in the appropriate sections of the Developer Guide. In this guide, we will use an example of the Fleet State Service for which the API reference documentation is available here. Check out our API reference documentation for further information on all available services.

Requirements#

This guide requires curl and grpcurl to be installed. grpcurl will require the Protobuf definitions of the Fleet API as input which we provide as a zip archive. The zip archive includes:

Protobuf definitions of the Fleet API,
buf.yaml configuration file for optional usage of buf,

You can download the zip archive here: fleet_api.zip.

For later usage, unzip the zip archive e.g:

unzip ./downloads/fleet_api.zip -d ./downloads

Setup Credentials#

MOIA will provision credentials for evaluating / integrating with the Fleet API product.

Note

Evaluation Credentials

Evaluation credentials are valid for a limited time period and will allow testing of the Fleet API with an example Fleet/s containing a small set of Vehicles. With evaluation credentials you can immediately get started, following these steps.

In order to start working with the Fleet API you need to request an API access token from our API gateway.

Retrieve the API token using the following request providing the credentials using the Authorization header. Replace $CLIENT_ID and $CLIENT_SECRET with the credentials provided.

curl \
--location "https://fleet-api.trip.int.moia-group.io/auth/oauth/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data-urlencode "grant_type=client_credentials"

You will need an <ACCESS_TOKEN> for all subsequent requests. Set the token as an environment variable for convenience in the following steps. Replace <ACCESS_TOKEN> with the token you received through authentication with the API gateway, in the previous step.

export ACCESS_TOKEN=<ACCESS_TOKEN>

Note

Authentication Problems

In cases when a 401 error is repeatedly returned, please retry the Authentication steps. If this problem persists, please contact us as there may be a problem with your credentials.

In cases when a 464 error is returned, please make sure that you are using HTTP/2 as the authentication endpoint is only accessible via HTTP/2.

Structure of Basic API Call#

To place an API call with grpcurl set the following options:

Provide the Bearer token for authorization in the header with -H "authorization: Bearer $ACCESS_TOKEN"
Provide the paths in which the protobuf definitions are located, e.g. -import-path <PATH_TO_FLEET_API_PROTOS>
Provide the JSON formatted request data with -d '<JSON_FORMATTED_REQUEST>'
State the name of the protobuf source file for the corresponding gRPC service:
- -proto fleet_state.proto for Fleet State Service
- -proto maps.proto for Maps Service
- -proto routing.proto for Routing Service
For convenience, set -emit-defaults to show default values in the responses.

Note

TLS

Fleet API uses TLS for transport encryption. grpcurl enables TLS by default. If you use another client to evaluate the API make sure TLS is enabled.

To test the import-path configuration of grpcurl the following command can be adjusted until successful.

grpcurl \
 -import-path ./fleet_api/ \
 -proto fleet_state.proto \
describe

List Fleets#

Users of MOIAs Fleet API can have access to 0 or more Fleets of Vehicles. We can query all Fleets available to a user with the following request. Make sure to be in the same directory as the fleet_state.proto file that was downloaded in requirements.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto -emit-defaults \
fleet-api.trip.int.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/ListFleets

Example output:

{
  "fleets": [
    {
      "id": "d51ae7a5-7316-419e-be82-a2811256eeb9",
      "description": "Austin",
      "operationalAreaId": "d51ae7a5-7316-419e-be82-a2811256eeb9"
    }
  ]
}

In the response, we will receive a list of all the Fleets available to the user. For each Fleet there is a Fleet ID and Description. From the list of Fleets we need to select a Fleet ID that we will continue working with.

Note

Evaluation Fleet

MOIA evaluation credentials will come with access provisioned to an example Fleet (ID: d51ae7a5-7316-419e-be82-a2811256eeb9) with a couple of vehicles available.

List Vehicles#

Now we want to retrieve info on all the Vehicles of a specific Fleet. For this we need to know the fleet_id that we are interested in (of the Fleets returned by ListFleets).

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto \
-d "{ \"fleet_id\": \"$FLEET_ID\"}" \
fleet-api.trip.int.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/ListVehicles

Example output:

{
  "vehicles": [
    {
      "id": "50027692-016f-482d-a311-d6f9063d6abc",
      "vin": "AUSTIN-VEHICLE-42",
      "licensePlate": "AUS-42",
      "label": "42",
      "telemetry": {
        "location": {
          "latitude": 30.273812764653634,
          "longitude": -97.73927946039707
        },
        "heading": 353.03143310546875
      },
      "configuration": {
        "selfDriving": true
      },
      "mission": {
        "id": "ffbda218-e230-3fc8-8cd1-b94ab9e93b3e",
        "waypoints": []
      },
      "status": {
        "readyForNewRides": false,
        "online": false
      }
    },
    {
      "id": "819f0cda-62dd-4251-9efd-9c4294b4f42d",
      "vin": "WVWNP9ANXCE000000",
      "licensePlate": "AUS-430",
      "label": "430",
      "telemetry": {
        "location": {
          "latitude": 30.26020822482599,
          "longitude": -97.73298812305585
        },
        "heading": 0
      },
      "configuration": {
        "selfDriving": true
      },
      "mission": {
        "id": "8ee57702-4c23-3064-aa10-e3f039870063",
        "waypoints": []
      },
      "status": {
        "readyForNewRides": true,
        "online": true
      }
    }
  ]
}

This request returns a list of all vehicles in this Fleet. For each vehicle we have semantic information including ID, Label and Mission. Mission providing a set of Waypoints and Waypoint Actions that this vehicle has been tasked to complete.

We use paging for all our list endpoints, in case your results returns a nextPageToken, you can use it to query the next page of results. See Pagination for more information.

Get Vehicle#

In certain use cases, we may only want to retrieve information on a single Vehicle in the Fleet.

Note

Evaluation Vehicle

MOIA evaluation credentials will come with access provisioned to an example Fleet (ID: d51ae7a5-7316-419e-be82-a2811256eeb9) with a couple of vehicles available. For testing purposes we recommend using Vehicle 430 - Vehicle ID: 819f0cda-62dd-4251-9efd-9c4294b4f42d.

With a specific vehicle_id, we are able to retrieve information for this Vehicle only.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto -emit-defaults \
-d "{ \"vehicle_id\": \"$VEHICLE_ID\" }" \
fleet-api.trip.int.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/GetVehicle

Example output:

{
  "vehicle": {
    "id": "819f0cda-62dd-4251-9efd-9c4294b4f42d",
    "vin": "WVWNP9ANXCE000000",
    "licensePlate": "AUS-430",
    "label": "430",
    "telemetry": {
      "location": {
        "latitude": 30.26020822482599,
        "longitude": -97.73298812305585
      },
      "heading": 0
    },
    "configuration": {
      "selfDriving": true
    },
    "mission": {
      "id": "8ee57702-4c23-3064-aa10-e3f039870063",
      "waypoints": []
    },
    "status": {
      "readyForNewRides": true,
      "online": true
    }
  }
}

The response returns information on the specific Vehicle only.

Stream Vehicle Telemetry Movement#

Now we may want to get continuous updates on a Vehicle’s movement. This is provided via non-durable streams.

With a specific vehicle_id, we are able to get live updates of the movement of this Vehicle only. A vehicle only emits updates of its location if it is online. We can check in the response of GetVehicle whether this is the case.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN"  -import-path .  -proto fleet_state.proto -emit-defaults \
-d "{ \"vehicle_id\": \"$VEHICLE_ID\" }" \
-max-time 30 \
fleet-api.trip.int.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/SubscribeToVehicleTelemetryMovement

Example output:

{
  "vehicleMovement": {
    "location": {
      "latitude": 30.26605500117993,
      "longitude": -97.75039999907479
    },
    "heading": 0,
    "speedMetersPerSecond": 0,
    "timestamp": "2024-03-28T13:13:15.556Z"
  }
}
{
  "vehicleMovement": {
    "location": {
      "latitude": 30.26605500117993,
      "longitude": -97.75039999907479
    },
    "heading": 0,
    "speedMetersPerSecond": 0,
    "timestamp": "2024-03-28T13:13:21.820Z"
  }
}

The response is a stream of vehicle movement objects, with location, heading, speed and timestamp information, providing live movement updates as they happen.

Getting Started

Contents

Getting Started#

Requirements#

Setup Credentials#

Structure of Basic API Call#

List Fleets#

List Vehicles#

Get Vehicle#

Stream Vehicle Telemetry Movement#