Core concepts
An overview of our platform entities
Every API call references these entities, from your organization down to a device and its telemetry.
A related, deeper topic (how you define device types and the data they produce) has its own doc: Data model. This page covers the "live" entities; the ontology covers the schema that describes them.
Overview
Everything nests under your organization, which holds:
- Sites: physical locations (a kind of "Place"), each with internal levels.
- Fleets: logical groups of Things (the other kind of "Place"), such as vehicles.
- Integrations: connections to external systems that feed your Things.
A Thing (a device or asset) lives in a Site or Fleet. Each Thing is typed by a Thing Type Definition, and it emits telemetry: timestamped metric readings.
Organization
An Organization is your account context and the hard isolation boundary. Your credentials scope you to one organization, and you can only ever see resources within it. Organizations can be arranged in a hierarchy (a parent org with child orgs), which mirrors real customer structures.
Everything else (Sites, Fleets, Things, Integrations, type definitions) belongs to an organization. You rarely pass the org id explicitly: it's derived from your API key or token.
Behind the scenes there's also a Tenant above the organization (the top-level account/region container). As an integrator you mostly operate at the organization level; tenancy is the platform's outer isolation layer.
Places
A Place is a container that Things belong to. There are two kinds:
Site
A physical location: a depot, charging hub, or building. A Site has internal structure (levels and level groups, e.g. floors, zones, or bays), and Things can be installed at a specific level. A Site has coordinates and an address.
Fleet
A logical grouping of Things, most naturally a set of vehicles. Unlike a Site, a Fleet isn't tied to one physical location. It's a grouping over a set of devices, and it can span multiple Sites.
Why "Place" matters in the API: many endpoints are addressed as
…/{placeType}/{placeId}/…, whereplaceTypeissiteorfleet. A Thing always belongs to a Place, and you'll reference that Place when ingesting and querying its data.
Thing
A Thing is the universal model for a device or asset: a battery, swap station, charger, meter, inverter, solar array, or vehicle. Almost everything in the platform exists to describe Things, route their data, or act on it.
A Thing carries several kinds of information:
Identity
| Field | Meaning |
|---|---|
thingId | Globally unique id (<thingId>). |
thingName | Friendly name. |
thingType | The device category (e.g. Battery, SwapStation). |
thingDescription, address | Optional human context. |
Hardware
| Field | Meaning |
|---|---|
manufacturer, model | Hardware identity (default to UNKNOWN). |
thingManufacturerId | The device's id in the manufacturer's own system. |
Placement
| Field | Meaning |
|---|---|
placeType, placeId | Which Place (Site or Fleet) the Thing belongs to. |
levelId | Which level of a Site it's installed at (optional). |
latitude, longitude, altitude | Physical location. |
Configuration & metadata
| Field | Meaning |
|---|---|
properties | Static, pre-defined attributes (e.g. a battery's capacity). Validated against the Thing's type definition. |
attributes | Arbitrary free-form key/value metadata. |
isSimulated | Whether the Thing is real or part of a simulation. |
integrationIds | Which integrations feed this Thing. |
Type linkage
| Field | Meaning |
|---|---|
thingTypeDefIndexId | The stable id of the Thing's type (tdefi_…). |
thingTypeDefId | The specific version of that type definition the Thing follows. This determines which metric set applies to it. |
The type linkage is the bridge to the next doc: a Thing's Thing Type Definition is what tells the platform which metrics it's allowed to report and which properties it can carry. See Data model.
Device categories
Common Thing categories you'll encounter: Battery, SwapStation, Charger, Meter, Inverter, and Solar. These are broad categories; the precise contract for each kind of device (its exact metrics and properties) comes from its Thing Type Definition, which you define and version yourself.
Telemetry
The measurements a Thing reports are time-series:
- A data point is a single reading: a metric (by id/name), a value, and a unit.
For example
{ "type": "soc", "value": 87, "unit": "%" }. - Readings are grouped into timestamped frames and sent in via the Aerovy Platform API.
- Each metric corresponds to a Metric Definition in your ontology: that's how a raw number gains meaning (e.g. "State of Charge, 87%").
How to send and read these is covered in Ingesting data and Querying data.
Integrations
An Integration is a configured connection to an external system (Geotab, Zubie, UtilityAPI, and others) that feeds data into your Things (or sends notifications out). Configure an Integration once and the platform maps external devices onto your Things, so telemetry arrives without you POSTing it yourself.
Other terms
| Term | One-liner |
|---|---|
| Level / Level Group | The internal structure of a Site: floors, zones, bays. |
| Monitor | A rule that watches metrics and raises alerts when a condition is met. |
| Metric / Metric Definition | A measured quantity and its schema (see the Data model doc). |
| Transaction | A business event: payment, battery-swap reservation, control action, invoice. |
| API Key | A credential for app-to-app access (see API fundamentals). |