v1

latestOpenAPI 3.0.12026-07-2433136135.1 KB
Ranking Reports

Ranking Index - Top Ranked

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/><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.

post/v1/reports/ranking-index/top-ranking

Request body

apiIdstring 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
limitinteger

Number of records to be fetched

skipinteger

Relevant for the chain scope only. Contains 0 in the first call, and the offset for pagination in next calls, default set to 0.

Example request

{
  "apiId": "venue:7d55054520e387813d764b03",
  "period": "lastWeek",
  "scope": "category",
  "metric": "visits"
}

Response

200 response

OR

Example response

{
  "totalRanked": 123,
  "rank": 65,
  "region": "state",
  "scope": "category",
  "metricType": "visits",
  "visits": 12000,
  "rankingIndexArray": [
    {
      "apiId": "venue:7d55054520e387813d764b03",
      "name": "entity name",
      "address": {
        "city": "Milpitas",
        "state": "California",
        "countryCode": "US",
        "streetName": "Ranch Dr",
        "formattedAddress": "301 Ranch Dr, Milpitas, CA, United States",
        "shortFormattedAddress": "Ranch Dr, Milpitas, CA",
        "zipCode": "95035",
        "country": "United States",
        "address": "301 Ranch Dr"
      },
      "rank": 90,
      "visits": 105463
    }
  ],
  "visitDurationSegmentation": "10MinOrLonger"
}