---
title: "Ranking Metrics for a Single Property"
method: POST
path: "/v1/reports/ranking-overview"
tags: ["Ranking Reports"]
---

# Ranking Metrics for a Single Property

`POST /v1/reports/ranking-overview`

This service returns the specific entity <<glossary:Ranking>> within a selected scope :<br/> <ul> <li>Chain scope - compares the entity <<glossary:Ranking>> vs all other chain’s entities</li> <li>Group category scope - compares the entity <<glossary:Ranking>> vs all venues under the selected group category (Apparel, Leisure, …).</li> <li>Category scope - compares the entity <<glossary:Ranking>> vs all venues under the selected category (Regional Mall, Industrial, …).</li> </ul> </br> The endpoint supports the option to have a custom date range (as well as pre-defined time buckets) and <<glossary:Ranking>> within a local area ( 5,10,15 miles). <br/> &#x23F1; <strong>Average measured processing time: 8.57 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/>
NOTE: <<glossary:Flagged entities>> will not be taken into consideration in the resulting report.

## Request body

- RankingRequestSingular — The endpoint return the nationwide, state, CBSA, DMA and the local distance <<glossary:Ranking>> as selected in the query params.
  - `apiId` string, required — Placer API Entity Id
  - `startDate` string, date — The start date of the time period for which the <<glossary:Ranking>> will be calculated. Cannot be used along with period param
  - `endDate` string, date — The end date of the time period for which the <<glossary:Ranking>> will be calculated. Cannot be used along with period param
  - `distanceMiles` 5 | 10 | 15 | 30 | 50
  - `period` 'last3Months' | 'last6Months' | 'last12Months' | 'lastWeek' | 'lastMonth' | 'lastQuarter' | 'yearToDate' | 'year2018' | 'year2019' | 'year2020' | 'year2021' | 'year2022' | 'year2023' | 'year2024' | 'year2025', nullable — The time period for which the <<glossary:Ranking>> will be calculated. Cannot be used along with startDate and endDate
  - `scope` 'chain' | 'category' | 'groupCategory', required
  - `metric` 'visitsPerSqft' | 'visits', required

## Response `200`

200 response

- RankingResponseSingular
  - `apiId` string — Placer API Entity Id
  - `metricType` string
  - `info` RankingEntityInfo
    - `name` string — Entity name
    - `entityId` string — Entity ID
    - `entityType` 'venue' | 'complex' | 'chain' — Entity Type (i.e. venue, complex etc.)
    - `flagged` boolean — Flagging status for entity
    - `rankedBy` string — the scope which the <<glossary:Ranking>> has been ranked by
    - `categoryInfo` CategoryInfo — Property’s categorization
      - `category` string
      - `group` string
      - `subCategory` string
    - `parentChain` string — The name of the chain that entity belongs to
  - `ranking` union
    - RankingMetricsWithLocal — <<glossary:Ranking>> info for a property
      - `nationwide` RankingRegionObjectNationwide
        - `rank` integer
        - `percentile` integer
        - `rankedOutOf` integer
        - `regionCode` string
      - `state` RankingRegionObjectState
        - `rank` integer
        - `percentile` integer
        - `rankedOutOf` integer
        - `regionCode` string
      - `dma` RankingRegionObjectDma
        - `rank` integer
        - `percentile` integer
        - `rankedOutOf` integer
        - `regionCode` string
      - `cbsa` RankingRegionObjectCbsa
        - `rank` integer
        - `percentile` integer
        - `rankedOutOf` integer
        - `regionCode` string
      - `local` RankingRegionObjectLocal
        - `rank` integer
        - `percentile` integer
        - `rankedOutOf` integer
        - `radiusMiles` integer
    - object
      - `rankError` string — The error that was occuerd while trying to get <<glossary:Ranking>> for that entity
  - `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'.

## 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)