Sign in

v1

latestOpenAPI 3.0.12026-07-2433136135.1 KB
Ranking Reports

Ranking Index - Closely Ranked

This endpoint generates a ranked list of properties relative to a benchmark based on the one of following segments:<br/> <ul> <li>Within Chain - Provides other closely ranked venues within the same chain.</li> <li>category - provides the <glossary:Ranking> within the venue’s category</li> <li>Within Category/Group Category - Provides other closely ranked venues within the same category/group category.</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> </br> 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 Ranking benchmarked against POIs from within a 5 / 10 / 15 / 30 / 50 miles radius.</li> </ul> You may define the total number of results to display (up to 1000), whereby half of the results will reflect properties ranked higher than the requested property and half of the results will reflects the ones ranked lower. For example: if the requested POI is ranked 550 and <b>results amount</b> value is set to 200 - then the response includes all properties ranked between 450 and 649 within the indexed list.</br> The endpoint supports pre-defined time buckets and ranking regions.</br><br/> &#x23F1; <strong>Average measured processing time: 3.98 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: Flagged entities will not be taken into consideration in the resulting report.
post/v1/reports/ranking-index/closely-ranked

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
resultsAmountinteger

The amount of results returned in the response - half of the results are the properties which are ranked higher than the requested property, and half are ranked lower. By default 100 results will be retrieved.

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"
}