TerraGo API

Routes

Named routes and their ordered stops, each tied to a the registry zone/location and tag. Create and update routes and stops, view a route with its stops, and save the per-trip-planner student boarding/alighting order that drives the on-vehicle roster.

8 endpoint(s)
GET List Routes {{url}}/routes ▸

Retrieve a paginated list of transport routes (a route is a defined path with ordered stops that a vehicle follows, e.g. "Route A - Westlands").

Query Parameters

  • per_page (integer, optional, default 10, max 20)
  • status (string, optional): ACTIVE, INACTIVE, or N/A.
  • waaszoneuuid (string UUID, optional): Filter by the vehicle/zone/location mapped to the route.
  • tags (array, optional): Filter by route the registry tag UUIDs.
  • search (string, optional): Matches route name, description, or zone/location name.

Response

Each route includes its nested route_stops.

Auth
Bearer token
Used On
Route Management
Request Body
{
    "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
    // "search": "Terra Hq",
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "1474a1f5-e969-4fa1-97d4-d110ba99c5c8",
            "name": "Waiyaki Way",
            "description": "Students along Waiyaki way",
            "waas_zone_name": "KPM 321",
            "waas_zone_uuid": "825e7402-a072-4926-9bfb-27280c2be5eb",
            "waas_tag_uuid": "762aa069-510e-4732-8099-95893d5d51c9",
            "est_duration": "45",
            "status": "Active",
            "route_stops": [
                {
                    "id": "05e94a3d-caa7-4c2a-95be-1bed00f38866",
                    "name": "Westlands",
                    "description": null,
                    "latitude": null,
                    "longitude": null,
                    "status": "Active"
                },
                {
                    "id": "8f47a8d5-c375-4b80-aab9-055f68c7d09f",
                    "name": "Kangemi",
                    "description": null,
                    "latitude": null,
                    "longitude": null,
                    "status": "Active"
                },
                {
                    "id": "167ff01b-9a5a-4663-9731-039691b6eef2",
                    "name": "Uthiru",
                    "description": null,
                    "latitude": null,
                    "longitude": null,
                    "status": "Active"
                },
                {
                    "id": "4c60da45-747d-43a3-8cc1-3cd24df391ea",
                    "name": "Kinoo",
                    "description": null,
                    "latitude": null,
                    "longitude": null,
                    "status": "Active"
                }
            ]
        },
        {
            "id": "0b8e5bd3-a33c-4653-8b76-6679a0d04c33",
            "name": "John Carter yrw",
            "description": "dsgjhsjhjhsjh",
            "waas_zone_name": "KPM 321",
            "waas_zone_uuid": "825e7402-a072-4926-9bfb-27280c2be5eb",
            "waas_tag_uuid": "b488151d-8349-4257-88fd-3899b2151265",
            "est_duration": "45",
            "status": "Active",
            "route_stops": []
        }
    ],
    "links": {
        "first": "https://terragostg.terrasofthq.com/api/routes?page=1",
        "last": "https://terragostg.terrasofthq.com/api/routes?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://terragostg.terrasofthq.com/api/routes?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "https://terragostg.terrasofthq.com/api/routes",
        "per_page": 10,
        "to": 2,
        "total": 2
    },
    "status": 200,
    "message": "Routes retrieved Successfully"
}
POST Create Route {{url}}/routes/add ▸

Create a new transport route. A the registry "tag" is automatically created for the route (used later for NFC-based student filtering and stop-ordering lookups).

Request Body

  • name (string, required)
  • description (string, required)
  • est_duration (integer, required, min 1): Estimated journey time, in minutes.
  • status (string, required): ACTIVE, INACTIVE, or N/A.
  • filters (object, required): Must include a "student" key with an array of tag UUIDs — controls which students are eligible on this route.
  • waaszoneuuid / waaszonename (string, optional): Vehicle/zone/location assigned to this route.
  • waaszonewhitelist_tags (array, optional): Tags pre-approved for the zone/location.
  • alert_settings (object, optional): Alert thresholds (e.g. delay threshold in minutes used by the route-ranking report).

Notes

  • This whole operation is transactional — if the registry call to register the route's tag fails, nothing is saved locally either.

Response

The created route (data) with its stops.

Auth
Bearer token
Used On
Route Management
Request Body
{
    "name": "Kiota School Rongai Route",
    "description": "Kiota School Rongai Route for students",
    "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
    "waas_zone_name": "Terra Hq",
    "est_duration": "60", //minutes
    "status": "ACTIVE", //only use: ACTIVE, INACTIVE
     "filters": {
            "account": [
                {
                    "id": "27ba6b10-c659-408f-beb1-dc650d5d5034",
                    "name": "VIP ACCESS",
                    "created_at": "2025-05-05T19:37:58.000000Z"
                },
                {
                    "id": "5ac13004-3e77-4e9e-a9b8-be8080ce845e",
                    "name": "BACKSTAGE ACCESS",
                    "created_at": "2025-05-05T19:37:46.000000Z"
                },
                {
                    "id": "84561c7c-125c-4a96-97c8-3ba7ea5ca2e1",
                    "name": "Foundation",
                    "created_at": "2025-04-03T17:17:17.000000Z"
                }
            ],
            "dependant": [
                {
                    "id": "27ba6b10-c659-408f-beb1-dc650d5d5034",
                    "name": "VIP ACCESS",
                    "created_at": "2025-05-05T19:37:58.000000Z"
                }
            ],
            "iot": [
                {
                    "id": "27ba6b10-c659-408f-beb1-dc650d5d5034",
                    "name": "VIP ACCESS",
                    "created_at": "2025-05-05T19:37:58.000000Z"
                },
                {
                    "id": "5ac13004-3e77-4e9e-a9b8-be8080ce845e",
                    "name": "BACKSTAGE ACCESS",
                    "created_at": "2025-05-05T19:37:46.000000Z"
                },
                {
                    "id": "84561c7c-125c-4a96-97c8-3ba7ea5ca2e1",
                    "name": "Foundation",
                    "created_at": "2025-04-03T17:17:17.000000Z"
                }
            ],
            "wallet": [],
            "zone": [
                {
                    "id": "861c01cb-f570-499e-94be-bbb02ed1aacd",
                    "name": "VIP ACCESS",
                    "created_at": "2025-05-05T19:38:22.000000Z"
                },
                {
                    "id": "82556e35-4593-4fba-9ba5-df73bcb27b61",
                    "name": "BACKSTAGE ACCESS",
                    "created_at": "2025-05-05T19:38:31.000000Z"
                },
                {
                    "id": "84561c7c-125c-4a96-97c8-3ba7ea5ca2e1",
                    "name": "Foundation",
                    "created_at": "2025-04-03T17:17:17.000000Z"
                }
            ]
        }
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "643ab899-5b74-4dc1-b3a0-5b512dc11336",
        "name": "Kiota School Rongai Route",
        "description": "Kiota School Rongai Route for students",
        "waas_zone_name": "Terra Hq",
        "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
        "est_duration": "60",
        "status": "Active"
    },
    "message": "Route Created Successfully"
}
PUT Update Route {{url}}/routes/update/643ab899-5b74-4dc1-b3a0-5b512dc11336 ▸

Update a route's details. If you change the assigned zone/location/vehicle, the route's the registry tag is automatically de-whitelisted from the old zone/location and whitelisted on the new one.

Path Parameters

  • id (string UUID, required): Route UUID.

Request Body

  • name (string, required)
  • description (string, optional)
  • est_duration (integer, optional, min 1)
  • status (string, required): ACTIVE, INACTIVE, or N/A.
  • waaszoneuuid / waaszonename (string, optional): Reassign the route to a different vehicle/zone/location.
  • alert_settings (object, optional)

Notes

  • Transactional — rolls back and returns a 500 if the the registry sync fails.
Auth
Bearer token
Used On
Route Management
Request Body
{
    "name": "Kiota School Rongai Route",
    "description": "Kiota School Rongai Route for students",
    "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
    "waas_zone_name": "Terra Hq",
    "est_duration": "120", //minutes
    "status": "ACTIVE" //only use: ACTIVE, INACTIVE
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "643ab899-5b74-4dc1-b3a0-5b512dc11336",
        "name": "Kiota School Rongai Route",
        "description": "Kiota School Rongai Route for students",
        "waas_zone_name": "Terra Hq",
        "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
        "est_duration": "120",
        "status": "Active"
    },
    "message": "Route Updated Successfully"
}
GET Get Route {{url}}/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336 ▸

Retrieve a single route by UUID, including its ordered route stops.

Path Parameters

  • id (string UUID, required): The route's UUID.

Response

The route (RouteResource) with its route_stops relationship loaded.

Notes

  • Returns 404 if no route matches the UUID.
  • Requires a bearer token (auth:api).
Auth
Bearer token
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "643ab899-5b74-4dc1-b3a0-5b512dc11336",
        "name": "Kiota School Rongai Route",
        "description": "Kiota School Rongai Route for students",
        "waas_zone_name": "Terra Hq",
        "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
        "est_duration": "60",
        "status": "Active"
    },
    "message": "Route Retrieved Successfully"
}
GET List Route Stops {{url}}/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336/route-stops/ ▸

List the stops (pickup/dropoff points) defined on a route.

Path Parameters

  • id (string UUID, required): Route UUID.

Query Parameters

  • per_page (integer, optional, default 10, max 20)
  • status (string, optional): ACTIVE, COMPLETED, CANCELLED, or N/A.
  • search (string, optional): Matches stop name/description.

Response

The route's ordered stops (data).

Auth
Bearer token
Request Body
{
    "search": "Your Home"  // Free-text search (name / phone / email)
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "f57786e4-5417-4757-ae41-8ebf6ae60460",
            "name": "Your Home",
            "description": "Your Home",
            "waas_zone_name": null,
            "waas_zone_uuid": null,
            "est_duration": null,
            "status": "Active"
        }
    ],
    "links": {
        "first": "http://localhost:8001/api/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336/route-stops?page=1",
        "last": "http://localhost:8001/api/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336/route-stops?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336/route-stops?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "http://localhost:8001/api/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336/route-stops",
        "per_page": 15,
        "to": 1,
        "total": 1
    },
    "status": 200,
    "message": "Route Stops Retrieved Successfully"
}
POST Create Route Stop {{url}}/routes/643ab899-5b74-4dc1-b3a0-5b512dc11336/route-stops/add ▸

Add a pickup/dropoff stop to a route.

Path Parameters

  • id (string UUID, required): Route UUID.

Request Body

  • name (string, required): Stop name/address.
  • description (string, optional)
  • latitude (number, optional, -90 to 90)
  • longitude (number, optional, -180 to 180)
  • status (string, required)

Notes

  • New stops are always created as ACTIVE regardless of the status value passed.

Response

The created route stop (data).

Auth
Bearer token
Used On
Route Management
Request Body
{
    "name": "Your Home",  // Human-readable name / label
    "description": "Your Home",  // Optional free-text description
    "status": "ACTIVE"  // Status value — one of the allowed statuses for this resource
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "f57786e4-5417-4757-ae41-8ebf6ae60460",
        "name": "Your Home",
        "description": "Your Home",
        "latitude": null,
        "longitude": null,
        "status": "Active"
    },
    "message": "Route Stop Created Successfully"
}
PUT Update Route Stop {{url}}/routes/route-stops/update/f57786e4-5417-4757-ae41-8ebf6ae60460 ▸

Update a route stop's name, location, or status.

Path Parameters

  • id (string UUID, required): Route stop UUID (note: this is the stop's own ID, not the parent route's).

Request Body (all optional)

  • name (string)
  • description (string)
  • latitude (number, -90 to 90)
  • longitude (number, -180 to 180)
  • status (string)

Response

The updated route stop (data).

Auth
Bearer token
Request Body
{
    "name": "My Home",  // Human-readable name / label
    "description": "My Home",  // Optional free-text description
    "status": "ACTIVE"  // Status value — one of the allowed statuses for this resource
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "f57786e4-5417-4757-ae41-8ebf6ae60460",
        "name": "My Home",
        "description": "My Home",
        "latitude": null,
        "longitude": null,
        "status": "Active"
    },
    "message": "Route Updated Successfully"
}
POST Save Student Boarding/Alighting Order {{url}}/routes/route-ordering/2241ff88-f590-4fb1-9b99-18ecf15cfc82 ▸

Define the pickup (boarding) and dropoff (alighting) sequence for students on a route, for a specific trip planner. This drives the driver app's "next stop" ordering and the List Students Order By Route Ordering endpoint.

Path Parameters

  • id (string UUID, required): Route UUID.

Request Body

  • tripplannerid (string UUID, required): Must reference an existing trip planner.
  • orders (array, required):
  • orders[].dependant_id (string UUID, required)
  • orders[].boarding_order (integer, required): Pickup sequence position (1, 2, 3, …).
  • orders[].alighting_order (integer, required): Dropoff sequence position.

Notes

  • This replaces the entire existing order set for this route + trip planner combination — it is not additive/mergeable.
  • Response includes a synced_count of how many order records were created.

Response

Confirmation (data): tripplannerid, routeid and syncedcount (how many students were ordered).

Auth
Bearer token
Used On
Route Profile
Request Body
{
    "orders": [  // List of {student, boarding_order, alighting_order} rows
        {
            "dependant_id": "c75f2355-2f88-40b2-916b-999744d1d1f5",  // Student UUID
            "boarding_order": 1,  // Position in the pickup order (1 = first picked up)
            "alighting_order": 1  // Position in the drop-off order (1 = first dropped)
        },
        {
            "dependant_id": "184c32e2-878d-4e89-99c3-91dda70c03e9",  // Student UUID
            "boarding_order": 2,  // Position in the pickup order (1 = first picked up)
            "alighting_order": 1  // Position in the drop-off order (1 = first dropped)
        }
    ],
    "trip_planner_id": "1742827f-ddf2-4894-ab72-60f0f93ba7ff"  // Trip planner UUID (which trip this belongs to)
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "route_id": "2241ff88-f590-4fb1-9b99-18ecf15cfc82",
        "synced_count": 2
    },
    "message": "2 dependant route order(s) synced successfully"
}