Sign in

v1

latestOpenAPI 3.0.12026-07-2433136135.1 KB
Ranking Reports

Ranking Metrics for a Single Property

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

post/v1/reports/ranking-overview

Request body

apiIdstring required

Placer API Entity Id

startDatestring date

The start date of the time period for which the <glossary:Ranking> will be calculated. Cannot be used along with period param

endDatestring date

The end date of the time period for which the <glossary:Ranking> will be calculated. Cannot be used along with period param

distanceMiles5 | 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

Example request

{
  "apiId": "venue:7d55054520e387813d764b03",
  "startDate": "2020-12-01",
  "endDate": "2020-12-31",
  "distanceMiles": 15,
  "period": "lastWeek",
  "scope": "category",
  "metric": "visits"
}

Response

200 response

apiIdstring

Placer API Entity Id

metricTypestring
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'.

Example response

{
  "apiId": "venue:7d55054520e387813d764b03",
  "metricType": "visits",
  "info": {
    "name": "Walmart",
    "entityId": "7d55054520e387813d764b03",
    "entityType": "venue",
    "rankedBy": "chain",
    "categoryInfo": {
      "category": "Fast Food & QSR",
      "group": "Dining",
      "subCategory": "Pizze Place"
    }
  },
  "ranking": {
    "nationwide": {
      "rank": 4,
      "percentile": 85,
      "rankedOutOf": 1850,
      "regionCode": "US"
    },
    "state": {
      "rank": 4,
      "percentile": 85,
      "rankedOutOf": 1850,
      "regionCode": "CA"
    },
    "dma": {
      "rank": 4,
      "percentile": 85,
      "rankedOutOf": 1850,
      "regionCode": "510"
    },
    "cbsa": {
      "rank": 4,
      "percentile": 85,
      "rankedOutOf": 1850,
      "regionCode": "34980"
    },
    "local": {
      "rank": 4,
      "percentile": 85,
      "rankedOutOf": 1850,
      "radiusMiles": 15
    }
  },
  "visitDurationSegmentation": "10MinOrLonger"
}