Search docs ⌘K
esc
Type to search across all documentation pages
Logistics

Geo Entities

A geo entity is any trackable object — a driver, vehicle, package, or custom type. Entities hold a current position, status, and optional metadata. All routes live under /logistics/* and require a token with logistics:read or logistics:write scope.

Create Entity

POST
/logistics/geo/entities
logistics:write0.0000053 tokens

Register a trackable entity (driver, vehicle, asset, etc.).

curl
curl -X POST https://api.saasignal.saastemly.com/logistics/geo/entities \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"driver","name":"example"}'
json — 201 Created
{ "status": "ok" }
typescript
const entity = await ss.logistics.geo.create({
  type: 'driver',
  name: 'Alice',
  external_id: 'drv-001',
})
  1. Open Dashboard and select your project
  2. Go to Geo in the sidebar
  3. Click Add Entity, fill in type, name, and optional metadata
  4. Click Create
Body field
Type
Description
type required
string
Entity type label (1–64 chars, e.g. driver, vehicle)
1–64 chars
name required
string
Display name (1–256 chars)
1–256 chars
external_id
string
Your own ID for cross-referencing (max 256 chars)
max 256 chars
status
string
Initial status label (max 64 chars). Default active.
max 64 chars
lat
number
Initial latitude (−90 to 90)
range ≥-90 .. ≤90
lng
number
Initial longitude (−180 to 180)
range ≥-180 .. ≤180
callback_url
string (URL)
Webhook URL for geofence events (max 2048 chars)
metadata
object
Arbitrary key-value metadata
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

List Entities

GET
/logistics/geo/entities
logistics:read0.0000008 tokens

List all geo entities for the project.

curl
curl https://api.saasignal.saastemly.com/logistics/geo/entities \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const result = await ss.logistics.geo.list({ type: 'driver', status: 'active', limit: 50 })
  1. Open Dashboard and select your project
  2. Go to Geo to see all entities with filters for type and status
Query param
Type
Description
type
string
Filter by entity type
status
string
Filter by status
limit
integer
Results per page (1–100). Default 25.
range ≥1 .. ≤100default 25
cursor
string
Pagination cursor from previous response
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Nearby Search

GET
/logistics/geo/entities/nearby
logistics:read0.0000008 tokens

Find entities within a radius of a given point.

curl
curl https://api.saasignal.saastemly.com/logistics/geo/entities/nearby?lat=40.7128&lng=-74.0060 \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const nearby = await ss.logistics.geo.nearby({
  lat: 40.7128, lng: -74.0060,
  radius_km: 5, type: 'driver',
})
  1. Open Dashboard and select your project
  2. Go to Geo and click Nearby Search
  3. Click a point on the map or enter coordinates and radius
  4. Matching entities are highlighted on the map
Query param
Type
Description
lat required
number
Center latitude (−90 to 90)
range ≥-90 .. ≤90
lng required
number
Center longitude (−180 to 180)
range ≥-180 .. ≤180
radius_km
number
Search radius in km (0.1–100). Default 10.
range ≥0.1 .. ≤100default 10
type
string
Filter by entity type
status
string
Filter by status
limit
integer
Max results (1–100). Default 20.
range ≥1 .. ≤100default 20
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Get Entity

GET
/logistics/geo/entities/{entity_id}
logistics:read0.0000008 tokens

Retrieve a single entity with cached position.

curl
curl https://api.saasignal.saastemly.com/logistics/geo/entities/{entity_id} \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const entity = await ss.logistics.geo.get('ent_abc123')
  1. Open Dashboard and select your project
  2. Go to Geo and click on any entity to view its details, position, and metadata
Path param
Type
Description
entity_id required
string
Entity ID
Error responses
401 Unauthorized
402 Insufficient tokens
404 Not found
429 Rate limited

Update Entity

PATCH
/logistics/geo/entities/{entity_id}
logistics:write0.0000053 tokens

Update entity fields.

curl
curl -X PATCH https://api.saasignal.saastemly.com/logistics/geo/entities/{entity_id} \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.logistics.geo.update('ent_abc123', { status: 'inactive' })
  1. Open Dashboard and select your project
  2. Go to Geo and click on an entity
  3. Edit the fields you want to change and click Save
Path param
Type
Description
entity_id required
string
Entity ID
Body field
Type
Description
name
string
Updated display name (1–256 chars)
1–256 chars
type
string
Updated entity type (1–64 chars)
1–64 chars
external_id
string
Updated external ID (max 256 chars)
max 256 chars
status
string
Updated status (max 64 chars)
max 64 chars
lat
number
Updated latitude (−90 to 90)
range ≥-90 .. ≤90
lng
number
Updated longitude (−180 to 180)
range ≥-180 .. ≤180
callback_url
string (URL)
Updated webhook URL (max 2048 chars)
metadata
object
Updated key-value metadata (replaces existing)
Error responses
401 Unauthorized
402 Insufficient tokens
404 Not found
429 Rate limited

Deactivate Entity

DELETE
/logistics/geo/entities/{entity_id}
logistics:admin

Soft-delete an entity by setting status to deactivated.

curl
curl -X DELETE https://api.saasignal.saastemly.com/logistics/geo/entities/{entity_id} \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
await ss.logistics.geo.deactivate('ent_abc123')
  1. Open Dashboard and select your project
  2. Go to Geo and click on the entity
  3. Click Deactivate to mark the entity as inactive
Path param
Type
Description
entity_id required
string
Entity ID to deactivate
Error responses
401 Unauthorized
402 Insufficient tokens
404 Not found
429 Rate limited