API Reference
WS metric/area/data

Area average dwell

Mean dwell time per area entry — how long each visit to the zone lasts on average.

Returns the mean dwell time per area entry — total dwell divided by total entries — i.e. how long, on average, a single visit to the zone lasts. Use it to compare engagement across zones independently of footfall.

Three values share this route (metric/area/data) — total entries, total dwell, and average dwell. Each page focuses on one field; request all three at once by including them in facets.

Body parameters

FieldTypeRequiredDescription
startstring (ISO 8601)yesInclusive start timestamp with timezone
endstring (ISO 8601)yesInclusive end timestamp with timezone
entitiesstring[]yesArray of location, organisation, or recording IDs (matching entityType)
entityType"location" | "organisation"yesAggregation level
areaType"taxonomy" | "location-dwell"yesRequired by all Area routes
taxonomystring[]conditionalRequired when areaType: "taxonomy". Zone path strings, e.g. ["Service:Fitting Rooms"] — see how taxonomies work
facetsstring[]yesWhat to include: segments, summary, aggregates, thumbnails, thumbnails-with-statelems
aggregationPeriodstringyesTime granularity — see aggregation period options
breakdownByDimensionsstring[]noSplit data by: entity, taxonomy, age, gender, role
rolesstring[]conditionalRequired when breakdownByDimensions includes role
gendersstring[]conditionalRequired when breakdownByDimensions includes gender
agesstring[]conditionalRequired when breakdownByDimensions includes age
insideRecordingTimesbooleannotrue to restrict to opening hours only. Default false

Example request

{
  "action": "metric",
  "data": {
    "id": "req-aad-001",
    "route": "area/data",
    "body": {
      "start": "2024-04-01T00:00:00.000Z",
      "end": "2024-04-07T23:59:59.000Z",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "areaType": "taxonomy",
      "taxonomy": ["Service:Fitting Rooms"],
      "facets": ["segments", "summary"],
      "aggregationPeriod": "day"
    }
  }
}

Example response

req-aad-001|0|0|{
  "segments": [
    { "index": "2024-04-01T00:00:00.000", "location": "64a1b2c3d4e5f6a7b8c9d0e3", "area_average_dwell_time": 146 },
    { "index": "2024-04-02T00:00:00.000", "location": "64a1b2c3d4e5f6a7b8c9d0e3", "area_average_dwell_time": 152 }
  ],
  "summary": [
    { "location": "64a1b2c3d4e5f6a7b8c9d0e3", "area_average_dwell_time": 146 }
  ],
  "meta": {
    "units": {
      "area_average_dwell_time": "seconds"
    }
  }
}

Values are in seconds per area entry.

Update frequency

Refreshes approximately every 10 minutes.