---
title: "Ranking Index - Top Ranked"
method: POST
path: "/v1/reports/ranking-index/top-ranking"
tags: ["Ranking Reports"]
---

# Ranking Index - Top Ranked

`POST /v1/reports/ranking-index/top-ranking`

Generate a ranked list of properties relative to a benchmark based on the one of following segments:<br/> <ul> <li>Within Chain - ability to reach all chain’s venues ranked from the top most to the last using pagination.</li> <li>Within Category/Group Category - ability to fetch up to 1000 top ranked properties within the same Category/group category of the requested property.</li> </ul> Provides view by different metrics and regions.<br/> Metrics<br/> <ul> <li>Visits: shows the <<glossary:Ranking>> according to the estimated number of visits to the POI.</li> <li>Visits / Sq ft: shows the <<glossary:Ranking>> according to the estimated number of visits relative to the total square footage of a property.</li> </ul> Regions<br/> <ul> <li>nationwide: The nationwide <<glossary:Ranking>> of a POI benchmarked against POIs from the same category or chain.</li> <li>state/dma/cbsa: The ranking benchmarked against POIs from the same category or chain in the POI's state/dma/cbsa.</li> <li>Specific distance: The POI’s <<glossary:Ranking>> benchmarked against POIs from within a 5 / 10 / 15 / 30 / 50 miles radius.</li> </ul><br/><br/> &#x23F1; <strong>Average measured processing time: 2.71 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

- RankingIndexTopRankingRequest
  - `apiId` string, required — Placer API Entity Id
  - `region` '5' | '10' | '15' | '30' | '50' | 'nationwide' | 'state' | 'dma' | 'cbsa', required — Region to be set for ranking index
  - `period` 'last3Months' | 'last6Months' | 'last12Months' | 'lastWeek' | 'lastMonth' | 'lastQuarter' | 'yearToDate' | 'year2018' | 'year2019' | 'year2020' | 'year2021' | 'year2022' | 'year2023' | 'year2024' | 'year2025', nullable, required — 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
  - `limit` integer — Number of records to be fetched
  - `skip` integer — Relevant for the chain scope only. Contains 0 in the first call, and the offset for pagination in next calls, default set to 0.

## Response `200`

200 response

- union
  - RankingIndexResponse
    - `totalRanked` integer — The total number of properties within the scope and region selected, from which the <<glossary:Ranking>> will be conducted. For example: the requested property is ranked 550 out of 7500 (= total number of records) properties within the same chain(= scope) in the same state(= region).
    - `rank` integer — The rank of the requested POI
    - `region` string — The requested region
    - `scope` string — The requested scope
    - `metricType` string — The requested metric
    - `visits` number — The estimated foot traffic at the requested property per the requested parameters
    - `rankingIndexArray` object[]
      - `apiId` string — Placer API Entity Id
      - `name` string
      - `address` RankingIndexAddress
        - `city` string — Entity City
        - `state` string — Entity State
        - `countryCode` string — Entity Country Code
        - `streetName` string — Entity Street Name
        - `formattedAddress` string — Entity Address
        - `shortFormattedAddress` string — Entity Address
        - `zipCode` string — Entity Zip Code
        - `country` string — Entity Country
        - `address` string — Entity Address
      - `rank` integer
      - `visits` number
    - `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'.
  - RankingIndexError
    - `region` string — The requested region
    - `scope` string — The requested scope
    - `metricType` string — The requested metric
    - `rankError` string — The error that was occuerd while trying to get <<glossary:Ranking>> for that entity

## Other responses

- `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/versions/e317a0bbbd11/schema)