--- title: "Visits by Dwell Time Report" method: POST path: "/v1/reports/visit-metrics/dwell-time" tags: ["Visits Reports"] --- # Visits by Dwell Time Report `POST /v1/reports/visit-metrics/dwell-time` Retrieves visits for a given entity(venue/complex) broken by dwell time periods.

The response includes:
  1. Dwell time bins array: [0,5,15,30,45,60,75,90,105,120,135,150] (I.e. 5 represents 5-14 minutes, 150 represents all visits with dwell time higher than or equal to 150)
  2. Estimated foot traffic array: Indicates the total visits for the POI during the selected date range for each of the dwell time bins (correlated to the location in the dwell time bins array)
  3. Average dwell time
  4. Median dwell time

⏱ Average measured processing time: 0.77 seconds
For more information on request retries best practices and processing measurements you may visit this page

📍 This service supports the <>. Once setting a value to the nearbyRadius parameter, the report will be generated based on the nearby activity logic. ## Request body - VisitsByGranularityRequest - `startDate` string, date, required — Queried data start date. Format YYYY-MM-DD - `endDate` string, date, required — Queried data end date. Format YYYY-MM-DD - `apiId` string, required — Placer API Entity Id - `filters` VmFilterObject — Filtering options for the report results. - `audienceType` string[] — If provided - metrics will be calculated based only on the specified types of audience. - `dwellTime` object — Metrics will be calculated considering the requested dwell time range. - `operator` '<' | '>=' — Less than (<) to Greater Equal (>=) - `value` integer — The wanted dwell time - `hoursRange` object — Filter the report’s results based on visits hours range. The filter is defined by 2 strings:
1. The starting hour to filter the reports results from (Format HH:MM XM, for example: 08:00 am).
2. The end hour to filter the reports results(Format HH:MM XM, for example: 11:59 pm) . - `fromHour` string, required - `toHour` string, required - `daysOfWeek` unknown[] — Filter visit calculation based on days of the week. Results will contain only requested days. Days are represented by using numbers where Monday=1 and Sunday=7. For example: in order to retrieve weekend days use the following [ 6, 7 ]. - unknown - `distance` object — Filter visits by distance in miles from home or work
where only visits in a given radius will be used in metrics calculation. - `from` 'home' | 'work' — The origin from where the distance will be measured. - `values` object — Object representation of the distance range
lt - less than
le - less than or equal to
eq - equal to
ge - greater than or equal to
gt - greater than. - `le` number - `ge` number - `lt` number - `gt` number - `eq` number - `nearbyRadius` 100 | 250 | 500 | 750 | 1000 — The radius requested for nearby activity report generation.
Note: When a value is populated for this attribute - the report will be calculated as per the <> logic. ## Response `200` 200 response - VisitsByDwellTimeResponse - `requestId` string, required — Request ID that can be used for tracing - `data` object - `bins` integer[] — [0,5,15,30,45,60,75,90,105,120,135,150] (I.e. 5 represents 5-14 minutes, 150 represents all visits with dwell time higher than or equal to 150) - `estimatedFoottraffic` integer[] — Visits correlated with the same index in the dwell time bins array - `average` integer — The average dwell time in the POI during the requested period - `median` integer — The median dwell time in the POI during the requested period - `nearbyRadius` 100 | 250 | 500 | 750 | 1000 — The radius requested for nearby activity report generation.
Note: When a value is populated for this attribute - the report will be calculated as per the <> logic. - `filters` ResponseFilters - `audienceType` string[] — The list of audiences that is specified in the request filter. - `dwellTime` object — The dwell time filter specified in the request, in case it was utilized.
For example: “< 100” or “>= 10” - `operator` '<' | '>=' — Represents the operator used for defining the dwell time range for filtering the report data - `value` integer — Represents the number of minutes referred to when defining the dwell time range for filtering the report data - `hoursRange` object — The hours range that is specified in the request filter. - `fromHour` string — Start visits hour (Format HH:MM XM, for example: 08:00 am) - `toHour` string — End visitation hour (Format HH:MM XM, for example: 08:00 am) - `daysOfWeek` unknown[] — A list of days represented by integers (Monday=1, Sunday=7) as specified in the request filter, which was used in the report calculation. - unknown - `distance` object — The visits considered for the report calculation by distance in miles from home or work as specified in the request filter. - `from` 'home' | 'work' — The origin from where the distance will be measured. - `values` object — Object representation of the distance range
lt - less than
le - less than or equal to
eq - equal to
ge - greater than or equal to
gt - greater than. - `le` number - `ge` number - `lt` number - `gt` number - `eq` number - `visitDurationSegmentation` 'under10Min' | '10MinOrLonger' | 'allVisits' | 'mixedSegments', nullable — The default visit duration segmentation is returned when the report calculation uses the default segmentation duration. ## Other responses - `202` — 202 Accepted - `204` — 204 No matching results for the requested criteria. In case of report generation - not enough data to generate accurate results. - `207` — 207 MultiStatus - `400` — 400 Bad Request - `403` — 403 Permission Denied - `500` — 500 Internal Server Error --- [API](https://skmtc.net/placer/apis/papi.md) · [All operations](https://skmtc.net/placer/apis/papi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/placer/papi/revisions/e317a0bbbd11/schema)