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 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 (fleet_state_151.proto and related files).

  • Common types used across Fleet API services.

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

For later usage, unzip the archive:

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

Setup Credentials#

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

Note

Evaluation Credentials

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

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. 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. For convenience, set it as an environment variable:

export ACCESS_TOKEN=<ACCESS_TOKEN>

Note

Authentication Problems

  • A 401 error usually indicates expired or invalid credentials. Retry the Authentication steps. If the problem persists, contact support.

  • A 464 error indicates that HTTP/2 was not used. The authentication endpoint is only accessible via HTTP/2.

Structure of Basic API Call#

When using grpcurl, set the following options:

  1. Provide the Bearer token for authorization:
    -H "authorization: Bearer $ACCESS_TOKEN"

  2. Provide the paths to the protobuf definitions:
    -import-path <PATH_TO_FLEET_API_PROTOS>

  3. Provide the JSON formatted request data:
    -d '<JSON_FORMATTED_REQUEST>'

  4. State the protobuf source file for the corresponding gRPC service:

  5. Use -emit-defaults to display default values in 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:

grpcurl  -import-path ./fleet_api/  -proto fleet_state_151.proto  describe

List Fleets#

Users of MOIA’s Fleet API can have access to zero or more Fleets. To query all Fleets available to a user:

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.v1beta5.FleetStateService/ListFleets

Example output:

{
  "fleets": [
    {
      "id": "8a595a62-9058-4b94-ae70-e29f51df9eec",
      "description": "ExampleFleet",
      "operationalAreaId": "8a595a62-9058-4b94-ae70-e29f51df9eec"
    }
  ]
}

From the list, select a Fleet ID to use in further requests.

List Vehicles#

To retrieve info on all Vehicles in a Fleet, provide the fleet_id from 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.v1beta5.FleetStateService/ListVehicles

Example output:

{
  "vehicles": [
    {
      "id": "f30c6fcf-28b5-4788-9265-a0a4a2b4a3b9",
      "vin": "WVWZZZ9G38J6MKP6K",
      "licensePlate": "HH-MO42",
      "label": "42",
      "capacity": {
        "capacityDefinitionId": "static",
        "types": [
          { "key": "seat", "count": 4 },
          { "key": "child_seat", "count": 1 },
          { "key": "booster_seat", "count": 1 },
          { "key": "wheelchair_space" }
        ],
        "convertibleTypes": [
          { "key": "convertible_child_seat" }
        ]
      },
      "telemetry": {
        "location": {
          "latitude": 53.551484,
          "longitude": 9.985906
        },
        "heading": 354.97
      },
      "configuration": {
        "selfDriving": true
      },
      "mission": {
        "id": "ffbda218-e230-3fc8-8cd1-b94ab9e93b3e",
        "waypoints": []
      },
      "status": {
        "readyForNewRides": false,
        "online": false
      }
    }
  ]
}

This request returns semantic information per Vehicle, including ID, VIN, license plate, label, capacity, telemetry, mission, and status.

Pagination is supported. If a nextPageToken is returned, use it to request the next page. See Pagination.

Get Vehicle#

To retrieve information for a single Vehicle, provide its vehicle_id:

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

Example output:

{
  "vehicle": {
    "id": "819f0cda-62dd-4251-9efd-9c4294b4f42d",
    "vin": "WVWZZZNP9ANXCEWD2",
    "licensePlate": "AUS-430",
    "label": "430",
    "capacity": {
      "capacityDefinitionId": "static",
      "types": [
        { "key": "seat", "count": 4 },
        { "key": "child_seat", "count": 1 },
        { "key": "booster_seat", "count": 1 },
        { "key": "wheelchair_space", "count": 0 }
      ],
      "convertibleTypes": [
        { "key": "convertible_child_seat", "count": 0 }
      ]
    },
    "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 detailed information on the specific Vehicle.

Stream Vehicle Telemetry Movement#

Vehicles can stream continuous updates on their movement via non-durable streams.

Provide a vehicle_id to subscribe to live updates. Vehicles only emit updates if they are online.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto -emit-defaults \
    -d "{ \"vehicle_id\": \"$VEHICLE_ID\",\"fleet_id\": \"$FLEET_ID\" }" \
    -max-time 30 \
    fleet-api.trip.int.moia-group.io:443 moia.fleet.state.v1beta5.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, providing live updates with location, heading, speed, and timestamp information.

Contents