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

GET
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)
name required
string
Display name (1–256 chars)
external_id
string
Your own ID for cross-referencing (max 256 chars)
status
string
Initial status label (max 64 chars). Default active.
lat
number
Initial latitude (−90 to 90)
lng
number
Initial longitude (−180 to 180)
callback_url
string (URL)
Webhook URL for geofence events (max 2048 chars)
metadata
object
Arbitrary key-value metadata
Error responses
400 Invalid body (validation error)
401 Unauthorized
402 Insufficient Tokens
403 Forbidden
429 Rate Limited

List Entities

GET
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.
cursor
string
Pagination cursor from previous response
Error responses
401 Unauthorized
402 Insufficient Tokens
429 Rate Limited

Nearby Search

GET
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)
lng required
number
Center longitude (−180 to 180)
radius_km
number
Search radius in km (0.1–100). Default 10.
type
string
Filter by entity type
status
string
Filter by status
limit
integer
Max results (1–100). Default 20.
Error responses
400 Invalid coordinates or radius
401 Unauthorized
402 Insufficient Tokens
429 Rate Limited

Get Entity

GET
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

GET
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)
type
string
Updated entity type (1–64 chars)
external_id
string
Updated external ID (max 256 chars)
status
string
Updated status (max 64 chars)
lat
number
Updated latitude (−90 to 90)
lng
number
Updated longitude (−180 to 180)
callback_url
string (URL)
Updated webhook URL (max 2048 chars)
metadata
object
Updated key-value metadata (replaces existing)
Error responses
400 Invalid body (validation error)
401 Unauthorized
402 Insufficient Tokens
403 Forbidden
404 Not Found
429 Rate Limited

Deactivate Entity

GET
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
403 Forbidden
404 Not Found
429 Rate Limited