--- title: "Visits by Frequency Report" method: POST path: "/v1/reports/loyalty/visits-frequency" tags: ["Loyalty Reports"] --- # Visits by Frequency Report `POST /v1/reports/loyalty/visits-frequency` This service enables you to learn about the frequency of visitations to the requested POI.
Insights are provided for all the below types of metrics, bucketed into visitations frequency bins (i.e. 1, 2, 3, …30+ visits per visitor):


📍 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 - VisitsFrequencyRequest - `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 - `filter` 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 - VisitsFrequencyResponse - `requestId` string, required — Request ID that can be used for tracing - `data` object - `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 - `avgVisitsPerCustomer` number, float — The average number of visits for per visitor to the POI - `medianVisitsPerCustomer` integer — The median number of visits for per visitor to the POI - `bins` integer[] — The array represents bins for the number of visits. Each bin represents visits with frequency value between current bin value and the next. E.g. Bin #2 has a value of 2 and bin #3 has a value of 3. So in bin #2 represent the visits that occurred exactly 2 times. But bin #10 has the value of 10, and bin #11 has the value of 15. So bin #10 will include all the visits that occurred 10 times or more, but less than 15 times. The last bin is unbounded. - `visitors` integer[] — The estimated number of unique visitors to the POI correlated with the bins array. - `visitorsPercentage` number[] — The % of unique visitors that visited the POI correlated with the bins array. - `visits` integer[] — The estimated number of visits to the POI correlated with the bins array. - `visitsPercentage` number[] — The % of visits that visited the POI correlated with the bins array. - `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 - `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)