API Reference
WS metric/area/dwell-per-location-entrant

Area dwell per visitor

Total area dwell time divided by location entrants — average time each visitor spends in this zone.

Returns the total dwell time accumulated in an area divided by the number of location entrants over the same period — i.e. how much time, on average, each visitor to the location spent in this zone. Useful for comparing zone stickiness across locations or weeks with different overall traffic.

Distinct from Area average dwell, which divides by area entries. This page’s denominator counts every visitor — including those who never set foot in the zone — so values are typically lower.

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" — 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-adpe-001",
    "route": "area/dwell-per-location-entrant",
    "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-adpe-001|0|0|{
  "segments": [
    { "index": "2024-04-01T00:00:00.000", "location": "64a1b2c3d4e5f6a7b8c9d0e3", "area_dwell_per_location_entrant": 20.9 },
    { "index": "2024-04-02T00:00:00.000", "location": "64a1b2c3d4e5f6a7b8c9d0e3", "area_dwell_per_location_entrant": 22.4 }
  ],
  "summary": [
    { "location": "64a1b2c3d4e5f6a7b8c9d0e3", "area_dwell_per_location_entrant": 21.3 }
  ],
  "meta": {
    "units": {
      "area_dwell_per_location_entrant": "seconds"
    }
  }
}

Values in seconds per location entrant.

Update frequency

Tracks the same cadence as the area dwell + entries pipeline — approximately 10 minutes.