---
title: "Visit Metrics Summary Report"
method: POST
path: "/v1/reports/visit-metrics"
tags: ["Visits Reports"]
---

# Visit Metrics Summary Report

`POST /v1/reports/visit-metrics`

Retrieves visitors and visits for a given list of entities. <br/>This endpoint supports bulk requests up to 100 entities<br/><br/><strong>&#x21e1; This service supports bulk request</strong><br/> When nearbyRadius is set, a report will be generated for the first entity in the array <strong>only</strong>.<br/> <br/> &#x23F1; <strong>Average measured processing time: 10 seconds </strong><br/> For more information on request retries best practices and processing measurements you may visit <a href="https://docs.placer.ai/reference/measurements"> this</a> page<br/> <br/> &#128205; This service supports the <<glossary:Nearby Activity report>>. Once setting a value to the nearbyRadius parameter, the report will be generated based on the nearby activity logic<br/><br/>

## Request body

- VisitMetricsSummaryRequest — Retrieves visitors and visits for a given list of entities.<br/>This endpoint supports bulk requests up to 100 entities.
  - `startDate` string, date, required — Queried data start date. Format YYYY-MM-DD
  - `endDate` string, date, required — Queried data end date. Format YYYY-MM-DD
  - `apiIds` ApiId[], required
  - `includeMetadata` boolean — If the parameter is set to true, the response will also include the POI Info
  - `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:<br/> 1. The starting hour to filter the reports results from (Format HH:MM XM, for example: 08:00 am).<br/> 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 <strong>or</strong> work<br/> 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<br/>lt - less than<br/>le - less than or equal to<br/>eq - equal to<br/>ge - greater than or equal to<br/>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.</br> <strong>Note</strong>: When a value is populated for this attribute - the report will be calculated as per the <<glossary:Nearby Activity report>> logic.

## Response `200`

200 response

- BulkVisitMetricsSummary
  - `requestId` string — Request ID that can be used for tracing
  - `items` VisitMetricsSummaryResponse[]
    - `apiId` string — Placer API Entity Id
    - `data` object
      - `panelVisitors` integer — The number of unique devices used for statistical extrapolation
      - `panelVisits` integer — The number of visits observed by Placer and are used for statistical extrapolation
      - `visits` integer — Extrapolated number of visits
      - `visitors` integer — Extrapolated unique devices
      - `nearbyRadius` 100 | 250 | 500 | 750 | 1000 — The radius requested for nearby activity report generation.</br> <strong>Note</strong>: When a value is populated for this attribute - the report will be calculated as per the <<glossary:Nearby Activity report>> logic.
      - `visitDurationSegmentation` 'under10Min' | '10MinOrLonger' | 'allVisits' | 'mixedSegments', nullable — Represents the requested visit duration segmentation.<br> If the default visit duration segmentation is requested, the visitDurationSegmentation will display the actual segment.<br> In cases where the default segment was requested for a chain, in which the list of entities used different default segments for the report calculation, the visitDurationSegmentation will be set to 'mixedSegments'.
      - `metadata` BaseEntityInfo
        - `apiId` string — Placer API Entity Id
        - `name` string — Entity Name
        - `entityId` string — Entity ID
        - `entityType` 'venue' | 'complex' | 'chain' — Entity Type (i.e. venue, complex etc.)
        - `categoryInfo` CategoryInfo — Property’s categorization
          - `category` string
          - `group` string
          - `subCategory` string

## Other responses

- `202` — 202 Accepted
- `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)