---
title: "Trade Area Demographics Profile Report"
method: POST
path: "/v1/reports/trade-area-demographics"
tags: ["Trade Area Reports"]
---

# Trade Area Demographics Profile Report

`POST /v1/reports/trade-area-demographics`

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/> &#x23F1; <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/>&#128205; 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.

## Request body

- TradeAreaDemographicsRequest — Trade Area Demographics returns the demographic accounted for x percentage of the visits from a given dataset and template
  - `startDate` string, date, required — Queried data start date. Format YYYY-MM-DD
  - `endDate` string, date, required — Queried data end date. Format YYYY-MM-DD
  - `apiId` string, 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
  - `trafficVolPct` integer — 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.
  - `driveTime` integer — The max drive time duration in minutes to determine the trade area
  - `withinRadius` number, float — The max ‘home distance’ threshold for trade area calculation in miles; i.e. will exclude any visitor beyond this value. For TTA only
  - `ringRadius` number, 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
  - `template` string — 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>
  - `filters` VmFilterObject — Filtering options for the report results.
    - `audienceType` string[] — If provided - metrics will be calculated based only on the specified types of audience.
    - `dwellTime` object — Metrics will be calculated considering the requested dwell time range.
      - `operator` '<' | '>=' — Less than (<) to Greater Equal (>=)
      - `value` integer — The wanted dwell time
    - `hoursRange` object — Filter the report’s results based on visits hours range. The filter is defined by 2 strings:<br/> 1. The starting hour to filter the reports results from (Format HH:MM XM, for example: 08:00 am).<br/> 2. The end hour to filter the reports results(Format HH:MM XM, for example: 11:59 pm) .
      - `fromHour` string, required
      - `toHour` string, required
    - `daysOfWeek` unknown[] — Filter visit calculation based on days of the week. Results will contain only requested days. Days are represented by using numbers where Monday=1 and Sunday=7. For example: in order to retrieve weekend days use the following [ 6, 7 ].
      - unknown
    - `distance` object — Filter visits by distance in miles from home <strong>or</strong> work<br/> where only visits in a given radius will be used in metrics calculation.
      - `from` 'home' | 'work' — The origin from where the distance will be measured.
      - `values` object — Object representation of the distance range<br/>lt - less than<br/>le - less than or equal to<br/>eq - equal to<br/>ge - greater than or equal to<br/>gt - greater than.
        - `le` number
        - `ge` number
        - `lt` number
        - `gt` number
        - `eq` number
  - `nearbyRadius` 100 | 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.

## Response `200`

200 response

- TradeAreaDemographicsResponse
  - `requestId` string, required — Request ID that can be used for tracing
  - `data` object, required
    - `nearbyRadius` 100 | 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.
    - `filters` ResponseFilters
      - `audienceType` string[] — The list of audiences that is specified in the request filter.
      - `dwellTime` object — The dwell time filter specified in the request, in case it was utilized.<br/> For example: “< 100” or “>= 10”
        - `operator` '<' | '>=' — Represents the operator used for defining the dwell time range for filtering the report data
        - `value` integer — Represents the number of minutes referred to when defining the dwell time range for filtering the report data
      - `hoursRange` object — The hours range that is specified in the request filter.
        - `fromHour` string — Start visits hour (Format HH:MM XM, for example: 08:00 am)
        - `toHour` string — End visitation hour (Format HH:MM XM, for example: 08:00 am)
      - `daysOfWeek` unknown[] — A list of days represented by integers (Monday=1, Sunday=7) as specified in the request filter, which was used in the report calculation.
        - unknown
      - `distance` object — The visits considered for the report calculation by distance in miles from home <strong>or</strong> work as specified in the request filter.
        - `from` 'home' | 'work' — The origin from where the distance will be measured.
        - `values` object — Object representation of the distance range<br/>lt - less than<br/>le - less than or equal to<br/>eq - equal to<br/>ge - greater than or equal to<br/>gt - greater than.
          - `le` number
          - `ge` number
          - `lt` number
          - `gt` number
          - `eq` number
    - `visitDurationSegmentation` 'under10Min' | '10MinOrLonger' | 'allVisits' | 'mixedSegments', nullable — The default visit duration segmentation is returned when the report calculation uses the default segmentation duration.
  - `apiId` string — Placer API Entity Id

## Other responses

- `202` — 202 Accepted
- `204` — 204 No matching results for the requested criteria. In case of report generation - not enough data to generate accurate results.
- `400` — 400 Bad Request
- `401` — 401 Unauthrized dataset error
- `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)