How geo-position tracking works
Geo position records where an asset physically is, as latitude and longitude, historically.
Requirements
- To push positions in: Odyssey or Cosmos, and an API key with the
asset:locationscope - Roles: Owner, to create the API key
Positions are pushed in by external tracking systems through the integration API. UniAsset does not track devices itself — there is no GPS built into the product.
What a reading holds
| Field | Notes |
|---|---|
| Latitude and longitude | The coordinates |
| Accuracy | In metres |
| Source | Which system reported it — for example gps-tracker |
| Timestamp | When the position was recorded |
Readings are kept historically, so an asset accumulates a position trail rather than a single current point.
Geo position is not a Location
This is the distinction to get right.
| Geo position | Location | |
|---|---|---|
| What it is | A physical coordinate | An organizational place in your hierarchy |
| Example | 51.5072, −0.1276 | "Manchester Depot → Bay 3" |
| Set by | An external tracking system, via the API | A person, in UniAsset |
| Answers | Where is it right now? | Where does it belong? |
Sending coordinates does not change which building an asset belongs to. They are separate fields answering separate questions, and a vehicle that is out on a job has not changed depot.
Sending positions
POST /api/integrations/assets/geo-position
Requires the asset:location scope. Latitude must be between −90 and 90, longitude between −180 and 180.
Full reference: Getting started with the REST API.
Where positions appear
On the asset, and on its timeline alongside everything else that happened to it — so a position update sits in sequence with services, scans, and assignment changes.
A geo_position.updated webhook event fires when a position is updated, so your own systems can react.
Common mistakes
Expecting UniAsset to track assets on its own. It stores what a tracking system sends. The tracking is theirs.
Sending coordinates instead of setting a Location. An asset with coordinates but no Location has no place in your hierarchy, so it appears in no location report.
Sending very high-frequency updates. Every reading is stored historically. Send at a rate that is useful to look at.
Omitting accuracy. A reading with no accuracy figure cannot be judged against one that has it.
Troubleshooting
The geo-position endpoint returns 403. Either your plan does not include API access — Odyssey or above — or the key lacks the asset:location scope.
404 NOT_FOUND. The asset ID does not exist in your organization.
422 VALIDATION_ERROR. Latitude and longitude must be within range and numeric; accuracy must be non-negative.
Positions arrive but the asset's Location hasn't changed. That is correct. They are separate fields.
I can't see position history. Check the readings are actually arriving — the activity log shows every API request against your keys.
Related articles
Need Help?
If you have questions not covered in this article, our support team is here to help.
Contact Support