Skip to main content

Geo API — overview

The Geo API handles everything spatial: turning coordinates into addresses, and managing zones (geofences) that you can use to trigger alerts when vehicles enter or leave defined areas.

This guide is an orientation

The Geo API in the Reference has every endpoint in this collection — reverse-geolocation, zone categories, and the three zone shapes — with parameters, payload schemas, and code samples. Browse it for anything not covered here.

What it contains (client-facing)​

CapabilityWhat it does
Reverse geolocationlat, lng → human-readable address
Zone Categories (Client)Group your zones into named categories (e.g. "Depots", "Restricted")
Zones (Client)The geofences themselves — circular, rectangular, or polygonal

Each client has their own zones and zone categories. The "Global" variants of these endpoints are admin/staff-only and not visible to clients.

Zones — three shapes​

You can create geofences in three shapes. Pick the one that matches what you're fencing:

  • Circular — a centre lat/lng + a radius. Simplest. Good for "around a depot."
  • Rectangular — two opposite corners. Good for rough quadrants.
  • Polygonal — an arbitrary list of lat/lng points. Use when the shape matters (a winding warehouse perimeter, a city border).

Try it​

# Turn coordinates into an address
curl "https://www.acmdestiny.net/api/v1/geo/reverse?lat=-26.10&lng=28.05" \
  -H "Authorization: bearer YOUR_TOKEN"

# List your zone categories
curl https://www.acmdestiny.net/api/v1/geo/zone-categories/client \
  -H "Authorization: bearer YOUR_TOKEN"

# List your zones
curl https://www.acmdestiny.net/api/v1/geo/zones/client \
  -H "Authorization: bearer YOUR_TOKEN"

(The exact paths are listed in the API Reference under Geo API → Reverse Geolocation, Zone Categories (Client), Zones (Client). The reference is the source of truth for parameters and the request body shapes for creating zones.)

How zones connect to alerts​

Creating a zone is just a definition. To get alerted when a vehicle enters or leaves a zone, you use Vehicle Safe Zones (or Unit Safe Zones) in the HTTP API to attach the zone to the vehicle — that wires up the alert behaviour.

When to use a different collection​

  • Where is a specific vehicle right now? → GET /vehicles/{id}/telemetry in the HTTP API.
  • Was this vehicle inside zone X last Tuesday? → History Query API — query past positions and check against the zone yourself.
  • Stream zone enter/leave events live → Streaming (SSE).