openapi: 3.0.1
info:
title: papi Account Info Visits Reports API
description: Placer Public API
version: 0.1-oas3
servers:
- url: https://papi.placer.ai
x-amazon-apigateway-endpoint-configuration:
disableExecuteApiEndpoint: true
security: null
tags:
- name: Visits Reports
paths:
/v1/reports/visit-metrics:
post:
summary: Visit Metrics Summary Report
tags:
- Visits Reports
description: 'Retrieves visitors and visits for a given list of entities. <br/>This endpoint supports bulk requests up to 100 entities<br/><br/><strong>⇡ This service supports bulk request</strong><br/> When nearbyRadius is set, a report will be generated for the first entity in the array <strong>only</strong>.<br/> <br/> ⏱ <strong>Average measured processing time: 10 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/> 📍 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<br/><br/>
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitMetricsSummaryRequest'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVisitMetricsSummary'
'202':
$ref: '#/components/responses/202_bulk'
'207':
$ref: '#/components/responses/207'
'400':
$ref: '#/components/responses/400_invalid_argument'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
/v1/reports/visit-metrics/cbgs:
post:
summary: Visit by CBGs Report
tags:
- Visits Reports
description: This service populates a report of the CBGs that generate visitation to the properties examined. You may assess visitations per each CBG. You may also determine the desired data granularity.<br/><br/> <strong>⇡ This service supports bulk request</strong><br/><br/> <strong>📍 This service doesn't support custom POI. </strong><br/><br/> * <strong>Please note</strong> that sparsely populated CBGs may not be included in the feed to align with Placer's privacy policy.<br/><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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByCbgModel'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByCbgResponse'
'202':
$ref: '#/components/responses/202_single'
'400':
$ref: '#/components/responses/400_bad_request'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
/v1/reports/visit-metrics/days:
post:
summary: Visits by Days Report
tags:
- Visits Reports
description: 'Retrieves visits for a given entity(venue/complex/billboard) broken by the days of the week.<br/> <br/>The response includes 2 arrays:<br/> <ol> <li>Day of the week bins : [0,1,2,3,4,5,6], where each represents a day of the week. (i.e. Mon.-Sun.).</li> <li>Indicates the total visits for the POI during the selected date range for each of the day of the week bins (correlated to the location in the Day of the week array)</li> </ol> <br/> ⏱ <strong>Average measured processing time: 0.72 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/>
📍 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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByGranularityRequest'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByDayResponse'
'202':
$ref: '#/components/responses/202_bulk'
'204':
$ref: '#/components/responses/204'
'207':
$ref: '#/components/responses/207'
'400':
$ref: '#/components/responses/400_invalid_argument'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
/v1/reports/visit-metrics/dwell-time:
post:
summary: Visits by Dwell Time Report
tags:
- Visits Reports
description: 'Retrieves visits for a given entity(venue/complex) broken by dwell time periods.<br/> <br/>The response includes:<br/> <ol> <li>Dwell time bins array: [0,5,15,30,45,60,75,90,105,120,135,150] (I.e. 5 represents 5-14 minutes, 150 represents all visits with dwell time higher than or equal to 150)</li> <li>Estimated foot traffic array: Indicates the total visits for the POI during the selected date range for each of the dwell time bins (correlated to the location in the dwell time bins array)</li> <li>Average dwell time</li> <li>Median dwell time</li> </ol> <br/> ⏱ <strong>Average measured processing time: 0.77 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/>
📍 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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByGranularityRequest'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByDwellTimeResponse'
'202':
$ref: '#/components/responses/202_bulk'
'204':
$ref: '#/components/responses/204'
'207':
$ref: '#/components/responses/207'
'400':
$ref: '#/components/responses/400_invalid_argument'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
/v1/reports/visit-metrics/hours:
post:
summary: Visits by Hours Report
tags:
- Visits Reports
description: 'Retrieves visits for a given entity(venue/complex) broken by the hours of the day and its business opening hours.<br/> <br/>The response includes:<br/> <ul> <li>2 arrays: <ol> <li>Hour of the day bins: [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23], where each represents an hour in the day. (e.g. 11 = 11 am - 12 pm)</li> <li>Estimated foot traffic array: Indicates the total visits for the POI during the selected date range for each of the hour bins (correlated to the location in the Hour of the day array)</li> </ol> </li> <li> Array of the business opening hours for each day of the week. </li> </ul> <br/> ⏱ <strong>Average measured processing time: 0.79 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/>
📍 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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByGranularityRequest'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/VisitsByHourResponse'
'202':
$ref: '#/components/responses/202_bulk'
'204':
$ref: '#/components/responses/204'
'207':
$ref: '#/components/responses/207'
'400':
$ref: '#/components/responses/400_invalid_argument'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
/v1/reports/visit-trends:
post:
summary: Visit Trends Report
tags:
- Visits Reports
description: 'Retrieves visitations for a given list of entities in daily, weekly or monthly granularity.<br/><br/> <strong>⇡ This service supports bulk request</strong><br/><br/> <strong> ✽ This service supports chain level requests</strong><br/><br/> ⏱ <strong>Average measured processing time: 3.58 seconds </strong><br><br> <strong>📍 This service doesn''t support custom POI. To pull visits trend for custom POI please use <a href="https://docs.placer.ai/reference/post_v1-reports-visit-trends-single">Visit Trends Report for a Single Property </a> endpoint. </strong><br/><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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitTrendsRequest'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/VisitTrendsResponse'
'202':
$ref: '#/components/responses/202_bulk'
'207':
$ref: '#/components/responses/207'
'400':
$ref: '#/components/responses/400_bad_request'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
/v1/reports/visit-trends/single:
post:
summary: Visit Trends Report for a Single Property
tags:
- Visits Reports
description: 'Retrieves visits for a given entity in daily, weekly or monthly granularity.<br/><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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VisitHistoryRequest'
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
x-api-key:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/VisitHistoryResponse'
'202':
$ref: '#/components/responses/202_single'
'400':
$ref: '#/components/responses/400_bad_request'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
x-amazon-apigateway-integration:
type: aws_proxy
httpMethod: POST
uri: ${reports_lambda}
passthroughBehavior: when_no_match
timeoutInMillis: 29000
components:
schemas:
VisitDurationSegmentationRespVisitTrends:
description: "If the default visit duration segmentation is requested, the visitDurationSegmentation will display the actual segment.<\br>.\nIn 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’."
title: Visit Duration Segmentation
type: string
nullable: true
enum:
- under10Min
- 10MinOrLonger
- allVisits
- mixedSegments
example: 10MinOrLonger
StartDate:
type: string
format: date
description: Queried data start date. Format YYYY-MM-DD
example: '2020-12-01'
BasePoiInfo:
title: Base POI Info Object
type: object
properties:
apiId:
$ref: '#/components/schemas/ApiId'
name:
type: string
example: Walmart
description: Entity Name
entityId:
$ref: '#/components/schemas/EntityId'
entityType:
$ref: '#/components/schemas/EntityType'
categoryInfo:
$ref: '#/components/schemas/categoryInfo'
ApiId:
type: string
example: venue:7d55054520e387813d764b03
description: Placer API Entity Id
VisitTrendsSuccess:
allOf:
- type: object
required:
- status
- code
properties:
apiId:
$ref: '#/components/schemas/ApiId'
data:
type: object
properties:
dates:
type: array
description: Date bins for the corresponding data points
items:
type: string
example:
- '2020-12-01'
- '2021-01-01'
- '2021-02-01'
- '2021-03-01'
- '2021-04-01'
- '2021-05-01'
granularity:
description: Aggregation Period
type: string
enum:
- day
- week
- month
example: month
visits:
type: array
description: Extrapolated Visits per datetime bin
items:
type: integer
example:
- 68293
- 67661
- 60130
- 79550
- 79292
- 78276
panelVisits:
type: array
description: The number of visits observed by Placer and are used for statistical extrapolation (per datetime bin) <strong>NOTE:</strong> When using the <strong>distance</strong> filter, panelVisits attribute will not be impacted by the filter and will keep presenting the full panel for the time frame.
items:
type: integer
example:
- 1856
- 1962
- 1745
- 2145
- 1996
- 1842
visitDurationSegmentation:
$ref: '#/components/schemas/VisitDurationSegmentationRespVisitTrends'
categoryInfo:
type: object
properties:
category:
type: string
example: Fast Food & QSR
group:
type: string
example: Dining
subCategory:
type: string
example: Pizze Place
description: Property’s categorization
VisitDurationSegmentationRespReports:
description: The default visit duration segmentation is returned when the report calculation uses the default segmentation duration.
title: Visit Duration Segmentation
type: string
nullable: true
enum:
- under10Min
- 10MinOrLonger
- allVisits
- mixedSegments
example: 10MinOrLonger
BaseBulkReportRequest:
required:
- startDate
- endDate
- apiIds
properties:
startDate:
$ref: '#/components/schemas/StartDate'
endDate:
$ref: '#/components/schemas/EndDate'
apiIds:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/ApiId'
EndDate:
type: string
format: date
description: Queried data end date. Format YYYY-MM-DD
example: '2021-05-31'
VisitsByGranularityRequest:
title: Visits By Granularity Request
allOf:
- $ref: '#/components/schemas/DatesIdParams'
- type: object
properties:
filters:
$ref: '#/components/schemas/VmFilterObject'
nearbyRadius:
$ref: '#/components/schemas/NearbyRadius'
EntityId:
type: string
example: 7d55054520e387813d764b03
description: Entity ID
VisitMetricsSummaryRequest:
title: Visit Metrics Summary Request
description: Retrieves visitors and visits for a given list of entities.<br/>This endpoint supports bulk requests up to 100 entities.
allOf:
- $ref: '#/components/schemas/BaseBulkReportRequest'
- type: object
properties:
includeMetadata:
$ref: '#/components/schemas/IncludeMetadata'
filters:
$ref: '#/components/schemas/VmFilterObject'
nearbyRadius:
$ref: '#/components/schemas/NearbyRadius'
VisitTrendsRequest:
title: Visit Trends Request
description: Calculating ft trends for given dates
allOf:
- $ref: '#/components/schemas/BaseBulkReportRequest'
- type: object
required:
- granularity
properties:
granularity:
type: string
enum:
- day
- week
- month
example: month
filters:
$ref: '#/components/schemas/BaseVmFilterObject'
visitDurationSegmentation:
$ref: '#/components/schemas/VisitDurationSegmentationReq'
VisitsByHourResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: object
properties:
bins:
type: array
items:
type: integer
example:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
description: '[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23], where each represents an hour in the day. (e.g. 11 = 11 am - 12 pm)'
estimatedFoottraffic:
type: array
items:
type: integer
example:
- 691
- 337
- 337
- 337
- 337
- 158
- 308
- 4081
- 16268
- 31543
- 54469
- 78110
- 98220
- 108307
- 112484
- 130168
- 135215
- 127224
- 115792
- 97031
- 75903
- 45117
- 11245
- 996
description: Visits correlated with the same index in the hour bins array
openingHours:
$ref: '#/components/schemas/OpeningHoursList'
nearbyRadius:
$ref: '#/components/schemas/NearbyRadius'
- $ref: '#/components/schemas/filtersAndVisitsDurationSegmentationResp'
OpeningHoursItem:
title: Opening Hours
type: object
properties:
day:
type: string
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
example: Sunday
description: The day of the week
fromHour:
type: string
example: 8:00 AM
description: Opening hour
toHour:
type: string
example: 5:00 PM
description: Closing hour
BaseVmFilterWithHours:
allOf:
- type: object
properties:
hoursRange:
description: '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) .'
type: object
required:
- fromHour
- toHour
properties:
fromHour:
type: string
toHour:
type: string
example:
fromHour: 03:00 am
toHour: 11:59 pm
- $ref: '#/components/schemas/BaseVmFilterObject'
VmFilterObject:
description: Filtering options for the report results.
allOf:
- type: object
properties:
audienceType:
description: If provided - metrics will be calculated based only on the specified types of audience.
example:
- visitors
type: array
items:
type: string
enum:
- visitors
- employees
- residents
dwellTime:
description: Metrics will be calculated considering the requested dwell time range.
type: object
properties:
operator:
description: Less than (<) to Greater Equal (>=)
type: string
enum:
- <
- '>='
example: <
value:
description: The wanted dwell time
type: integer
example: 150
- $ref: '#/components/schemas/BaseVmFilterWithHours'
VisitTrendsResponseNoPanel:
allOf:
- type: object
required:
- status
- code
properties:
apiId:
$ref: '#/components/schemas/ApiId'
data:
type: object
properties:
dates:
type: array
description: Date bins for the corresponding data points
items:
type: string
example:
- '2020-12-01'
- '2021-01-01'
- '2021-02-01'
- '2021-03-01'
- '2021-04-01'
- '2021-05-01'
granularity:
description: Aggregation Period
type: string
enum:
- day
- week
- month
example: month
visits:
type: array
description: Extrapolated Visits per datetime bin
items:
type: integer
example:
- 68293
- 67661
- 60130
- 79550
- 79292
- 78276
visitDurationSegmentation:
$ref: '#/components/schemas/VisitDurationSegmentationRespVisitTrends'
OpeningHoursList:
type: array
items:
$ref: '#/components/schemas/OpeningHoursItem'
description: The property’s business opening hours on each day of the week.
filtersAndVisitsDurationSegmentationResp:
type: object
properties:
filters:
$ref: '#/components/schemas/ResponseFilters'
visitDurationSegmentation:
$ref: '#/components/schemas/VisitDurationSegmentationRespReports'
VisitMetricsSummaryResponse:
title: Visit Metrics Summary
allOf:
- type: object
properties:
apiId:
$ref: '#/components/schemas/ApiId'
data:
type: object
properties:
panelVisitors:
type: integer
example: 5655
description: The number of unique devices used for statistical extrapolation
panelVisits:
type: integer
example: 11546
description: The number of visits observed by Placer and are used for statistical extrapolation
visits:
type: integer
description: Extrapolated number of visits
example: 433202
visitors:
type: integer
example: 184092
description: Extrapolated unique devices
nearbyRadius:
$ref: '#/components/schemas/NearbyRadius'
visitDurationSegmentation:
$ref: '#/components/schemas/VisitDurationSegmentationRespRanking'
metadata:
$ref: '#/components/schemas/BaseEntityInfo'
VisitDurationSegmentationRespRanking:
description: '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''.'
title: Visit Duration Segmentation
type: string
nullable: true
enum:
- under10Min
- 10MinOrLonger
- allVisits
- mixedSegments
example: 10MinOrLonger
VisitsByCbgModel:
title: Visits By Cbg Model
allOf:
- $ref: '#/components/schemas/BaseBulkReportRequest'
- type: object
required:
- granularity
properties:
location:
type: string
enum:
- Home
example: Home
default: Home
description: This parameter determines which CBGs will be listed in the response of the visiting CBGs - The ones that are considered as the visitors' home or the ones considered as their work.</br>*Currently available for home CBGs only
granularity:
type: string
enum:
- week
- month
- year
example: month
description: The data aggregation granularity requested
trafficVolPct:
type: integer
enum:
- 70
- 100
example: 70
default: 70
description: The threshold for the volume of traffic coming to the property.<br> For example - setting a traffic volume percentage of 70 will draw a polygon that includes at least 70% of the visitors’ home location, where 100 will consider all CBGs visited from to the requested POI
Address:
type: object
properties:
city:
type: string
example: Milpitas
description: Entity City
state:
type: string
example: California
description: Entity State
countryCode:
type: string
example: US
description: Entity Country Code
streetName:
type: string
example: Ranch Dr
description: Entity Street Name
formattedAddress:
type: string
example: 301 Ranch Dr, Milpitas, CA, United States
description: Entity Address
shortFormattedAddress:
type: string
example: Ranch Dr, Milpitas, CA
description: Entity Address
zipCode:
type: string
example: '95035'
description: Entity Zip Code
VisitDurationSegmentationReq:
description: This parameter allows for the generation of reports based on either short visits (< 10 minutes), long visits (>= 10 minutes), or all visit data. <br/> By setting the parameter with a “default” value the report may be limited to certain visit durations (length of stay in minutes), to best reflect the typical behavior of visitors.<br> <strong>Available values:</strong><br> ‘under10Min’ - Only visits with a duration of less than 10 minut
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/placer/refs/heads/main/openapi/placer-visits-reports-api-openapi.yml