{ "openapi": "3.0.1", "info": { "title": "papi", "description": "Placer Public API", "version": "0.1-oas3" }, "servers": [ { "url": "https://papi.placer.ai", "x-amazon-apigateway-endpoint-configuration": { "disableExecuteApiEndpoint": true } } ], "security": null, "paths": { "/v1/poi/custom-poi/{id}": { "delete": { "summary": "Delete Custom POI", "tags": [ "Manage POIs" ], "description": "This service allows developers to delete a custom POI by its apiId.", "parameters": [ { "name": "id", "in": "path", "description": "Placer API ID", "required": true, "schema": { "type": "string" }, "example": "complex:5f7a2d2dc2b5e82a0114cf62" } ], "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/DeleteCustomPoiResponse" } } } }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } }, "get": { "summary": "Get Custom POI Info", "tags": [ "Manage POIs" ], "description": "The Get Custom POI Info service can be used to retrieve information regarding any of your <>s, by providing its id.
If the requested Custom POI is newly created, this endpoint will respond with the following statuses:
\n- **HTTP code = 200**: The full response for the Get Custom POI is provided.
- **HTTP code = 202**: The creation process is still in progress.
- **HTTP code = 404**: The POI does not exist, indicating a failure in the creation process. Please retry creating the custom POI.
- **HTTP code = 500**: Server error.", "parameters": [ { "name": "id", "in": "path", "description": "Placer API ID", "required": true, "schema": { "type": "string" }, "example": "complex:5f7a2d2dc2b5e82a0114cf62" } ], "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/CustomPoiInfoGetResponse" } } } }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } }, "put": { "summary": "Update Custom POI", "tags": [ "Manage POIs" ], "description": "The Update POI service can be used to update any of your <>s, by providing any combination of the following custom POI\u2019s properties(at least one):
  1. Name - the POI\u2019s name.
  2. Area - can be defined either by determining the centroid (lng, lat) and the radius to create the POI area, or by a list of all polygon GEO points (lng,lat).
  3. Sub-category (For available sub-categories, see listed categories.
  4. Address - the consumer can change any of the following properties: street address, city and/or zipcode.
", "parameters": [ { "name": "id", "in": "path", "description": "Placer API ID", "required": true, "schema": { "type": "string" }, "example": "complex:5f7a2d2dc2b5e82a0114cf62" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomPoiRequest" } } } }, "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/CustomPoiResponse" } } } }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/poi/tags/": { "delete": { "summary": "Remove POI List From an Existing Tag", "tags": [ "Manage POIs" ], "description": "This service can be used to detach entities from an existing tag.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTagMembersRequest" } } } }, "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/ModifyTagEntitiesResponseSuccess" } } } }, "207": { "$ref": "#/components/responses/207_delete_entities_to_tags" }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } }, "post": { "summary": "Create a new tag", "tags": [ "Manage POIs" ], "description": "Using this service, you have the capability to generate a fresh tag for organizing entities according to your specific business needs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNewTagRequest" } } } }, "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/CreateNewTagResponseSuccess" } } } }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } }, "put": { "summary": "Add POI List to an Existing Tag", "tags": [ "Manage POIs" ], "description": "This service can be used to attach entities to an existing tag.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTagMembersRequest" } } } }, "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/ModifyTagEntitiesResponseSuccess" } } } }, "207": { "$ref": "#/components/responses/207_add_entities_to_tags" }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/accounts/keys/usage-status": { "get": { "summary": "Account Usage", "tags": [ "Account Info" ], "description": "Retrieves the current API usage status for the requesting API key.
This endpoint helps you monitor consumption and remaining quota. Running it 2\u20133 times per week is recommended for optimal tracking usage patterns.
Note: ", "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStatusResponse" } } } }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "api_key": [] } ], "x-amazon-apigateway-integration": { "type": "aws_proxy", "httpMethod": "POST", "uri": "${account_management_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/poi": { "get": { "summary": "Search for Placer Entities", "tags": [ "Manage POIs" ], "description": "This service returns a list of Placer managed entities in a particular area. You can search based on any combination of the following filter parameters:
entities within a specific location radius, entities associated with a specific group category/category/sub category, entity name or type.
The response lists the matched entities, including address and location, zip code, group category, category ,sub-category and a link to Placer dashboard.
The service supports pagination using the skip parameter. The first 1000 entities matching the criteria of the request are available.
For available categories, see listed categories.

Note that when using the radius parameter, the actual area being considered for searching POIs is the area within a square that is bounding the circle, which is defined by the requested radius.
Please note: In case you receive results where the isPermitted attribute is set to \u201cfalse\u201d, that means that you are not permitted to run reports for those. In case you wish to extend your permissions please contact customer support.", "parameters": [ { "name": "lat", "in": "query", "description": "Latitude of query location, if specified then response will not include <>", "required": false, "schema": { "$ref": "#/components/schemas/Latitude" } }, { "name": "lng", "in": "query", "description": "Longitude of query location, if specified then response will not include chains", "required": false, "schema": { "$ref": "#/components/schemas/Longitude" } }, { "name": "query", "in": "query", "description": "String included in the entity name", "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "example": "Walmart" }, { "name": "radius", "in": "query", "schema": { "type": "number", "minimum": 0.01, "maximum": 2000, "default": 1 }, "description": "Filter results by radius in miles. default value 0.01 miles" }, { "name": "category", "in": "query", "description": "Filter specific category", "schema": { "type": "string" }, "example": "Superstores" }, { "name": "subCategory", "in": "query", "description": "Filter specific sub category", "schema": { "type": "string" }, "example": "Big Box Store" }, { "name": "groupCategory", "in": "query", "description": "Filter specific group category i.e. Search POIs by business domains (e.g. Apparel,Dining, ....)", "schema": { "type": "string" }, "example": "Superstores" }, { "name": "entityType", "in": "query", "schema": { "type": "array", "default": [ "venue", "complex", "chain" ], "items": { "type": "string", "enum": [ "venue", "complex", "chain" ] } }, "description": "Filter out specific entity type in search result. If this is not provided, all entity types will be returned", "required": false, "explode": false, "example": [ "venue" ] }, { "name": "limit", "in": "query", "description": "Search result limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "skip", "in": "query", "schema": { "type": "number", "minimum": 0, "default": 0, "maximum": 999 } }, { "name": "includeFlaggedEntities", "in": "query", "description": "If the parameter is set to true, the response will also include flagged entities", "schema": { "type": "boolean" }, "example": false } ], "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "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": "${search_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/poi/{id}/entities": { "get": { "summary": "Get Sub-Entities for a complex, a chain or a tag", "tags": [ "Manage POIs" ], "description": "Returns a list of sub-entities for given api ID. Sub-entities can be associated with <>, <> and <> . <> and <> contain venues as their sub-entities while <> may have venues, <> or <>

✽ This service supports chain level requests.", "parameters": [ { "name": "id", "in": "path", "description": "Placer entity API ID (i.e. ID of a chain, a complex or a tag)", "required": true, "schema": { "type": "string" }, "example": "chain:58ef64a9173f5601f92d8f0e" }, { "name": "includeRegionalChains", "in": "query", "description": "Set this parameter to True for pulling regional chains(under the parent chain requested) as well as all other sub entities.", "required": false, "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubEntitiesResponse" } } } }, "400": { "$ref": "#/components/responses/400_invalid_argument" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "api_key": [] } ], "x-amazon-apigateway-integration": { "type": "aws_proxy", "httpMethod": "POST", "uri": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/poi/my-properties": { "get": { "summary": "Get Listed Entities for Account.", "tags": [ "Manage POIs" ], "description": "Returns a list of entities for a given account.The response will include all entities which are under the Property tag (i.e. Portfolio).", "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyPropertiesResponse" } } } }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "api_key": [] } ], "x-amazon-apigateway-integration": { "type": "aws_proxy", "httpMethod": "POST", "uri": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/poi/custom-poi": { "post": { "summary": "Create Custom POI", "tags": [ "Manage POIs" ], "description": "The create <> endpoint can be used to generate custom POIs by specifying the unique polygons to analyze.
The <> can be generated by either specifying the combination of centroid (lng, lat) and mile radius to draw the POI's area, or by using GEOJson which includes a list of all polygon GEO points (lng, lat).
This endpoint runs duplication checks on each call in order to ensure that the same <> is not created more than once. If a <> is already created the return code will display a wrong request (http-code=400) specifying the previously created API ID.
Please be aware that creating custom POIs might take longer than 30 seconds, which falls within the timeout window. During such occurrences, the HTTP response code will be 202 (i.e., In progress), along with the apiId of the partially created POI. You can monitor the creation status by querying the Get Custom POI endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomPoiRequest" } } } }, "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/CustomPoiResponse" } } } }, "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": "${poi_info_lambda}", "passthroughBehavior": "when_no_match", "timeoutInMillis": 29000 } } }, "/v1/reports/favorites-chains": { "post": { "summary": "Visitor Journey - Favorite Chains", "tags": [ "Visitor Journey Reports" ], "description": "Favorite <> provides a list of other <> that visitors to your location have also visited during the selected time frame (e.g., X% of visitors to My Venue also visited Chain A during the last X months).
\nYou may choose specific categories to examine among the listed categories and define the minimum visit frequency.
\nThe response includes the top 50 properties matching the requested parameters.



⏱ Average measured processing time: 4.46 seconds
For more information on request retries best practices and processing measurements you may visit this page

📍 This service supports the <>. 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/FavoriteRequest" } } } }, "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/FavoriteChainsResponse" } } } }, "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/favorites-places": { "post": { "summary": "Visitor Journey - Favorite Places", "tags": [ "Visitor Journey Reports" ], "description": "Favorite Places provides a list of other places that visitors to your location have also visited during the selected time frame (e.g., X% of visitors to My Venue also visited Place A during the last X months).
\nYou may choose specific categories to examine among the listed categories and define the minimum visit frequency.
\nThe response includes the top 50 properties matching the requested parameters.

\n⏱ Average measured processing time: 4.46 seconds
For more information on request retries best practices and processing measurements you may visit this page

\n📍 This service supports the <>. 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/FavoriteRequest" } } } }, "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/FavoritePlacesResponse" } } } }, "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/loyalty/visits-frequency": { "post": { "summary": "Visits by Frequency Report", "tags": [ "Loyalty Reports" ], "description": "This service enables you to learn about the frequency of visitations to the requested POI.
Insights are provided for all the below types of metrics, bucketed into visitations frequency bins (i.e. 1, 2, 3, \u202630+ visits per visitor):
  • Visitors - The estimated number of unique visitors to the POI
  • % of Visitors - The % of unique visitors that visited the POI
  • Visits - The estimated number of visits to the POI
  • % of Visits - The % of visits generated by visitors to the POI


📍 This service supports the <>. 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/VisitsFrequencyRequest" } } } }, "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/VisitsFrequencyResponse" } } } }, "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/ranking-index/closely-ranked": { "post": { "summary": "Ranking Index - Closely Ranked", "tags": [ "Ranking Reports" ], "description": "This endpoint generates a ranked list of properties relative to a benchmark based on the one of following segments:
  • Within Chain - Provides other closely ranked venues within the same chain.
  • category - provides the <> within the venue\u2019s category
  • Within Category/Group Category - Provides other closely ranked venues within the same category/group category.
Provides view by different metrics and regions.
Metrics:
  • Visits: shows the <> according to the estimated number of visits to the POI.
  • Visits / Sq ft: shows the <> according to the estimated number of visits relative to the total square footage of a property.

Regions:
  • nationwide: The nationwide <> of a POI benchmarked against POIs from the same category or chain.
    • \n
  • state/dma/cbsa: The Ranking benchmarked against POIs from the same category or chain in the POI's state/dma/cbsa.
    • \n
  • Specific distance: The POI\u2019s Ranking benchmarked against POIs from within a 5 / 10 / 15 / 30 / 50 miles radius.
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 results amount value is set to 200 - then the response includes all properties ranked between 450 and 649 within the indexed list.
The endpoint supports pre-defined time buckets and ranking regions.

\n⏱ Average measured processing time: 3.98 seconds
For more information on request retries best practices and processing measurements you may visit this page

\nNOTE: Flagged entities will not be taken into consideration in the resulting report.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingIndexCloselyRankedRequest" } } } }, "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": { "oneOf": [ { "$ref": "#/components/schemas/RankingIndexResponse" }, { "$ref": "#/components/schemas/RankingIndexError" } ] } } } }, "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/ranking-index/top-ranking": { "post": { "summary": "Ranking Index - Top Ranked", "tags": [ "Ranking Reports" ], "description": "Generate a ranked list of properties relative to a benchmark based on the one of following segments:
  • Within Chain - ability to reach all chain\u2019s venues ranked from the top most to the last using pagination.
  • Within Category/Group Category - ability to fetch up to 1000 top ranked properties within the same Category/group category of the requested property.
Provides view by different metrics and regions.
Metrics
  • Visits: shows the <> according to the estimated number of visits to the POI.
  • Visits / Sq ft: shows the <> according to the estimated number of visits relative to the total square footage of a property.
Regions
  • nationwide: The nationwide <> of a POI benchmarked against POIs from the same category or chain.
  • state/dma/cbsa: The ranking benchmarked against POIs from the same category or chain in the POI's state/dma/cbsa.
  • Specific distance: The POI\u2019s <> benchmarked against POIs from within a 5 / 10 / 15 / 30 / 50 miles radius.


⏱ Average measured processing time: 2.71 seconds
For more information on request retries best practices and processing measurements you may visit this page

\nNOTE: <> will not be taken into consideration in the resulting report.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingIndexTopRankingRequest" } } } }, "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": { "oneOf": [ { "$ref": "#/components/schemas/RankingIndexResponse" }, { "$ref": "#/components/schemas/RankingIndexError" } ] } } } }, "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/ranking-overview": { "post": { "summary": "Ranking Metrics for a Single Property", "tags": [ "Ranking Reports" ], "description": "This service returns the specific entity <> within a selected scope :
  • Chain scope - compares the entity <> vs all other chain\u2019s entities
  • Group category scope - compares the entity <> vs all venues under the selected group category (Apparel, Leisure, \u2026).
  • Category scope - compares the entity <> vs all venues under the selected category (Regional Mall, Industrial, \u2026).

The endpoint supports the option to have a custom date range (as well as pre-defined time buckets) and <> within a local area ( 5,10,15 miles).
⏱ Average measured processing time: 8.57 seconds
For more information on request retries best practices and processing measurements you may visit this page

\nNOTE: <> will not be taken into consideration in the resulting report.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRequestSingular" } } } }, "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/RankingResponseSingular" } } } }, "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/ranking-overview/multi": { "post": { "summary": "Ranking Metrics For Multiple Properties", "tags": [ "Ranking Reports" ], "description": "Returns the <> for all the requested entities within a selected scope :
  • Chain scope - compares each entity <> vs all other chain\u2019s entities.
  • Group category scope - compares each entity <> vs all venues under the selected group category (Apparel, Leisure, \u2026).
  • Category scope - compares each entity <> vs all venues under the selected category (Regional Mall, Industrial, \u2026).
The service supports <> based on pre-defined periods. (In case a custom date range is required use /reports/ranking-overview endpoint).

⇡ This service supports bulk request
\n\n⏱ Average measured processing time: 3.58 seconds
For more information on request retries best practices and processing measurements you may visit this page

NOTE: <> will not be taken into consideration in the resulting report", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRequestMulti" } } } }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/RankingResponseMulti" } } } } }, "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/retail-sales/avg-ticket-size-trends": { "post": { "summary": "Retail Sales Average Ticket Size Trend Report", "tags": [ "Retail Sales Reports" ], "description": "Average Ticket Size report allows you to examine the average dollar amount of sales per transaction generated at the venue in your report, during the selected date range. You can compare the venue's average ticket size trend against its category average.

\nNote: Retail sales data currently excludes online transactions and only pertains to sales in brick and mortar locations. Transactions which occurred using the Buy Now Pick Up In Store option may be reflected in the data, depending on the retailer concerned. In the event that Retail Sales data is not available for the report\u2019s entire date range the response will provide the exact dates for which the data applies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvgTicketSizeRequest" } } } }, "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/AvgTicketSizeResponse" } } } }, "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/retail-sales/days": { "post": { "summary": "Retail Sales Daily Trends", "tags": [ "Retail Sales Reports" ], "description": "This service provides the retail sales metrics overview for the entire requested period aggregated either by the day of the week or by weekdays/weekend. The insights are available for various of metrics:
  • sales: The dollar value (USD) of all sales during your selected aggregation.
  • avg_sales: The dollar value (USD) of average sales per day during your selected aggregation.
  • sales_pct: The percentage of total sales which occurred during your selected aggregation.
  • sales_sq_ft: The total value of sales per square foot at the venue examined, during your selected aggregation.
  • transactions: The total number of individual transactions which took place at the property examined during your selected aggregation.
  • transactions_pct:The percentage of total transactions which occurred during your selected .aggregation.
  • avg_ticket_size: The average dollar amount of sales per transaction generated at the venues in your report, per your selected aggregation.
\nNote: Retail sales data currently excludes online transactions and only pertains to sales in brick and mortar locations. Transactions which occurred using the Buy Now Pick Up In Store option may be reflected in the data, depending on the retailer concerned. In the event that Retail Sales data is not available for the report\u2019s entire date range the response will provide the exact dates for which the data applies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDaysTrendsRequest" } } } }, "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/SalesDaysTrendsResponse" } } } }, "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/retail-sales/overview": { "post": { "summary": "Retail Sales Overview", "tags": [ "Retail Sales Reports" ], "description": "This service provides the retail sales metrics overview for the entire requested period.

\nNote: Retail sales data currently excludes online transactions and only pertains to sales in brick and mortar locations. Transactions which occurred using the Buy Now Pick Up In Store option may be reflected in the data, depending on the retailer concerned. In the event that Retail Sales data is not available for the report\u2019s entire date range the response will provide the exact dates for which the data applies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatesIdParams" } } } }, "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/SalesOverviewResponse" } } } }, "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/retail-sales/sales-trends": { "post": { "summary": "Retail Sales Trend Report", "tags": [ "Retail Sales Reports" ], "description": "This service provides the insights about sales performance at each venue examined in the report. Within the response of this service you will be receiving both the requested insights based on the date range, granularity and type of metric, and the annual sales for the past year-to-date and 3 last calendar years.

\nNote: Retail sales data currently excludes online transactions and only pertains to sales in brick and mortar locations. Transactions which occurred using the Buy Now Pick Up In Store option may be reflected in the data, depending on the retailer concerned. In the event that Retail Sales data is not available for the report\u2019s entire date range the response will provide the exact dates for which the data applies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesTrendRequest" } } } }, "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/SalesTrendResponse" } } } }, "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/retail-sales/transaction-trends": { "post": { "summary": "Retail Sales Transactions Trends Report", "tags": [ "Retail Sales Reports" ], "description": "The Transaction Trend presents the total number of transactions generated at the venues in your report over time. You can compare the venue's transaction trend against its category or chain average.

\nNote: Retail sales data currently excludes online transactions and only pertains to sales in brick and mortar locations. Transactions which occurred using the Buy Now Pick Up In Store option may be reflected in the data, depending on the retailer concerned. In the event that Retail Sales data is not available for the report\u2019s entire date range the response will provide the exact dates for which the data applies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionTrendRequest" } } } }, "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/TransactionTrendResponse" } } } }, "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/trade-area-demographics": { "post": { "summary": "Trade Area Demographics Profile Report", "tags": [ "Trade Area Reports" ], "description": "Returns trade area demographics. By default returns potential demographics (population living in the trade area). Set audienceType to captured in the request body to get captured demographics (home-CBG demographics of actual visitors).
Supported datasets to use are:
  • Census: ACS (2024)
  • STI: Popstats
  • STI: Landscape
  • STI: Market Outlook
  • STI: Spending Patterns
  • STI: Workplace
  • Spatial.ai:PersonaLive
  • Spatial.ai:FollowGraph
  • Experian:Mosaic

Datasets are available based on your account's settings

⏱ Average measured processing time: 1.58 seconds
For more information on request retries best practices and processing measurements you may visit this page

\nNOTE: <> will not be taken into consideration in the resulting report

\n📍 This service supports the <>. 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/TradeAreaDemographicsRequest" } } } }, "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/TradeAreaDemographicsResponse" } } } }, "202": { "$ref": "#/components/responses/202_single" }, "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_bad_request" }, "401": { "$ref": "#/components/responses/401" }, "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/trade-area/drive-time": { "post": { "summary": "Trade Area by Drive Time Report", "tags": [ "Trade Area Reports" ], "description": "This service lets you retrieve the trade area polygon calculated for a specified drive time.

\n📍 This service supports the <>. 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/TradeAreaByDriveTimeRequest" } } } }, "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/TradeAreaByDriveTimeResponse" } } } }, "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/true-trade-area": { "post": { "summary": "Trade Area Report", "tags": [ "Trade Area Reports" ], "description": "True Trade Areas are calculated by the volume of traffic reaching the venue or complex . For example, setting 'traffic vol' to 70% draws a polygon that represents 70% of the visitors\u2019 home location.

⏱ Average measured processing time: 2.24 seconds
For more information on request retries best practices and processing measurements you may visit this page

\n📍 This service supports the <>. 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/TrueTradeAreaRequest" } } } }, "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/PolygonResponse" } } } }, "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": { "post": { "summary": "Visit Metrics Summary Report", "tags": [ "Visits Reports" ], "description": "Retrieves visitors and visits for a given list of entities.
This endpoint supports bulk requests up to 100 entities

⇡ This service supports bulk request
When nearbyRadius is set, a report will be generated for the first entity in the array only.

⏱ Average measured processing time: 10 seconds
For more information on request retries best practices and processing measurements you may visit this page

📍 This service supports the <>. Once setting a value to the nearbyRadius parameter, the report will be generated based on the nearby activity logic

\n", "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.

⇡ This service supports bulk request

📍 This service doesn't support custom POI.

* Please note that sparsely populated CBGs may not be included in the feed to align with Placer's privacy policy.

For more information on request retries best practices and processing measurements you may visit this 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.

The response includes 2 arrays:
  1. Day of the week bins : [0,1,2,3,4,5,6], where each represents a day of the week. (i.e. Mon.-Sun.).
  2. 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)

⏱ Average measured processing time: 0.72 seconds
For more information on request retries best practices and processing measurements you may visit this page

\n📍 This service supports the <>. 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.

The response includes:
  1. 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)
  2. 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)
  3. Average dwell time
  4. Median dwell time

⏱ Average measured processing time: 0.77 seconds
For more information on request retries best practices and processing measurements you may visit this page

\n📍 This service supports the <>. 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.

The response includes:
  • 2 arrays:
    1. 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)
    2. 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)
  • Array of the business opening hours for each day of the week.

⏱ Average measured processing time: 0.79 seconds
For more information on request retries best practices and processing measurements you may visit this page

\n📍 This service supports the <>. 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.

⇡ This service supports bulk request

✽ This service supports chain level requests

⏱ Average measured processing time: 3.58 seconds

📍 This service doesn't support custom POI. To pull visits trend for custom POI please use Visit Trends Report for a Single Property endpoint.

\nFor more information on request retries best practices and processing measurements you may visit this 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.

\nFor more information on request retries best practices and processing measurements you may visit this 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": { "BaseError": { "title": "BaseError", "type": "object", "required": [ "code", "details", "message" ], "properties": { "message": { "type": "string", "description": "Detail error message", "example": "Internal server error" }, "details": { "type": "string", "example": "GENERAL_ERROR", "description": "Brief error message" }, "code": { "type": "integer", "example": 5000, "description": "Status Code" }, "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "ErrorBadRequest": { "title": "ErrorBadRequest", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "code": 2000, "message": "Validation error. Field `startDate` is required", "details": "BAD_REQUEST", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "ErrPermissionDenied": { "title": "ErrPermissionDenied", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "code": 1008, "details": "PERMISSION_DENIED", "message": "You don't have permission to perform this action", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "RequestId": { "type": "string", "example": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122", "description": "Request ID that can be used for tracing" }, "DeleteCustomPoiResponse": { "title": "Delete Custom POI Response", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "result": { "type": "string", "example": "SUCCESS" } } } } }, "DeleteTagMembersRequest": { "title": "Delete tag members request", "type": "object", "required": [ "apiIds", "tagId" ], "properties": { "apiIds": { "type": "array", "description": "The list of entities to remove from the specified tag", "items": { "$ref": "#/components/schemas/ApiId" } }, "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807", "description": "The Id of the tag to remove the list of entities from" } } }, "ApiId": { "type": "string", "example": "venue:7d55054520e387813d764b03", "description": "Placer API Entity Id" }, "ModifyTagEntitiesResponseSuccess": { "title": "Modify Tag Entities Response Success", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "result": { "type": "string", "example": "SUCCESS" }, "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807" } } } } }, "DeleteEntitiesFromTagResponseMultiStatus": { "title": "Delete Entities From Tag Response Multi Status", "type": "object", "properties": { "data": { "type": "object", "properties": { "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807" } } }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ModifyTagEntitiesResponseSuccessItem" }, { "title": "Modify Tag Entities Response Failure", "type": "object", "properties": { "status": { "type": "string", "example": "FAILURE" }, "code": { "type": "integer", "example": 2002 }, "details": { "type": "string", "example": "INVALID_ARGUMENTS" }, "message": { "type": "string", "example": "The apiId cannot be removed from the specified tag" }, "apiId": { "type": "string", "example": "venue:7d55054520e387813d764b03" } } } ] } } } }, "ModifyTagEntitiesResponseSuccessItem": { "title": "Modify Tag Entities Response Success", "type": "object", "properties": { "status": { "type": "string", "example": "SUCCESS" }, "code": { "type": "integer", "example": 0 }, "apiId": { "type": "string", "example": "venue:7d55054520e387813d764b03" } } }, "UsageStatusResponse": { "title": "Usage Status Response", "type": "object", "properties": { "usedQuota": { "type": "integer", "description": "The number of API calls your account has actually used during the current weekly quota period. This reflects your current API call consumption." }, "queriedPOIs": { "type": "integer", "description": "The total number of unique Points of Interest (POIs) queried through any POI-related endpoints in the current weekly quota period. This helps track how many distinct POIs have been requested." }, "weeklyUsageByEndpoint": { "description": "The weekly usage per each utilized endpoint", "type": "array", "items": { "type": "object", "properties": { "endpoint": { "type": "string", "description": "Endpoint's method and URI" }, "numOfCalls": { "type": "integer", "description": "The number of calls to the endpoint on the current week." } } } } } }, "BaseResponse": { "title": "Base Response", "type": "object", "required": [ "requestId" ], "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "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" } } }, "BaseEntityInfo": { "title": "POI Entity (complex, venue and billboard only!) Object", "allOf": [ { "$ref": "#/components/schemas/BasePoiInfo" } ], "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "isFlagged": { "type": "boolean", "example": false, "description": "The Entity Data Is Incomplete" }, "regions": { "type": "object", "properties": { "dma": { "type": "object", "description": "The Entity Designated Market Area", "properties": { "code": { "type": "string", "example": 807 }, "name": { "type": "string", "example": "San Francisco-Oakland-San Jose, CA" } } }, "state": { "type": "object", "description": "Entity State", "properties": { "code": { "type": "string", "example": "CA" }, "name": { "type": "string", "example": "California" } } }, "cbsa": { "type": "object", "description": "The Entity Core-Based Statistical Areas", "properties": { "code": { "type": "string", "example": "41940" }, "name": { "type": "string", "example": "San Jose-Sunnyvale-Santa Clara, CA Metro Area" } } } }, "description": "The regions in which the property is included" } } }, "PoiInfo": { "title": "POI Info Object", "allOf": [ { "$ref": "#/components/schemas/BasePoiInfo" }, { "$ref": "#/components/schemas/BaseEntityInfo" } ], "type": "object", "properties": { "placerUrl": { "type": "string", "example": "https://staging-analytics.placer.team/#!/admin/insights/venues/7d55054520e387813d764b03/overview" }, "parentChains": { "type": "object", "example": { "apiId": "chain:58ef64a9173f5601f92d8f0e", "name": "Target" } }, "parentTags": { "type": "object", "example": { "apiId": "tag:614c118e500adeae9e9e70a6", "name": "Test Group Tag" } }, "isPermitted": { "type": "boolean", "example": true, "description": "This flag indicates whether the account is permitted to generate/request reports on this entity or not." }, "regionType": { "type": "string", "example": "dma", "description": "The regions which the entity is associated with. Supported regions are: 'nationwide', 'state', 'dma' & 'cbsa'. Relevant only for chain." }, "regionCode": { "type": "string", "example": "11010", "description": "The code defining the region (e.g. The state of Arizona -> 'AZ', nationwide -> 'US'). Relevant only for chain." } } }, "SearchResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" } ], "required": [ "data" ], "title": "POI Search Results", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoiInfo" } } } }, "Longitude": { "type": "number", "format": "float", "minimum": -180, "maximum": 180, "description": "Longitude of query location", "example": -121.98 }, "Latitude": { "type": "number", "format": "float", "minimum": -90, "maximum": 90, "description": "Latitude of query location", "example": 37.52 }, "EntityId": { "type": "string", "example": "7d55054520e387813d764b03", "description": "Entity ID" }, "EntityType": { "type": "string", "enum": [ "venue", "complex", "chain" ], "example": "venue", "description": "Entity Type (i.e. venue, complex etc.)" }, "categoryInfo": { "type": "object", "properties": { "category": { "type": "string", "example": "Fast Food & QSR" }, "group": { "type": "string", "example": "Dining" }, "subCategory": { "type": "string", "example": "Pizze Place" } }, "description": "Property\u2019s categorization" }, "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" } } }, "CustomPoiInfoGetResponse": { "title": "POI By ID Info Object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BasePoiInfo" }, { "$ref": "#/components/schemas/BaseEntityInfo" }, { "$ref": "#/components/schemas/PoiInfo" }, { "type": "object", "properties": { "storeId": { "type": "string", "example": 1401, "description": "The identification of a venue. Relevant only for chain's venues." } } } ] }, "ErrInvalidArguments": { "title": "ErrInvalidArguments", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "message": "Invalid apiId format", "code": 2002, "details": "INVALID_ARGUMENTS", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "ErrorNotFound": { "title": "ErrorNotFound", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "code": 4000, "details": "ERROR_NOT_FOUND", "message": "Requested item was not found", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "SubEntitiesResponse": { "title": "Sub Entities Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" } ], "required": [ "data" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityInfoRegional" } } } }, "EntityInfoRegional": { "title": "Placer Entity Info", "allOf": [ { "$ref": "#/components/schemas/EntityInfo" }, { "$ref": "#/components/schemas/RegionInfo" } ] }, "RegionInfo": { "title": "Placer Region Info", "properties": { "regionType": { "type": "string", "example": "state", "description": "Optional string for region type" }, "regionCode": { "type": "string", "example": "WV", "description": "Optional string for region code" } } }, "EntityInfo": { "title": "Placer Entity Info", "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "name": { "type": "string", "example": "Walmart", "description": "Entity name" }, "entityId": { "$ref": "#/components/schemas/EntityId" }, "entityType": { "$ref": "#/components/schemas/EntityType" }, "flagged": { "type": "boolean", "description": "Flagging status for entity" }, "storeId": { "type": "string", "example": "1401", "description": "The identification of a venue. Relevant only for chain\u2019s venues" } } }, "MyPropertiesResponse": { "title": "MyProperties Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" } ], "required": [ "data" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoiInfo" } } } }, "BaseCustomPoiRequest": { "allOf": [ { "type": "object", "properties": { "centroid": { "type": "array", "items": { "type": "number", "format": "float", "minimum": -200, "maximum": 80 }, "description": "List of 2 values that represents the GEO location of the POI center", "example": [ -78.519444, 36.61636 ] }, "radius": { "type": "number", "format": "float", "minimum": 0.007, "maximum": 0.21, "default": 0.1, "description": "Radius (in miles) with which the polygon is constructed when the center of the polygon is the centroid" }, "polygon": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "float" } }, "description": "List of pairs ([lng, lat]) that represents the POI polygon", "example": [ [ -78.51961433887482, 36.61628975092374 ], [ -78.51927638053894, 36.61628975092374 ], [ -78.51927638053894, 36.616430763747964 ], [ -78.51961433887482, 36.616430763747964 ], [ -78.51961433887482, 36.61628975092374 ] ] }, "address": { "type": "object", "properties": { "address": { "type": "string", "example": "301 Ranch Dr", "description": "Entity Address" }, "city": { "type": "string", "example": "Milpitas", "description": "Entity City" }, "zipCode": { "type": "string", "example": "95035", "description": "Entity Zip Code" } } } } } ] }, "CreateCustomPoiRequest": { "title": "Create custom POI request", "description": "Creating <> by given name, sub category and polygon/centroid + radius", "allOf": [ { "type": "object", "required": [ "name", "subCategory" ], "properties": { "name": { "type": "string", "example": "Some Custom POI Name" }, "subCategory": { "type": "string", "example": "Pizza Place" }, "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807", "description": "The Id of the tag that the <> is requested to be associated with. If no value is provided, the new POI will not be associated with any tag." } } }, { "$ref": "#/components/schemas/BaseCustomPoiRequest" } ] }, "CustomPoiResponse": { "title": "Custom POI Response", "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomPoiInfo" } } }, "CustomPoiInfo": { "title": "Custom POI Info Object", "type": "object", "properties": { "result": { "type": "string", "example": "SUCCESS" }, "name": { "type": "string", "example": "Name to be used to identify the <>" }, "apiId": { "type": "string", "example": "complex:8d22ae197ee335c5074a67ff" } } }, "CreateNewTagRequest": { "title": "Add a new tag request", "type": "object", "required": [ "tagName" ], "properties": { "tagName": { "type": "string", "description": "The new tag name", "example": "My Shop", "maxLength": 150 } } }, "CreateNewTagResponseSuccess": { "title": "Create New Tag Response Success", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "result": { "type": "string", "example": "SUCCESS" }, "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807" } } } } }, "DatesIdParams": { "title": "Base Report Request", "type": "object", "required": [ "startDate", "endDate", "apiId" ], "properties": { "startDate": { "$ref": "#/components/schemas/StartDate" }, "endDate": { "$ref": "#/components/schemas/EndDate" }, "apiId": { "$ref": "#/components/schemas/ApiId" } } }, "filtersAndVisitsDurationSegmentationResp": { "type": "object", "properties": { "filters": { "$ref": "#/components/schemas/ResponseFilters" }, "visitDurationSegmentation": { "$ref": "#/components/schemas/VisitDurationSegmentationRespReports" } } }, "BaseChainInfo": { "title": "POI Chain Object", "allOf": [ { "$ref": "#/components/schemas/BasePoiInfo" } ], "type": "object", "properties": { "regionType": { "type": "string", "example": "nationwide" } } }, "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" }, "FavoriteRequest": { "title": "Favorites Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" }, "example": [ "gas stations & convenience stores", "airport facilities" ], "description": "Array of categories to which the resulted favorite places are associated. \u201call\u201d will be used as default.
NOTE: please select the specific categories from the listed categories.
If a list of categories is provided yet only some categories are recognized, results will reflect only the recognized categories. In case no category is recognized the results will reflect all categories." }, "minimalVisitFrequency": { "type": "integer", "default": 1, "minimum": 0, "maximum": 99, "description": "The minimal visits frequency requested in the other places/<>. 1 will be used as default." }, "limit": { "type": "integer", "default": 50, "minimum": 0, "maximum": 50, "description": "The number of expected results. Default is set to 50." }, "filters": { "$ref": "#/components/schemas/VmFilterObject" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] }, "FavoriteChainsResponse": { "allOf": [ { "$ref": "#/components/schemas/FavoriteResponse" }, { "type": "object", "properties": { "favoritesChainsArray": { "description": "The list of most visited chains by the visitors to the requested POI", "type": "array", "items": { "$ref": "#/components/schemas/FavoriteChainsInfo" } } } } ] }, "FavoriteResponse": { "allOf": [ { "type": "object", "properties": { "requestedCategories": { "type": "array", "items": { "type": "string" }, "example": [ "gas stations & convenience stores", "airport facilities" ], "description": "The list of requested categories" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } }, { "$ref": "#/components/schemas/filtersAndVisitsDurationSegmentationResp" } ] }, "StartDate": { "type": "string", "format": "date", "description": "Queried data start date. Format YYYY-MM-DD", "example": "2020-12-01" }, "EndDate": { "type": "string", "format": "date", "description": "Queried data end date. Format YYYY-MM-DD", "example": "2021-05-31" }, "BaseVmFilterWithHours": { "allOf": [ { "type": "object", "properties": { "hoursRange": { "description": "Filter the report\u2019s results based on visits hours range. The filter is defined by 2 strings:
1. The starting hour to filter the reports results from (Format HH:MM XM, for example: 08:00 am).
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" } ] }, "BaseVmFilterObject": { "description": "Filtering options for the report results.", "type": "object", "properties": { "daysOfWeek": { "description": "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 ].", "example": [ 6, 7 ], "type": "array", "items": { "enum": [ 1, 2, 3, 4, 5, 6, 7 ] } }, "distance": { "description": "Filter visits by distance in miles from home or work
where only visits in a given radius will be used in metrics calculation.", "example": { "from": "home", "values": { "lt": 250, "gt": 10 } }, "type": "object", "properties": { "from": { "description": "The origin from where the distance will be measured.", "type": "string", "enum": [ "home", "work" ], "example": "home" }, "values": { "description": "Object representation of the distance range
lt - less than
le - less than or equal to
eq - equal to
ge - greater than or equal to
gt - greater than.", "example": { "gt": 10, "le": 100 }, "type": "object", "properties": { "le": { "type": "number" }, "ge": { "type": "number" }, "lt": { "type": "number" }, "gt": { "type": "number" }, "eq": { "type": "number" } } } } } } }, "ResponseFilters": { "type": "object", "properties": { "audienceType": { "description": "The list of audiences that is specified in the request filter.", "example": [ "visitors" ], "type": "array", "items": { "type": "string", "enum": [ "visitors", "employees", "residents" ] } }, "dwellTime": { "description": "The dwell time filter specified in the request, in case it was utilized.
For example: \u201c< 100\u201d or \u201c>= 10\u201d", "type": "object", "properties": { "operator": { "description": "Represents the operator used for defining the dwell time range for filtering the report data", "type": "string", "enum": [ "<", ">=" ], "example": "<" }, "value": { "description": "Represents the number of minutes referred to when defining the dwell time range for filtering the report data", "type": "integer", "example": 150 } } }, "hoursRange": { "description": "The hours range that is specified in the request filter.", "type": "object", "properties": { "fromHour": { "description": "Start visits hour (Format HH:MM XM, for example: 08:00 am)", "type": "string" }, "toHour": { "description": "End visitation hour (Format HH:MM XM, for example: 08:00 am)", "type": "string" } }, "example": { "fromHour": "03:00 am", "toHour": "11:59 pm" } }, "daysOfWeek": { "description": "A list of days represented by integers (Monday=1, Sunday=7) as specified in the request filter, which was used in the report calculation.", "example": [ 6, 7 ], "type": "array", "items": { "enum": [ 1, 2, 3, 4, 5, 6, 7 ] } }, "distance": { "description": "The visits considered for the report calculation by distance in miles from home or work as specified in the request filter.", "example": { "from": "home", "values": { "lt": 250, "gt": 10 } }, "type": "object", "properties": { "from": { "description": "The origin from where the distance will be measured.", "type": "string", "enum": [ "home", "work" ], "example": "home" }, "values": { "description": "Object representation of the distance range
lt - less than
le - less than or equal to
eq - equal to
ge - greater than or equal to
gt - greater than.", "example": { "gt": 10, "le": 100 }, "type": "object", "properties": { "le": { "type": "number" }, "ge": { "type": "number" }, "lt": { "type": "number" }, "gt": { "type": "number" }, "eq": { "type": "number" } } } } } } }, "NearbyRadius": { "type": "integer", "enum": [ 100, 250, 500, 750, 1000 ], "description": "The radius requested for nearby activity report generation.
Note: When a value is populated for this attribute - the report will be calculated as per the <> logic." }, "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" } ] }, "FavoriteBaseInfo": { "title": "Favorite Base Entity Info", "type": "object", "properties": { "estimatedNumberOfCustomers": { "type": "integer", "example": 1234, "description": "Estimated foot traffic during the requested period, when associated with visitation to the queried POI" }, "percentage": { "type": "number", "format": "float", "example": 48.92, "description": "The percentage of visitors to the requested venue also visited this property during the requested period" } } }, "FavoriteChainsInfo": { "title": "Favorite Chains Entity Info", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseChainInfo" }, { "$ref": "#/components/schemas/FavoriteBaseInfo" } ] }, "FavoritePlacesResponse": { "allOf": [ { "$ref": "#/components/schemas/FavoriteResponse" }, { "type": "object", "properties": { "favoritesPlacesArray": { "description": "The list of most visited places by the visitors to the requested POI", "type": "array", "items": { "$ref": "#/components/schemas/FavoritePlacesInfo" } } } } ] }, "FavoritePlacesInfo": { "title": "Favorite Places Entity Info", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseEntityInfo" }, { "$ref": "#/components/schemas/FavoriteBaseInfo" }, { "type": "object", "properties": { "distanceInMiles": { "type": "number", "format": "float", "example": 12.43, "description": "The distance between this property to the queried POI in Miles." } } } ] }, "VisitsFrequencyRequest": { "title": "Visits Frequency Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/VmFilterObject" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] }, "VisitsFrequencyResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "avgVisitsPerCustomer": { "type": "number", "format": "float", "description": "The average number of visits for per visitor to the POI", "example": 1.88 }, "medianVisitsPerCustomer": { "type": "integer", "description": "The median number of visits for per visitor to the POI", "example": 1 }, "bins": { "type": "array", "description": "The array represents bins for the number of visits. Each bin represents visits with frequency value between current bin value and the next. E.g. Bin #2 has a value of 2 and bin #3 has a value of 3. So in bin #2 represent the visits that occurred exactly 2 times. But bin #10 has the value of 10, and bin #11 has the value of 15. So bin #10 will include all the visits that occurred 10 times or more, but less than 15 times. The last bin is unbounded.", "items": { "type": "integer" }, "example": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 30 ] }, "visitors": { "type": "array", "description": "The estimated number of unique visitors to the POI correlated with the bins array.", "items": { "type": "integer" }, "example": [ 195397, 42348, 20053, 9578, 6046, 3337, 2013, 1394, 1282, 3195, 1163, 385, 219 ] }, "visitorsPercentage": { "type": "array", "description": "The % of unique visitors that visited the POI correlated with the bins array.", "items": { "type": "number", "format": "float" }, "example": [ 68.22, 14.79, 7, 3.34, 2.11, 1.17, 0.7, 0.49, 0.45, 1.12, 0.41, 0.13, 0.08 ] }, "visits": { "type": "array", "description": "The estimated number of visits to the POI correlated with the bins array.", "items": { "type": "integer" }, "example": [ 195397, 84696, 60159, 38311, 30230, 20025, 14089, 11151, 11534, 35719, 19090, 8790, 10029 ] }, "visitsPercentage": { "type": "array", "description": "The % of visits that visited the POI correlated with the bins array.", "items": { "type": "number", "format": "float" }, "example": [ 36.24, 15.71, 11.16, 7.1, 5.61, 3.71, 2.61, 2.07, 2.14, 6.62, 3.54, 1.63, 1.86 ] }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] } } }, { "$ref": "#/components/schemas/filtersAndVisitsDurationSegmentationResp" } ] }, "InProgress": { "title": "InProgress", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "code": 3005, "message": "Report is being prepared", "details": "IN_PROGRESS", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "RankingIndexBaseRequest": { "title": "Ranking Index Request", "allOf": [ { "type": "object", "required": [ "apiId", "region", "period" ], "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "region": { "$ref": "#/components/schemas/Region" }, "period": { "$ref": "#/components/schemas/PeriodPreset" } } }, { "$ref": "#/components/schemas/RankingRequest" } ] }, "RankingIndexCloselyRankedRequest": { "title": "Ranking Index Closely Ranked Request", "allOf": [ { "$ref": "#/components/schemas/RankingIndexBaseRequest" }, { "type": "object", "properties": { "resultsAmount": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "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." } } }, { "$ref": "#/components/schemas/RankingRequest" } ] }, "RankingRequest": { "allOf": [ { "type": "object", "required": [ "scope", "metric" ], "properties": { "scope": { "type": "string", "enum": [ "chain", "category", "groupCategory" ], "example": "category", "default": "category" }, "metric": { "type": "string", "enum": [ "visitsPerSqft", "visits" ], "example": "visits", "default": "visits" } } } ] }, "VisitDurationSegmentationRespRanking": { "description": "Represents the requested visit duration segmentation.
If the default visit duration segmentation is requested, the visitDurationSegmentation will display the actual segment.
\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" }, "PeriodPreset": { "description": "The time period for which the <> will be calculated. Cannot be used along with startDate and endDate", "title": "period", "type": "string", "nullable": true, "enum": [ "last3Months", "last6Months", "last12Months", "lastWeek", "lastMonth", "lastQuarter", "yearToDate", "year2018", "year2019", "year2020", "year2021", "year2022", "year2023", "year2024", "year2025" ], "example": "lastWeek" }, "RankingIndexError": { "properties": { "region": { "description": "The requested region", "example": "state" }, "scope": { "description": "The requested scope", "type": "string", "example": "category" }, "metricType": { "description": "The requested metric", "type": "string", "example": "visits" }, "rankError": { "type": "string", "description": "The error that was occuerd while trying to get <> for that entity", "example": "The ranking is unavailable for this entity with the specified parameters." } } }, "RankingIndexResponse": { "type": "object", "properties": { "totalRanked": { "description": "The total number of properties within the scope and region selected, from which the <> will be conducted. For example: the requested property is ranked 550 out of 7500 (= total number of records) properties within the same chain(= scope) in the same state(= region).", "type": "integer", "example": 123 }, "rank": { "description": "The rank of the requested POI", "type": "integer", "example": 65 }, "region": { "description": "The requested region", "example": "state" }, "scope": { "description": "The requested scope", "type": "string", "example": "category" }, "metricType": { "description": "The requested metric", "type": "string", "example": "visits" }, "visits": { "description": "The estimated foot traffic at the requested property per the requested parameters", "type": "number", "example": 12000 }, "rankingIndexArray": { "type": "array", "items": { "type": "object", "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "name": { "type": "string", "example": "entity name" }, "address": { "$ref": "#/components/schemas/RankingIndexAddress" }, "rank": { "type": "integer", "example": 90 }, "visits": { "type": "number", "example": 105463 } } } }, "visitDurationSegmentation": { "$ref": "#/components/schemas/VisitDurationSegmentationRespRanking" } } }, "Region": { "enum": [ "5", "10", "15", "30", "50", "nationwide", "state", "dma", "cbsa" ], "default": 15, "description": "Region to be set for ranking index" }, "RankingIndexAddress": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "country": { "type": "string", "example": "United States", "description": "Entity Country" }, "address": { "type": "string", "example": "301 Ranch Dr", "description": "Entity Address" } } } ] }, "RankingIndexTopRankingRequest": { "title": "Ranking Index Top Ranking Request", "allOf": [ { "$ref": "#/components/schemas/RankingIndexBaseRequest" }, { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 100, "description": "Number of records to be fetched" }, "skip": { "type": "integer", "minimum": 0, "default": 0, "description": "Relevant for the chain scope only. Contains 0 in the first call, and the offset for pagination in next calls, default set to 0." } } }, { "$ref": "#/components/schemas/RankingRequest" } ] }, "RankingRequestSingular": { "title": "Ranking Request", "description": "The endpoint return the nationwide, state, CBSA, DMA and the local distance <> as selected in the query params.", "allOf": [ { "type": "object", "required": [ "apiId" ], "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "startDate": { "description": "The start date of the time period for which the <> will be calculated. Cannot be used along with period param", "type": "string", "format": "date", "example": "2020-12-01" }, "endDate": { "description": "The end date of the time period for which the <> will be calculated. Cannot be used along with period param", "type": "string", "format": "date", "example": "2020-12-31" }, "distanceMiles": { "type": "integer", "enum": [ 5, 10, 15, 30, 50 ], "example": 15, "default": 15 }, "period": { "$ref": "#/components/schemas/PeriodPreset" } } }, { "$ref": "#/components/schemas/RankingRequest" } ] }, "RankingResponseSingular": { "type": "object", "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "metricType": { "type": "string", "example": "visits" }, "info": { "$ref": "#/components/schemas/RankingEntityInfo" }, "ranking": { "oneOf": [ { "$ref": "#/components/schemas/RankingMetricsWithLocal" }, { "type": "object", "properties": { "rankError": { "type": "string", "description": "The error that was occuerd while trying to get <> for that entity", "example": "This entity if flagged/unverified" } } } ] }, "visitDurationSegmentation": { "$ref": "#/components/schemas/VisitDurationSegmentationRespRanking" } } }, "RankingEntityInfo": { "type": "object", "properties": { "name": { "type": "string", "example": "Walmart", "description": "Entity name" }, "entityId": { "$ref": "#/components/schemas/EntityId" }, "entityType": { "$ref": "#/components/schemas/EntityType" }, "flagged": { "type": "boolean", "description": "Flagging status for entity" }, "rankedBy": { "type": "string", "description": "the scope which the <> has been ranked by", "example": "chain" }, "categoryInfo": { "$ref": "#/components/schemas/categoryInfo" }, "parentChain": { "type": "string", "description": "The name of the chain that entity belongs to" } } }, "RankingMetricsWithLocal": { "allOf": [ { "$ref": "#/components/schemas/RankingMetrics" }, { "type": "object", "properties": { "local": { "$ref": "#/components/schemas/RankingRegionObjectLocal" } } } ] }, "RankingMetrics": { "type": "object", "description": "<> info for a property", "properties": { "nationwide": { "$ref": "#/components/schemas/RankingRegionObjectNationwide" }, "state": { "$ref": "#/components/schemas/RankingRegionObjectState" }, "dma": { "$ref": "#/components/schemas/RankingRegionObjectDma" }, "cbsa": { "$ref": "#/components/schemas/RankingRegionObjectCbsa" } } }, "RankingRegionObjectNationwide": { "allOf": [ { "$ref": "#/components/schemas/RankingRegionObject" }, { "type": "object", "properties": { "regionCode": { "type": "string", "example": "US" } } } ] }, "RankingRegionObjectState": { "allOf": [ { "$ref": "#/components/schemas/RankingRegionObject" }, { "type": "object", "properties": { "regionCode": { "type": "string", "example": "CA" } } } ] }, "RankingRegionObjectDma": { "allOf": [ { "$ref": "#/components/schemas/RankingRegionObject" }, { "type": "object", "properties": { "regionCode": { "type": "string", "example": "510" } } } ] }, "RankingRegionObjectCbsa": { "allOf": [ { "$ref": "#/components/schemas/RankingRegionObject" }, { "type": "object", "properties": { "regionCode": { "type": "string", "example": "34980" } } } ] }, "RankingRegionObjectLocal": { "allOf": [ { "$ref": "#/components/schemas/RankingRegionObject" }, { "type": "object", "properties": { "radiusMiles": { "type": "integer", "example": 15 } } } ] }, "RankingRegionObject": { "type": "object", "properties": { "rank": { "type": "integer", "example": 4 }, "percentile": { "type": "integer", "example": 85 }, "rankedOutOf": { "type": "integer", "example": 1850 } } }, "RankingRequestMulti": { "title": "Ranking Request", "description": "Returns the <> metrics for given property in all regions.", "allOf": [ { "type": "object", "required": [ "apiIds", "period" ], "properties": { "apiIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ApiId" } }, "period": { "$ref": "#/components/schemas/PeriodPreset" } } }, { "$ref": "#/components/schemas/RankingRequest" } ] }, "RankingResponseMulti": { "type": "object", "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "metricType": { "type": "string", "example": "visits" }, "info": { "$ref": "#/components/schemas/RankingEntityInfo" }, "ranking": { "oneOf": [ { "$ref": "#/components/schemas/RankingMetrics" }, { "type": "object", "properties": { "rankError": { "type": "string", "description": "The error that was occuerd while trying to get <> for that entity", "example": "This entity if flagged/unverified" } } } ] }, "visitDurationSegmentation": { "$ref": "#/components/schemas/VisitDurationSegmentationRespRanking" } } }, "AvgTicketSizeRequest": { "title": "Average Ticket Size Trend Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "compareType": { "$ref": "#/components/schemas/AvgTicketSizeTrendsCompareType" }, "granularity": { "$ref": "#/components/schemas/SalesTrendGranularity" } } } ] }, "AvgTicketSizeResponse": { "title": "Avg Ticket Size Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "compareType": { "allOf": [ { "$ref": "#/components/schemas/AvgTicketSizeTrendsCompareType" }, { "description": "Will be presented if requested." } ] }, "granularity": { "$ref": "#/components/schemas/SalesTrendGranularity" }, "trend": { "type": "object", "description": "Presents the average ticket size trends for the requested POI during the requested period based on the selected granularity.", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "2022-08-01", "2022-09-01", "2022-10-01" ], "description": "Presents the sales average ticket size trends in bins based on the requested granularity (e.g. in month granularity each bin will present the first date of the month, for day granularity each bin will present each day of the report date range)" }, "values": { "type": "array", "description": "Correlated average ticket size info values to the bins array", "items": { "type": "number", "example": [ 60222003.71, 58126656.69, 67245632.21 ] } } } }, "compare": { "nullable": true, "type": "object", "description": "Presents the sales average ticket size comparison trends.", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "2022-08-01", "2022-09-01", "2022-10-01" ], "description": "Presents the sales in bins based on the requested granularity (e.g. in month granularity each bin will present the first date of the month, for day granularity each bin will present each day of the report date range)" }, "values": { "type": "array", "items": { "type": "number" }, "example": [ 60222523.71, 56326656.69, 47654112.81 ], "description": "Correlated sales info values to the bins array" } } } } } ] } } } ] }, "SalesTrendGranularity": { "description": "The aggregation of data requested for the report. Can be one of month, week or day.", "enum": [ "day", "week", "month" ], "example": "month", "default": "month" }, "AvgTicketSizeTrendsCompareType": { "description": "The chain or category trend to compare with. Can be one of:
  • None
  • avg_category_in_state
  • avg_category_nationwide
    • ", "enum": [ "avg_category_in_state", "avg_category_nationwide" ], "nullable": true, "example": "avg_category_nationwide" }, "SalesDaysTrendsRequest": { "title": "Sales Days Trends Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "aggregation": { "$ref": "#/components/schemas/SalesDayOfWeekAgg" }, "metricType": { "$ref": "#/components/schemas/DayOfWeekMetricType" } } } ] }, "SalesDaysTrendsResponse": { "title": "Sales Days Trends Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "aggregation": { "$ref": "#/components/schemas/SalesDayOfWeekAgg" }, "metricType": { "$ref": "#/components/schemas/DayOfWeekMetricType" }, "dayOfWeek": { "type": "object", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ], "description": "This array defines the relevant bins based on the aggregation requested.
    Either Monday-Sunday or weekday/weekend." }, "values": { "type": "array", "items": { "type": "number" }, "example": [ 23332019.04, 20430526.44, 20256899.97, 24597150.08, 30653813.68, 30801899.86, 27723322.83 ], "description": "The corresponding values to the bins (array index based)." } } } } } ] } } } ] }, "SalesDayOfWeekAgg": { "type": "string", "enum": [ "full_week", "weekday_weekend" ], "example": "full_week", "default": "full_week", "description": "For the day of week insights you can choose any of the following aggregation options:
    • full_week - The aggregation is done per each day of the week
    • weekday_weekend - The aggregation is done for the weekdays altogether and the weekend altogether.
    " }, "DayOfWeekMetricType": { "type": "string", "enum": [ "sales", "avg_sales", "sales_pct", "sales_sq_ft", "transactions", "transactions_pct", "avg_ticket_size" ], "example": "sales", "default": "sales", "description": "The metric for which you wish to get the day of week aggregation for:
    • sales: The dollar value (USD) of all sales during your selected aggregation.
    • avg_sales: The dollar value (USD) of average sales per day during your selected aggregation.
    • sales_pct: The percentage of total sales which occurred during your selected aggregation.
    • sales_sq_ft: The total value of sales per square foot at the venue examined, during your selected aggregation.
    • transactions: The total number of individual transactions which took place at the property examined during your selected aggregation.
    • transactions_pct:The percentage of total transactions which occurred during your selected .aggregation.
    • avg_ticket_size: The average dollar amount of sales per transaction generated at the venues in your report, per your selected aggregation.
    " }, "SalesOverviewResponse": { "title": "Sales Overview Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "salesOverview": { "type": "array", "description": "In this array the following overview of various sales metrics calculated for the whole period.", "items": { "type": "object", "properties": { "valueType": { "type": "string", "enum": [ "currency", "number" ], "description": "The type of the value provided either 'currency' or 'number'" }, "metricName": { "type": "string", "description": "This will include any of the following values for each array instance:
    \u25cf sales: Total sales for the requested period
    \u25cf sales_sq_ft: Total sales per SQ FT for the requested period
    \u25cf transactions: Total number of transactions done during the requested period
    \u25cf avg_daily_unique_customers: Average daily unique visitors amount for the requested period
    \u25cf avg_monthly_unique_customers: Average monthly unique visitors amount for the requested period
    \u25cf avg_weekly_unique_customers: Average weekly unique visitors amount for the requested period
    \u25cf avg_ticket_size: Average ticket size for the requested period" }, "value": { "description": "The relevant metric value calculated for the whole period.", "type": "number", "format": "float" } } }, "example": [ { "valueType": "currency", "metricName": "sales", "value": 177795631.94 }, { "valueType": "currency", "metricName": "sales_sq_ft", "value": 852.75 }, { "valueType": "number", "metricName": "transactions", "value": 3298775.63 }, { "valueType": "number", "metricName": "avg_daily_unique_customers", "value": 4611.03 }, { "valueType": "number", "metricName": "avg_monthly_unique_customers", "value": 71553.62 }, { "valueType": "number", "metricName": "avg_weekly_unique_customers", "value": 27317.12 }, { "valueType": "currency", "metricName": "avg_ticket_size", "value": 53.9 } ] } } } ] } } } ] }, "SalesTrendRequest": { "title": "Sales Trend Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "metric": { "$ref": "#/components/schemas/SalesTrendMetric" }, "granularity": { "$ref": "#/components/schemas/SalesTrendGranularity" } } } ] }, "SalesTrendResponse": { "title": "Sales Trend Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "metric": { "$ref": "#/components/schemas/SalesTrendMetric" }, "granularity": { "$ref": "#/components/schemas/SalesTrendGranularity" }, "annualSales": { "description": "Presents the annual sales in bins per year including last 3 years and last 12 months.", "type": "object", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "2021", "2022", "2023", "1y" ], "description": "Array of bins specifying the years which the sales info in the values array refer to" }, "values": { "type": "array", "items": { "type": "number" }, "example": [ 60222003.71, 58126656.69, 54654112.81, 67245632.21 ], "description": "Correlated sales info values to the bins array" } } }, "trend": { "description": "Presents the sales divided into bins based on the requested granularity.", "type": "object", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "2022-08-01", "2022-09-01", "2022-10-01" ], "description": "Presents the sales in bins based on the requested granularity (e.g. in month granularity each bin will present the first date of the month, for day granularity each bin will present each day of the report date range)" }, "values": { "type": "array", "items": { "type": "number" }, "example": [ 60222003.71, 58126656.69, 54654112.81 ], "description": "Correlated sales info values to the bins array" } } } } } ] } } } ] }, "SalesTrendMetric": { "description": "The metric requested for the report. Can be one of the following:
    sales - The total dollar value (USD) of all sales generated for the requested venue.
    sales_sq_ft - The total dollar value (USD) of sales per SQ FT generated for the requested venue.", "enum": [ "sales", "sales_sq_ft" ], "example": "sales", "default": "sales" }, "TransactionTrendRequest": { "title": "Transaction Trend Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "compareType": { "$ref": "#/components/schemas/TransactionTrendCompareType" }, "granularity": { "$ref": "#/components/schemas/SalesTrendGranularity" } } } ] }, "TransactionTrendResponse": { "title": "Transaction Trend Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "compareType": { "allOf": [ { "$ref": "#/components/schemas/TransactionTrendCompareType" }, { "description": "Will be presented if requested." } ] }, "granularity": { "$ref": "#/components/schemas/SalesTrendGranularity" }, "trend": { "type": "object", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "2022-08-01", "2022-09-01", "2022-10-01" ], "description": "Presents the transactions trends for the requested POI during the requested period based on the selected granularity." }, "values": { "type": "array", "items": { "type": "number" }, "example": [ 138915.39, 139320.64, 136581.83 ], "description": "Presents the sales transactions in bins based on the requested granularity (e.g. in month granularity each bin will present the first date of the month, for day granularity each bin will present each day of the report date range)" } } }, "compare": { "nullable": true, "type": "object", "properties": { "bins": { "type": "array", "items": { "type": "string" }, "example": [ "2022-08-01", "2022-09-01", "2022-10-01" ], "description": "Presents the sales transactions in bins based on the requested granularity (e.g. in month granularity each bin will present the first date of the month, for day granularity each bin will present each day of the report date range)" }, "values": { "type": "array", "items": { "type": "number" }, "example": [ 138915.39, 139320.64, 136581.83 ], "description": "Correlated sales info values to the bins array" } } } } } ] } } } ] }, "TransactionTrendCompareType": { "description": "The chain or category trend to compare with
    • None
    • avg_chain_in_state
    • avg_chain_nationwide
    • avg_category_in_state
    • avg_category_nationwide
    ", "enum": [ "avg_chain_in_state", "avg_chain_nationwide", "avg_category_in_state", "avg_category_nationwide" ], "nullable": true, "example": "avg_chain_in_state" }, "TradeAreaDemographicsRequest": { "title": "Trade Area Demographics Request", "description": "Trade Area Demographics returns the demographic accounted for x percentage of the visits from a given dataset and template", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "required": [ "startDate", "endDate", "apiId" ], "properties": { "method": { "description": "The Method for including the block groups in the TA
    tta - Determine block groups using intersection with TTA polygon. Requires the setting of the trafficVolPct param as well.
    mileRing - Use the block groups within a mile ring.
    driveTime - Use the block groups within the trade area defined by the trip duration (in minutes) required for visitors to arrive to the property.", "type": "string", "enum": [ "tta", "mileRing", "driveTime" ], "default": "tta", "example": "tta" }, "benchmarkScope": { "type": "string", "enum": [ "nationwide", "state" ], "description": "Benchmark scope", "example": "nationwide", "default": "nationwide" }, "audienceType": { "type": "string", "enum": [ "potential", "captured" ], "default": "potential", "example": "potential", "description": "Determines whose demographics are returned.
    potential - Demographics of the population living in the defined trade area (default behavior).
    captured - Home-CBG demographics of actual visitors in the selected date range." }, "allocationType": { "$ref": "#/components/schemas/AllocationType" }, "trafficVolPct": { "description": "Required only when method parameter is set to \u201ctta\u201d.
    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\u2019 home location.", "type": "integer", "default": 70, "minimum": 1, "maximum": 99 }, "driveTime": { "description": "The max drive time duration in minutes to determine the trade area", "type": "integer", "minimum": 1, "maximum": 200 }, "withinRadius": { "type": "number", "format": "float", "minimum": 1, "maximum": 300, "default": 15, "description": "The max \u2018home distance\u2019 threshold for trade area calculation in miles; i.e. will exclude any visitor beyond this value. For TTA only" }, "ringRadius": { "type": "number", "format": "float", "minimum": 0.2, "maximum": 250, "default": 3, "description": "The max distance for trade area calculation in miles; i.e. will exclude any visitor beyond this value. For mileRing only" }, "dataset": { "description": "The dataset characteristics. One of the following: census (Default), popstats, landscape, marketOutlook, spendingPatterns, workplace", "type": "string", "enum": [ "census", "sti_popstats", "sti_landscape", "sti_market_outlook", "sti_spending_patterns", "sti_workplace", "spatial_ai_personalive", "spatial_ai_followgraph", "experian_mosaic" ], "default": "census", "example": "census" }, "template": { "description": "The template to parse the demographics data with.
    census - default
    sti_popstats - default, 5_years_forecast, 10_years_forecast
    sti_landscape - overview, households, population
    sti_market_outlook - by_businesses, by_product_line
    sti_workplace - default, demographics
    sti_spending_patterns - default, food, transportation, healthcare,
    housing, entertainment, alcoholic_beverages, personal_care
    spatial_ai_personalive - overview, segments
    spatial_ai_followgraph - brands, interests, celebrities_and_influencers, media_channels
    experian_mosaic - overview, hh_default, pop_default
    ", "example": "default" }, "filters": { "$ref": "#/components/schemas/VmFilterObject" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] }, "NoContent": { "title": "No Content Response", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "message": "No data available for this entity in requested time range", "code": 3006, "details": "No Content", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "ErrUnAuthorizedDataSource": { "title": "ErrUnAuthorizedDataSource", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseError" }, { "type": "object", "example": { "message": "This dataset is unauthrized", "code": 1000, "details": "UNAUTHORIZED DATA SOURCE", "requestId": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122" } } ] }, "TradeAreaDemographicsResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DemographicGroupEntry" }, "properties": { "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" }, "filters": { "$ref": "#/components/schemas/ResponseFilters" }, "visitDurationSegmentation": { "$ref": "#/components/schemas/VisitDurationSegmentationRespReports" } }, "example": { "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": { "$ref": "#/components/schemas/ApiId" } } } ] }, "DemographicGroupEntry": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DemographicSubGroup" } }, "DemographicSubGroup": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number", "example": 534534 }, "variableIndex": { "description": "The index indicates the performance of the parameter you are evaluating comparing to the selected benchmark. For example if you are looking at avg. Household Income and comparing it to the nationwide benchmark an index score of 100 will mean that the location you are analyzing is preforming the same as nationwide levels for this metric.", "type": "number", "example": 17.3 }, "percentage": { "description": "Reflects the percentile <> of a given geographies as compared to the entire country. For example, a score of 90.00 would reflect that this geography has scored higher than 90% of the country for the given segmant", "type": "number", "example": 56.7 }, "variablePercentage": { "type": "number", "example": 20.3 } } }, "AllocationType": { "type": "string", "enum": [ "weightedCentroid", "centroid" ], "example": "weightedCentroid", "default": "weightedCentroid", "description": "The method for including the block group in the TA
    **Weighted centroid** - the centroid is adjusted per the block\u2019s group population. if it falls within the polygon the BG is included
    **Centroid** - A block group\u2019s data is included when the center of the block group falls within the trade area boundaries" }, "TradeAreaByDriveTimeRequest": { "title": "Trade Area By Drive Time Request", "description": "This service enables to pull the trade area polygon calculated based on a specified drive time.", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "allocationType": { "$ref": "#/components/schemas/AllocationType" }, "driveTime": { "$ref": "#/components/schemas/DriveTime" }, "filter": { "$ref": "#/components/schemas/VmFilterObject" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] }, "TradeAreaByDriveTimeResponse": { "title": "Trade Area By Drive Time Response", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "$ref": "#/components/schemas/filtersAndVisitsDurationSegmentationResp" }, { "type": "object", "properties": { "allocationType": { "$ref": "#/components/schemas/AllocationType" }, "driveTime": { "$ref": "#/components/schemas/DriveTime" }, "type": { "type": "string", "enum": [ "MultiPolygon" ], "example": "MultiPolygon", "description": "The Polygon Data Structure (https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.7)" }, "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] } } } ] }, "Coordinates": { "type": "array", "description": "Coordinate Object (Latitude, Longitude)", "items": { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "oneOf": [ { "$ref": "#/components/schemas/Longitude" }, { "$ref": "#/components/schemas/Latitude" } ] } } } }, "DriveTime": { "description": "The max drive time duration threshold for trade area calculation in minutes; i.e. will exclude any visitor beyond this value.", "type": "integer", "default": 10, "minimum": 5, "maximum": 200 }, "TrueTradeAreaRequest": { "title": "True trade area request", "description": "True trade areas are calculated by 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\u2019 home location.", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "required": [ "reportType" ], "properties": { "reportType": { "type": "string", "enum": [ "trueTradeArea" ], "description": "Queried report type", "example": "trueTradeArea", "default": "trueTradeArea" }, "fileFormat": { "type": "string", "enum": [ "polygonGeoJson" ], "default": "polygonGeoJson", "example": "polygonGeoJson", "description": "Result format" }, "trafficVolPct": { "type": "integer", "default": 70, "minimum": 30, "maximum": 100, "description": "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\u2019 home location" }, "allocationType": { "$ref": "#/components/schemas/AllocationType" }, "withinDistance": { "type": "number", "format": "float", "minimum": 1, "maximum": 100, "default": 50, "description": "The max \u2018home distance\u2019 threshold for trade area calculation in miles; i.e. will exclude any visitor beyond this value." }, "filter": { "$ref": "#/components/schemas/VmFilterObject" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] }, "PolygonResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" } ], "title": "Polygon Response", "type": "object", "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "data": { "allOf": [ { "$ref": "#/components/schemas/filtersAndVisitsDurationSegmentationResp" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MultiPolygon" ], "example": "MultiPolygon", "description": "The Polygon Data Structure (https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.7)" }, "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] } } }, "VisitMetricsSummaryRequest": { "title": "Visit Metrics Summary Request", "description": "Retrieves visitors and visits for a given list of entities.
    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" } } } ] }, "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" } } } }, "InProgressBulkResponse": { "title": "In Progress Bulk Response", "type": "object", "required": [ "requestId" ], "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseInProgressEntry" }, { "$ref": "#/components/schemas/ResponseInProgressEntry" } ] } } } }, "MultiStatusResponse": { "title": "Multi-status bulk response", "type": "object", "required": [ "requestId" ], "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseInProgressEntry" }, { "$ref": "#/components/schemas/ResponseSuccessEntry" } ] } } } }, "BulkVisitMetricsSummary": { "type": "object", "properties": { "requestId": { "type": "string", "example": "cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122", "description": "Request ID that can be used for tracing" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VisitMetricsSummaryResponse" } } } }, "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" } } } } } ] }, "ResponseInProgressEntry": { "type": "object", "properties": { "details": { "type": "string", "enum": [ "IN_PROGRESS" ], "description": "Status String" }, "code": { "type": "integer", "example": 3005, "description": "Status Code" }, "message": { "type": "string", "example": "Report is being prepared", "description": "Status description" }, "apiId": { "$ref": "#/components/schemas/ApiId" } } }, "ResponseSuccessEntry": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SUCCESS" ], "description": "Status String" }, "code": { "type": "integer", "example": 0, "description": "Status Code" }, "apiId": { "$ref": "#/components/schemas/ApiId" } } }, "IncludeMetadata": { "type": "boolean", "default": true, "description": "If the parameter is set to true, the response will also include the POI Info" }, "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.
    *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.
    For example - setting a traffic volume percentage of 70 will draw a polygon that includes at least 70% of the visitors\u2019 home location, where 100 will consider all CBGs visited from to the requested POI" } } } ] }, "VisitsByCbgResponse": { "title": "Visits By Cbg Response", "allOf": [ { "$ref": "#/components/schemas/VisitsByCbgModel" }, { "type": "object", "properties": { "visitsByCBGs": { "type": "array", "description": "Array of visits by CBGs insights broken down by apiIds", "items": { "type": "object", "properties": { "apiId": { "$ref": "#/components/schemas/ApiId" }, "dates": { "type": "array", "description": "Array of start days of each bin based on the granularity", "items": { "type": "string" }, "example": [ "2020-12-01", "2021-01-01", "2021-02-01", "2021-03-01", "2021-04-01", "2021-05-01" ] }, "visitsByCBGsTrend": { "type": "array", "description": "An Array that provides the visits per each CBG for the defined granularity broken down by the apiIds(corresponding to the apiIds array).
    The data is presented as array objects corresponding to the dates array, where for each defined a nested array of coupled CBGcode-visits, that were observed during the relevant time period.", "example": [ [ { "CBGCode": 360470163003, "visits": 2859.0998658824965 }, { "CBGCode": 360471122002, "visits": 1964.8362800193345 } ], [ { "CBGCode": 360471214002, "visits": 3428.9773043774903 }, { "CBGCode": 360471130002, "visits": 1552.924740122248 } ], [ { "CBGCode": 360471196003, "visits": 2557.0424557126844 }, { "CBGCode": 360471122002, "visits": 1390.5306827296477 } ], [ { "CBGCode": 360470886002, "visits": 2625.74170877762 }, { "CBGCode": 360471196003, "visits": 2866.8235103927195 } ], [ { "CBGCode": 360470163003, "visits": 3483.2945180135303 }, { "CBGCode": 360471196003, "visits": 3821.0165325827234 } ], [ { "CBGCode": 360471196003, "visits": 3815.7833289048413 }, { "CBGCode": 360470163003, "visits": 3087.490216778003 } ] ], "items": { "type": "array", "items": { "type": "object", "properties": { "CBGcode": { "type": "integer", "description": "The CBG code", "example": 481439506002 }, "visits": { "type": "number", "format": "float", "description": "The estimated visits to the POI from the CBG for the corresponding bin period", "example": 45.98458763323508 } } } } }, "visitDurationSegmentation": { "$ref": "#/components/schemas/VisitDurationSegmentationRespReports" } } } } } } ] }, "VisitsByDayResponse": { "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 ] }, "estimatedFoottraffic": { "type": "array", "items": { "type": "integer" }, "example": [ 219347, 227870, 226154, 229736, 245526, 369653, 295663 ] }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } } }, { "$ref": "#/components/schemas/filtersAndVisitsDurationSegmentationResp" } ] }, "VisitsByGranularityRequest": { "title": "Visits By Granularity Request", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "properties": { "filters": { "$ref": "#/components/schemas/VmFilterObject" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } ] }, "VisitsByDwellTimeResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "bins": { "type": "array", "items": { "type": "integer" }, "example": [ 0, 5, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150 ], "description": "[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)" }, "estimatedFoottraffic": { "type": "array", "items": { "type": "integer" }, "example": [ 0, 1099, 290496, 203518, 118502, 62588, 31487, 15440, 6029, 3405, 1877, 3602 ], "description": "Visits correlated with the same index in the dwell time bins array" }, "average": { "type": "integer", "example": 41, "description": "The average dwell time in the POI during the requested period" }, "median": { "type": "integer", "example": 34, "description": "The median dwell time in the POI during the requested period" }, "nearbyRadius": { "$ref": "#/components/schemas/NearbyRadius" } } } } }, { "$ref": "#/components/schemas/filtersAndVisitsDurationSegmentationResp" } ] }, "OpeningHoursList": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningHoursItem" }, "description": "The property\u2019s business opening hours on each day of the week." }, "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" } } }, "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" } ] }, "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" } } } ] }, "VisitTrendsResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VisitTrendsSuccess" } } } } ] }, "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) NOTE: When using the distance 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" } } } } } ] }, "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.
    By setting the parameter with a \u201cdefault\u201d value the report may be limited to certain visit durations (length of stay in minutes), to best reflect the typical behavior of visitors.
    Available values:
    \u2018under10Min\u2019 - Only visits with a duration of less than 10 minutes are included in the report.
    \u201810MinOrLonger\u2019 - only visits with a duration of 10 minutes or more are included in the report.
    \u2018allVisits\u2019 - all the visits are included in the report.
    \u2018default\u2019 - The default segment (as explained above)", "title": "Visit Duration Segmentation", "type": "string", "nullable": true, "enum": [ "under10Min", "10MinOrLonger", "allVisits", "default" ], "example": "10MinOrLonger", "default": "default" }, "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 \u2018mixedSegments\u2019.", "title": "Visit Duration Segmentation", "type": "string", "nullable": true, "enum": [ "under10Min", "10MinOrLonger", "allVisits", "mixedSegments" ], "example": "10MinOrLonger" }, "VisitHistoryRequest": { "title": "Visit History Request", "description": "Calculating ft trends for given dates", "allOf": [ { "$ref": "#/components/schemas/DatesIdParams" }, { "type": "object", "required": [ "granularity" ], "properties": { "granularity": { "type": "string", "enum": [ "day", "week", "month" ], "example": "month" }, "filters": { "$ref": "#/components/schemas/VmFilterObject" } } } ] }, "VisitHistoryResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseResponse" }, { "$ref": "#/components/schemas/VisitTrendsResponseNoPanel" } ] }, "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" } } } } } ] }, "UpdateCustomPoiRequest": { "title": "Update custom POI request", "description": "Updating <> by given name or sub category or polygon/centroid + radius or address.", "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "example": "complex:5f7a2d2dc2b5e82a0114cf62" } } }, { "$ref": "#/components/schemas/BaseCustomPoiRequest" } ] }, "AddTagMembersRequest": { "title": "Add tag members request", "type": "object", "required": [ "apiIds", "tagId" ], "properties": { "apiIds": { "type": "array", "description": "The list of entities to attach to the specified tag", "items": { "$ref": "#/components/schemas/ApiId" } }, "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807", "description": "The Id of the tag to attach the entities to" } } }, "AddEntitiesToTagResponseMultiStatus": { "title": "Add Entities to Tag Response Multi Status", "type": "object", "properties": { "data": { "type": "object", "properties": { "tagId": { "type": "string", "example": "672be20c36e1d0ff18a13807" } } }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ModifyTagEntitiesResponseSuccessItem" }, { "title": "Modify Tag Entities Response Failure", "type": "object", "properties": { "status": { "type": "string", "example": "FAILURE" }, "code": { "type": "integer", "example": 2002 }, "details": { "type": "string", "example": "INVALID_ARGUMENTS" }, "message": { "type": "string", "example": "The apiId cannot be added to the specified tag" }, "apiId": { "type": "string", "example": "venue:7d55054520e387813d764b03" } } } ] } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header" } } } }