Sign in

v1

latestOpenAPI 3.0.12026-07-2433136135.1 KB
Trade Area Reports

Trade Area Demographics Profile Report

Returns trade area demographics. By default returns <strong>potential</strong> demographics (population living in the trade area). Set <code>audienceType</code> to <code>captured</code> in the request body to get <strong>captured</strong> demographics (home-CBG demographics of actual visitors).<br/> Supported datasets to use are:<br/> <ul> <li>Census: ACS (2024)</li> <li>STI: Popstats</li> <li>STI: Landscape</li> <li>STI: Market Outlook</li> <li>STI: Spending Patterns</li> <li>STI: Workplace</li> <li>Spatial.ai:PersonaLive</li> <li>Spatial.ai:FollowGraph</li> <li>Experian:Mosaic</li> </ul> <br/>STI: Market Outlook and Spatial.ai:FollowGraph can only be used with <code>audienceType</code> set to <code>potential</code><br/><br/>Datasets are available based on your account's settings<br/><br/> ⏱ <strong>Average measured processing time: 1.58 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<br/><br/>📍 This service supports the <<glossary:Nearby Activity report>>. Once setting a value to the nearbyRadius parameter, the report will be generated based on the nearby activity logic.

post/v1/reports/trade-area-demographics

Request body

startDatestring date required

Queried data start date. Format YYYY-MM-DD

endDatestring date required

Queried data end date. Format YYYY-MM-DD

apiIdstring required

Placer API Entity Id

method'tta' | 'mileRing' | 'driveTime'

The Method for including the block groups in the TA <br/> tta - Determine block groups using intersection with TTA polygon. Requires the setting of the trafficVolPct param as well.<br/> mileRing - Use the block groups within a mile ring.<br/> driveTime - Use the block groups within the trade area defined by the trip duration (in minutes) required for visitors to arrive to the property.

benchmarkScope'nationwide' | 'state'

Benchmark scope

audienceType'potential' | 'captured'

Determines whose demographics are returned.<br/> <strong>potential</strong> - Demographics of the population living in the defined trade area (default behavior).<br/> <strong>captured</strong> - Home-CBG demographics of actual visitors in the selected date range.

allocationType'weightedCentroid' | 'centroid'

The method for including the block group in the TA <br/> Weighted centroid - the centroid is adjusted per the block’s group population. if it falls within the polygon the BG is included <br/> Centroid - A block group’s data is included when the center of the block group falls within the trade area boundaries

trafficVolPctinteger

Required only when method parameter is set to “tta”.<br/> The threshold for the volume of traffic coming to the property. For example - setting a 'traffic vol' of 70% will draw a polygon that includes at least 70% of the visitors’ home location.

driveTimeinteger

The max drive time duration in minutes to determine the trade area

withinRadiusnumber float

The max ‘home distance’ threshold for trade area calculation in miles; i.e. will exclude any visitor beyond this value. For TTA only

ringRadiusnumber float

The max distance for trade area calculation in miles; i.e. will exclude any visitor beyond this value. For mileRing only

dataset'census' | 'sti_popstats' | 'sti_landscape' | 'sti_market_outlook' | 'sti_spending_patterns' | 'sti_workplace' | 'spatial_ai_personalive' | 'spatial_ai_followgraph' | 'experian_mosaic'

The dataset characteristics. One of the following: census (<i>Default</i>), popstats, landscape, marketOutlook, spendingPatterns, workplace

templatestring

The template to parse the demographics data with.<br> <strong>census</strong> - default<br> <strong>sti_popstats</strong> - default, 5_years_forecast, 10_years_forecast<br> <strong>sti_landscape</strong> - overview, households, population<br> <strong>sti_market_outlook</strong> - by_businesses, by_product_line<br> <strong>sti_workplace</strong> - default, demographics<br> <strong>sti_spending_patterns</strong> - default, food, transportation, healthcare,<br> housing, entertainment, alcoholic_beverages, personal_care<br> <strong>spatial_ai_personalive</strong> - overview, segments<br> <strong>spatial_ai_followgraph</strong> - brands, interests, celebrities_and_influencers, media_channels<br> <strong>experian_mosaic</strong> - overview, hh_default, pop_default<br>

nearbyRadius100 | 250 | 500 | 750 | 1000

The radius requested for nearby activity report generation.</br> <strong>Note</strong>: When a value is populated for this attribute - the report will be calculated as per the <<glossary:Nearby Activity report>> logic.

Example request

{
  "startDate": "2020-12-01",
  "endDate": "2021-05-31",
  "apiId": "venue:7d55054520e387813d764b03",
  "method": "tta",
  "benchmarkScope": "nationwide",
  "audienceType": "potential",
  "allocationType": "weightedCentroid",
  "dataset": "census",
  "template": "default",
  "filters": {
    "audienceType": [
      "visitors"
    ],
    "dwellTime": {
      "operator": "<",
      "value": 150
    },
    "hoursRange": {
      "fromHour": "03:00 am",
      "toHour": "11:59 pm"
    },
    "daysOfWeek": [
      6,
      7
    ],
    "distance": {
      "from": "home",
      "values": {
        "lt": 250,
        "gt": 10
      }
    }
  }
}

Response

200 response

requestIdstring required

Request ID that can be used for tracing

apiIdstring

Placer API Entity Id

Example response

{
  "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122",
  "data": {
    "nearbyRadius": 100,
    "filters": {
      "audienceType": [
        "visitors"
      ],
      "dwellTime": {
        "operator": "<",
        "value": 150
      },
      "hoursRange": {
        "fromHour": "03:00 am",
        "toHour": "11:59 pm"
      },
      "daysOfWeek": [
        6,
        7
      ],
      "distance": {
        "from": "home",
        "values": {
          "lt": 250,
          "gt": 10
        }
      }
    },
    "visitDurationSegmentation": "10MinOrLonger",
    "Households": {
      "Households": {
        "value": 14714
      },
      "Family Households": {
        "value": 10641,
        "percentage": 72.31888,
        "variableIndex": 112
      },
      "Non-Family Households": {
        "value": 4073,
        "percentage": 27.68112,
        "variableIndex": 78
      },
      "Persons per Household": {
        "value": 2.705722,
        "variableIndex": 104
      }
    },
    "Gender": {
      "Male": {
        "value": 18686,
        "percentage": 46.935597,
        "variableIndex": 95
      },
      "Female": {
        "value": 21126,
        "percentage": 53.064403,
        "variableIndex": 105
      }
    }
  },
  "apiId": "venue:7d55054520e387813d764b03"
}