Zones/Locations

TerraGo-managed zones/locations — vehicles (mobile zones/locations) and fixed access points such as school gates. List zones/locations, create a new zone/location (a FIXED zone/location auto-provisions an NFC tag), and update zone/location name/type/metadata. TerraGo caches zones/locations but the registry is authoritative.

4 endpoint(s)

GET List {{url}}/utility/zones ▸

List zones/locations (vehicles / pickup areas) for the organisation. Like Tags, this is read directly from TerraGo's registry, re-paginated so the links point back at TerraGo.

Query Parameters

showonlymain (boolean, optional): Return only main zones/locations.
zone_id (string, optional): Filter by a main zone/location id.
status (string, optional), zone_type (string, optional), tags (optional): Additional the registry filters.
search (string, optional): Text search.
per_page (integer, optional, default 10, max 20), page (integer, optional).

Response

Paginated collection of zones/locations (ZoneResource).

Notes

Depends on the registry; returns a warning if the registry call fails.
Requires a bearer token (auth:api).

Auth

Bearer token

Used On

Zones/Locations Dashboard Trip Monitoring Fleet Management Route Management Staff Profile

Request Body

{
    // "search":  "Terra Hq",
    "show_only_main": false,  
    "zone_type": "Mobile", // Fixed for fixed zone
    "per_page": 10,
    "page": 1
}

Sample Response (200 OK)

{
    "data": [
        {
            "id": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
            "name": "Terra Hq",
            "zone_type": null,
            "description": "nnn",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": [],
            "metadata": {
                "Age": "12"
            }
        },
        {
            "id": "69a977c0-69f0-461e-b09d-b098a2cf412d",
            "name": "WS3 Main Gate",
            "zone_type": null,
            "description": "Main Gate Access",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": []
        },
        {
            "id": "10a7b5f5-6fef-4b60-a265-000cb9c862d8",
            "name": "WS3 Dining Hall",
            "zone_type": null,
            "description": "Dining hall access",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": []
        },
        {
            "id": "ffda0655-6d6b-4341-b666-1e3429066e27",
            "name": "Park View Room 101",
            "zone_type": null,
            "description": "Notes",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": []
        },
        {
            "id": "e6a21cd2-d7cc-4671-b20b-0020fdcf5847",
            "name": "SITE A",
            "zone_type": null,
            "description": "sdsaa",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": []
        },
        {
            "id": "0d8a8f14-6e16-48bc-9485-facff301725b",
            "name": "Backstage",
            "zone_type": null,
            "description": "Backstage",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": []
        },
        {
            "id": "dfa84171-df4f-43ab-89cb-5d86ab55f6ab",
            "name": "Main Entrance",
            "zone_type": null,
            "description": "Main Entrance",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [],
            "whitelist_tags": []
        },
        {
            "id": "33029d12-b2db-4def-acdf-ea75cb84427e",
            "name": "SAFARI-WALK",
            "zone_type": null,
            "description": "ZONE ENTRY",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [
                {
                    "id": "2bf8b100-e0df-41e0-96c6-453d7c0f079e",
                    "name": "Zephr Dyer",
                    "description": "Quis porro tempore",
                    "entity": "zone",
                    "color_code": null
                }
            ],
            "whitelist_tags": []
        },
        {
            "id": "fb3d18ca-1688-46d6-8efe-bafbf02a8335",
            "name": "KBJ 101D",
            "zone_type": null,
            "description": "Ruaka Ndenderu Route",
            "main_zone": null,
            "is_sub_zone": 0,
            "tags": [
                {
                    "id": "2bf8b100-e0df-41e0-96c6-453d7c0f079e",
                    "name": "Zephr Dyer",
                    "description": "Quis porro tempore",
                    "entity": "zone",
                    "color_code": null
                }
            ],
            "whitelist_tags": [
                {
                    "id": "7b18d5ea-346e-4b5c-8936-4a1f4cdaabb0",
                    "name": "Universal Tag",
                    "description": "This is a Universal Tag",
                    "entity": "universal",
                    "color_code": "#34C759",
                    "whitelisted_under": "account"
                },
                {
                    "id": "7b18d5ea-346e-4b5c-8936-4a1f4cdaabb0",
                    "name": "Universal Tag",
                    "description": "This is a Universal Tag",
                    "entity": "universal",
                    "color_code": "#34C759",
                    "whitelisted_under": "dependant"
                },
                {
                    "id": "5f9cbe4d-8274-47f4-84cc-8ba83f247c1e",
                    "name": "WS3",
                    "description": "World Service #3 schools",
                    "entity": "dependant",
                    "color_code": "#FF9500",
                    "whitelisted_under": "dependant"
                },
                {
                    "id": "dced7eab-c41a-4053-a38f-60b52b859f04",
                    "name": "Wasee",
                    "description": "Wathee",
                    "entity": "account",
                    "color_code": "#FF9500",
                    "whitelisted_under": "account"
                }
            ]
        }
    ],
    "links": {
        "first": "http://localhost:8001/api/zones?page=1",
        "last": "http://localhost:8001/api/zones?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/zones?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "page": null,
                "active": false
            }
        ],
        "path": "http://localhost:8001/api/zones",
        "per_page": 10,
        "to": 9,
        "total": 9
    },
    "status": 200,
    "message": "Zones Retrieved Successfully"
}

PUT Update Zone/Location Metadata {{url}}/utility/zones/update ▸

Update a zone/location's name, description, type, or custom metadata. Changes are pushed to TerraGo's zone/location and tag registry and propagated to every staff member currently assigned to this zone/location (their cached assigned_zone metadata is refreshed too).

Request Body

id (string UUID, required): The the registry zone/location UUID to update.
name (string, required)
description (string, optional)
zone_type (string, required): FIXED (a stationary gate/point, e.g. a school gate) or MOBILE (a vehicle).
metadata (object, optional): Arbitrary custom key/value fields (e.g. vehicle capacity, fuel consumption rating) — merged into the zone/location and into every assigned staff member's profile.

Notes

"Zones/Locations" here are TerraGo-managed entities representing either a fixed access point or a mobile vehicle; TerraGo caches and displays them but the registry is the source of truth.

Response

The updated zone (data); the change is pushed to WaaS and to every staff member assigned to the zone.

Auth

Bearer token

Used On

Zones/Locations Dashboard

Request Body

{
    "id": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",  // Record UUID
    "name": "Terra Hq",  // Human-readable name / label
    "zone_type": null,  // FIXED (a gate/point) or MOBILE (a vehicle)
    "description": "nnn",  // Optional free-text description
    "main_zone": null,  // true if this is a top-level (parent) zone
    "is_sub_zone": 0,  // true if this zone is nested under a main zone
    "tags": [],  // List of tag UUIDs to filter by
    "whitelist_tags": [],  // Tags allowed (whitelisted) for this zone
    "metadata": []  // Extra custom key/value fields
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
        "name": "Terra Hq",
        "zone_type": null,
        "description": "nnn",
        "main_zone": null,
        "is_sub_zone": 0,
        "tags": [],
        "whitelist_tags": [],
        "metadata": [],
        "assignees": [
            {
                "id": "c011772f-7677-4b6b-bd6e-21a2ba6d1841",
                "first_name": "Francis",
                "last_name": "Chege",
                "staff_type": null
            }
        ]
    },
    "message": "Zone MetaData Updated Successfully"
}

POST Create Zone/Location {{url}}/utility/zones/add ▸

Create a new zone/location (a vehicle or a fixed access point such as a gate) under your school/institution in TerraGo's zone/location and tag registry.

Request Body

name (string, required)
description (string, optional)
zone_type (string, required): FIXED or MOBILE.
metadata (object, optional): Custom fields (e.g. vehicle capacity for a MOBILE zone/location).

Side Effects

If zone_type is FIXED, an NFC tag is automatically created and whitelisted for the zone/location (named "{institution} {zone/location name}"), enabling tap detection at that point.
The new zone/location is created as a sub-zone/location of your institution's main zone/location, active, with a 9-year expiry.

Notes

The zone/location is attributed to your school automatically: Administrative Staff create zones/locations for themselves, Staff create zones/locations under their supervisor's school.

Response

The created zone (data); for a FIXED zone an NFC tag is auto-created and whitelisted.

Auth

Bearer token

Used On

Zones/Locations Dashboard

Request Body

{
    "name" : "The Zone Name",
    "description" : "The Zone Description",
    "zone_type" : "FIXED" //only use: FIXED,MOBILE
}

GET List Access Logs {{url}}/utility/access-logs ▸

Duplicate of AccessLogs → List (GET /utility/access-logs), surfaced here under Zones/Locations for convenience — same endpoint, filter by zoneid / zonetype to scope logs to a zone/location.

Retrieves a paginated list of access logs — student tap-in / tap-out events at zones — for auditing and monitoring. Proxied from the WaaS partner system and re-paginated to TerraGo.

Query Parameters (all optional)

status: filter by tap type — Checked In or Checked Out. Leave it out (null / empty) to return all taps.
zone_type: filter by point type — Mobile (a vehicle / bus) or Fixed (a gate / access point). Leave it out (null / empty) to return all point types.
dependant_id (string UUID): filter to one student.
parent_id (string UUID): filter to one parent's children.
zone_id (string UUID): filter to one zone / location.
tags (array of tag uuids): filter by route / zone tags.
date_range: "YYYY-MM-DD HH:mm:ss, YYYY-MM-DD HH:mm:ss" (start,end).
search: free-text (student name).
per_page (default 10, max 20), page.

Response

Paginated list of access-log entries (data) with meta pagination; each row is a student's check-in / check-out at a zone with a timestamp.

Auth

Bearer token

Used On

Live Board Zones/Locations Dashboard Trip Monitoring

Request Body

{
    // "tags": ["27ba6b10-c659-408f-beb1-dc650d5d5034", "5ac13004-3e77-4e9e-a9b8-be8080ce845e"],
    // "dependant_id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",  // filter to one student
    // "parent_id": "b3b62c15-1409-4713-81b2-d4f6744039e6",  // filter to one parent's children
    // "zone_id": "825e7402-a072-4926-9bfb-27280c2be5eb",  // filter to one zone/location
    // "date_range": "2025-04-23 14:03:21, 2025-05-23 14:03:21",
    // "status": "Checked In",  // "Checked In" or "Checked Out"; omit (null/empty) for all
    // "zone_type": "Mobile",  // "Mobile" (vehicle/bus) or "Fixed" (gate); omit (null/empty) for all
    "search":  "Lincoln Chege",  // Free-text search (student name)
    "per_page": 10,  // Page size — how many results per page
    "page": 1  // Page number (starts at 1)
}

Sample Response (200 OK)

{
    "data": [
        {
            "id": "929055eb-5e73-4563-855c-3a6b45391b07",
            "code": "B20C4A9AKDQ",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",
                "name": "Lincoln Chege",
                "metadata": {
                    "grade": "Grade 6"
                }
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": {
                "id": "b3b62c15-1409-4713-81b2-d4f6744039e6",
                "name": "Francis Chege"
            },
            "checked_in_guardian": {
                "id": "ba20fb10-c2c1-4951-9903-53c6fdbeabef",
                "name": "Peter Chege"
            },
            "checked_out_guardian": {
                "id": "ba20fb10-c2c1-4951-9903-53c6fdbeabef",
                "name": "Peter Chege"
            }
        },
        {
            "id": "4eb7d2d4-ba6b-44cb-ae93-ea0d95572346",
            "code": "B20C4A9AKDP",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",
                "name": "Lincoln Chege",
                "metadata": {
                    "grade": "Grade 6"
                }
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": {
                "id": "b3b62c15-1409-4713-81b2-d4f6744039e6",
                "name": "Francis Chege"
            },
            "checked_in_guardian": {
                "id": "ba20fb10-c2c1-4951-9903-53c6fdbeabef",
                "name": "Peter Chege"
            },
            "checked_out_guardian": {
                "id": "ba20fb10-c2c1-4951-9903-53c6fdbeabef",
                "name": "Peter Chege"
            }
        },
        {
            "id": "53ecd826-a60c-4aa4-8d15-ae46af183495",
            "code": "B20C4A9AKDO",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "7b5f4ec6-8aad-4629-85ba-192b2be6d2f2",
                "name": "Martin Nyaga",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "41932cfe-ee6d-43c5-9461-625b3f0c0d92",
            "code": "B20C4A9AKDN",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": null,
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "87fce716-9893-4ed6-a9d9-d313a8dc3536",
            "code": "B20C4A9AKDM",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "01f9a2d4-6fdb-4418-aa61-97b0d3157cd7",
                "name": "Ziham Man",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "674d9e12-a10b-4bd8-8d38-38e40d5fb2c5",
            "code": "B20C4A9AKDL",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "9357bc7d-b26b-4e28-8c75-46f8d4717c06",
                "name": "Mwinyi Mwinyi",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "9c4c1b71-68fc-4397-be69-7c5e8edcd32c",
            "code": "B20C4A9AKDK",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "01f9a2d4-6fdb-4418-aa61-97b0d3157cd7",
                "name": "Ziham Man",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "814291d5-5396-4253-b77d-a8fbcbeeaab4",
            "code": "B20C4A9AKDJ",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",
                "name": "Ben Ngovi",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "e5b761a8-dc83-4bf2-b858-36062f0ba7f4",
            "code": "B20C4A9AKDI",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "9357bc7d-b26b-4e28-8c75-46f8d4717c06",
                "name": "Mwinyi Mwinyi",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        },
        {
            "id": "187a4760-950e-4729-a21b-b34ee10e5977",
            "code": "B20C4A9AKDH",
            "zone": "SAFARI-WALK",
            "status": "Checked In",
            "checkin_at": "Thu, Apr 24, 2025 5:19 PM",
            "checkout_at": null,
            "created_at": "Thu, Apr 24, 2025 5:19 PM",
            "dependant": {
                "id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",
                "name": "Ben Ngovi",
                "metadata": null
            },
            "checked_in_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "checked_out_verified_by": {
                "id": "47886d66-99b4-4fa0-8bf9-3bac67812f58",
                "name": "Peter Chege"
            },
            "auth_by": null,
            "checked_in_guardian": null,
            "checked_out_guardian": null
        }
    ],
    "links": {
        "first": "http://localhost:8001/api/access-log?page=1",
        "last": "http://localhost:8001/api/access-log?page=689",
        "prev": null,
        "next": "http://localhost:8001/api/access-log?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 689,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": "http://localhost:8001/api/access-log?page=2",
                "label": "2",
                "page": 2,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=3",
                "label": "3",
                "page": 3,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=4",
                "label": "4",
                "page": 4,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=5",
                "label": "5",
                "page": 5,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=6",
                "label": "6",
                "page": 6,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=7",
                "label": "7",
                "page": 7,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=8",
                "label": "8",
                "page": 8,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=9",
                "label": "9",
                "page": 9,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=10",
                "label": "10",
                "page": 10,
                "active": false
            },
            {
                "url": null,
                "label": "...",
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=688",
                "label": "688",
                "page": 688,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=689",
                "label": "689",
                "page": 689,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/access-log?page=2",
                "label": "Next &raquo;",
                "page": 2,
                "active": false
            }
        ],
        "path": "http://localhost:8001/api/access-log",
        "per_page": 10,
        "to": 10,
        "total": 6887
    },
    "status": 200,
    "message": "Tags Retrieved Successfully"
}