First Steps

Use your access token to find a vehicle, check its connection, and read its current location.

Prerequisites

Obtain an access token as shown in Authentication.

Choose a vehicle

Request the vehicles available to your integration with GET https://api.polymathrobotics.dev/v1/vehicles.

The response contains an array of vehicles in data. For this guide, select the first vehicle and keep its id for later requests.

curl

Requires curl and jq.

POLYMATH_VEHICLE_ID="$(
  curl --silent --show-error --fail-with-body \
    --url https://api.polymathrobotics.dev/v1/vehicles \
    --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
    | jq -er '.data[0].id // error("No vehicles are available")'
)"
export POLYMATH_VEHICLE_ID

Python

Requires the requests package.

import requests

headers = {
    "Authorization": f"Bearer {access_token}"
}

vehicles_response = requests.get(
    "https://api.polymathrobotics.dev/v1/vehicles",
    headers=headers,
    timeout=30,
)
vehicles_response.raise_for_status()

vehicles = vehicles_response.json()["data"]
if not vehicles:
    raise RuntimeError("No vehicles are available")

vehicle_id = vehicles[0]["id"]

Node.js

const headers = {
  Authorization: `Bearer ${accessToken}`,
};

const vehiclesResponse = await fetch(
  "https://api.polymathrobotics.dev/v1/vehicles",
  {headers},
);

if (!vehiclesResponse.ok) {
  throw new Error(
    "Vehicle request failed with status " + vehiclesResponse.status,
  );
}

const vehicles = (await vehiclesResponse.json()).data;
if (vehicles.length === 0) {
  throw new Error("No vehicles are available");
}

const vehicleId = vehicles[0].id;

Check the connection

Use GET https://polyglot.polymathrobotics.dev/api/synapse/{vehicleId}/v2/health to confirm that the vehicle is reachable:

curl

curl --silent --show-error --fail-with-body \
  --url "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/health" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"

Python

health_response = requests.get(
    f"https://polyglot.polymathrobotics.dev/api/synapse/{vehicle_id}/v2/health",
    headers=headers,
    timeout=30,
)
health_response.raise_for_status()

print(health_response.json())

Node.js

const healthResponse = await fetch(
  `https://polyglot.polymathrobotics.dev/api/synapse/${vehicleId}/v2/health`,
  {headers},
);

if (!healthResponse.ok) {
  throw new Error(
    "Health request failed with status " + healthResponse.status,
  );
}

console.log(await healthResponse.json());

Read vehicle location

The vehicle's current GPS location and bearing are available in the GET https://polyglot.polymathrobotics.dev/api/synapse/{vehicleId}/v2/polymath-feedback response at data.polymath_feedback.current_pose.pose.

curl

curl --silent --show-error --fail-with-body \
  --url "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/polymath-feedback" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
  | jq '.data.polymath_feedback.current_pose.pose'

Python

feedback_response = requests.get(
    f"https://polyglot.polymathrobotics.dev/api/synapse/{vehicle_id}/v2/polymath-feedback",
    headers=headers,
    timeout=30,
)
feedback_response.raise_for_status()

pose = feedback_response.json()["data"]["polymath_feedback"]["current_pose"]["pose"]
print(pose)

Node.js

const feedbackResponse = await fetch(
  `https://polyglot.polymathrobotics.dev/api/synapse/${vehicleId}/v2/polymath-feedback`,
  {headers},
);

if (!feedbackResponse.ok) {
  throw new Error(
    "Feedback request failed with status " + feedbackResponse.status,
  );
}

const feedback = await feedbackResponse.json();
const pose = feedback.data.polymath_feedback.current_pose.pose;
console.log(pose);

The result has this form:

{
  "position": {
    "latitude": 40.634180274928184,
    "longitude": -96.16258620804851,
    "altitude": 0
  },
  "orientation": {
    "x": 0,
    "y": 0,
    "z": 0.3013746455741215,
    "w": 0.9535058064873398
  }
}

Poll this endpoint when your application needs current vehicle state.

Next steps

Explore the API Reference for the full list of available endpoints.