{ "openapi": "3.0.1", "info": { "title": "Foot Traffic Data API - Visits, Trade Area, Demographics", "description": "Get foot traffic data for any US retail location, shopping center or chain: visits and unique visitors, trends by day, week or month, dwell time, visitor loyalty, the true trade area polygon, trade area demographics, where else those visitors shop, rankings against competitors, and retail sales.", "version": "0.1", "x-build-id": "6hKF3d7lao5phNb11" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~foot-traffic-data-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-foot-traffic-data-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nabeelbaghoor~foot-traffic-data-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-foot-traffic-data-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nabeelbaghoor~foot-traffic-data-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-foot-traffic-data-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "What to do", "enum": [ "entitySearch", "subEntities", "myProperties", "visitMetrics", "visitTrends", "visitsByDay", "visitsByHour", "dwellTime", "visitsByBlockGroup", "loyalty", "tradeArea", "tradeAreaDriveTime", "tradeAreaDemographics", "favoriteChains", "favoritePlaces", "rankingOverview", "topRanked", "closelyRanked", "retailSalesOverview", "retailSalesTrends", "accountUsage" ], "type": "string", "description": "Entity search finds the provider's identifier for a place, a shopping centre or a chain, and every other mode starts there. The visit modes count and break down traffic. Trade area draws where the visitors came from and demographics profiles who lives there. Visitor journey lists where else those visitors go. Ranking places the venue against its category, chain or neighbours. Retail sales reads spend.", "default": "entitySearch" }, "apiIds": { "title": "Entity IDs", "type": "array", "description": "One entity ID per line in the provider's own spelling, for example venue:4ea4f76f1f766e7bbdeccd61. This is the apiId column from entity search, not the bare entityId. Visit metrics, visit trends and block groups take up to 100 per request; every other report reads them one at a time.", "items": { "type": "string" } }, "entityName": { "title": "Place or chain name", "type": "string", "description": "Entity search: text that appears in the place's name, for example Walmart or Chuck E Cheese." }, "latitude": { "title": "Latitude", "type": "string", "description": "Entity search: decimal latitude of the point to search around. Must be paired with a longitude." }, "longitude": { "title": "Longitude", "type": "string", "description": "Entity search: decimal longitude of the point to search around. A point search returns venues and complexes but never chains." }, "radiusMiles": { "title": "Search radius in miles", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Entity search: how far around the point to look, from 0.01 to 2000 miles. The provider's own default is 0.01 miles, which is about fifty feet and finds almost nothing, so this actor uses 1 mile when you leave it blank." }, "groupCategory": { "title": "Group category", "type": "string", "description": "Entity search: the business domain, for example Dining, Apparel or Grocery." }, "category": { "title": "Category", "type": "string", "description": "Entity search: the category within a group, for example Fast Food & QSR." }, "subCategory": { "title": "Sub-category", "type": "string", "description": "Entity search: the narrowest classification, for example Pizza Place." }, "entityTypes": { "title": "Entity types", "type": "array", "description": "Entity search: which kinds of entity to return. Leave empty for all three. A venue is one location, a complex is a mall or centre, and a chain is every location of a brand.", "items": { "type": "string", "enum": [ "venue", "complex", "chain" ], "enumTitles": [ "Venue", "Complex", "Chain" ] } }, "includeFlaggedEntities": { "title": "Include flagged entities", "type": "boolean", "description": "Entity search: also return entities the provider has flagged. Flagged entities are returned with a flag column but the provider will not produce reports for them, so this is useful for auditing rather than for building a report list.", "default": false }, "startDate": { "title": "Start date", "type": "string", "description": "First day of the window to report on, written as YYYY-MM-DD. Required by every report mode." }, "endDate": { "title": "End date", "type": "string", "description": "Last day of the window to report on, written as YYYY-MM-DD." }, "granularity": { "title": "Trend granularity", "enum": [ "day", "week", "month", "year" ], "type": "string", "description": "Visit trends and block groups: the size of each bin. A daily trend over a long window is the slowest report on this API.", "default": "month" }, "visitDurationSegmentation": { "title": "Visit length segment", "enum": [ "", "default", "under10Min", "10MinOrLonger", "allVisits" ], "type": "string", "description": "Which visits to count. The provider's default picks a segment per venue that reflects how people normally use it, and a chain whose venues use different defaults reports back as mixed.", "default": "" }, "audienceTypes": { "title": "Audience", "type": "array", "description": "Count only these kinds of people. Leave empty to count everyone. Employees and residents are usually excluded from a retail traffic read, because a member of staff visits every working day.", "items": { "type": "string", "enum": [ "visitors", "employees", "residents" ], "enumTitles": [ "Visitors", "Employees", "Residents" ] } }, "dwellTimeFilter": { "title": "Dwell time filter", "type": "string", "description": "Count only visits of a certain length, written as \">=10\" or \"<150\" in minutes. The provider accepts only those two operators, so \">\" is read as \">=\" and \"<=\" as \"<\" rather than being rejected." }, "daysOfWeek": { "title": "Days of week", "type": "array", "description": "Count only visits on these days. Monday is 1 and Sunday is 7, so a weekend read is 6 and 7.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7" ], "enumTitles": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] } }, "fromHour": { "title": "From hour", "type": "string", "description": "Count only visits from this hour onwards, written as \"08:00 am\". The provider needs both ends of the range, so a from hour without a to hour is dropped rather than sent." }, "toHour": { "title": "To hour", "type": "string", "description": "Count only visits up to this hour, written as \"11:59 pm\"." }, "distanceFilter": { "title": "Distance from home or work", "type": "string", "description": "Count only visits from within a distance in miles, written as \"10-250\", \">=10\" or \"<=100\". Note that the provider applies this to the extrapolated visits and NOT to the panel counts, so on a filtered run the two stop being comparable and every row is flagged accordingly." }, "distanceFrom": { "title": "Measure distance from", "enum": [ "home", "work" ], "type": "string", "description": "Whether the distance filter measures from the visitor's home or their work.", "default": "home" }, "nearbyRadiusFeet": { "title": "Nearby activity radius", "enum": [ "", "100", "250", "500", "750", "1000" ], "type": "string", "description": "Switch the report to nearby activity, measuring traffic passing within this many feet rather than visits to the place itself. Note that setting this collapses a bulk request to its first entity only, so it is left off bulk modes.", "default": "" }, "tradeAreaMethod": { "title": "Trade area method", "enum": [ "tta", "driveTime", "mileRing" ], "type": "string", "description": "Demographics only: how the trade area is drawn. True trade area uses the block groups the visitors actually came from, drive time uses a travel time ring, and mile ring uses a plain radius. Each needs its own sizing input and ignores the other two.", "default": "tta" }, "trafficVolumePercent": { "title": "Traffic volume threshold", "minimum": 1, "maximum": 100, "type": "integer", "description": "What share of the visits the trade area polygon must enclose. Setting 70 draws a shape covering at least 70 percent of the traffic. The two endpoints accept different ranges, 30 to 100 for the trade area and 1 to 99 for demographics, so the value is held inside whichever applies." }, "allocationType": { "title": "Block group allocation", "enum": [ "weightedCentroid", "centroid" ], "type": "string", "description": "How a census block group is judged to be inside the trade area. Weighted centroid moves the centroid towards where the block group's population actually lives, which is the better default in a block group with a lake or a park in it.", "default": "weightedCentroid" }, "withinDistanceMiles": { "title": "Maximum home distance", "minimum": 1, "maximum": 300, "type": "integer", "description": "Exclude visitors living further than this from the place, in miles. Keeps a tourist destination's trade area from stretching across the country." }, "driveTimeMinutes": { "title": "Drive time in minutes", "minimum": 1, "maximum": 200, "type": "integer", "description": "Drive time trade area: the travel time ring to draw, from 5 to 200 minutes." }, "ringRadiusMiles": { "title": "Mile ring radius", "minimum": 1, "maximum": 250, "type": "integer", "description": "Demographics with the mile ring method: the plain radius to profile, from 0.2 to 250 miles." }, "benchmarkScope": { "title": "Demographics benchmark", "enum": [ "nationwide", "state" ], "type": "string", "description": "Whether the demographic profile is indexed against the whole country or against the state.", "default": "nationwide" }, "demographicsAudience": { "title": "Demographics audience", "enum": [ "potential", "captured" ], "type": "string", "description": "Potential profiles everyone living in the trade area. Captured profiles only the block groups that actually sent visitors, which is a smaller and more flattering number.", "default": "potential" }, "demographicsDataset": { "title": "Demographics data set", "enum": [ "census", "sti_popstats", "sti_landscape", "sti_market_outlook", "sti_spending_patterns", "sti_workplace", "spatial_ai_personalive", "spatial_ai_followgraph" ], "type": "string", "description": "Which third-party data set to profile with. Access is per data set, and a set your plan does not include is refused rather than returned empty.", "default": "census" }, "journeyCategories": { "title": "Visitor journey categories", "type": "array", "description": "Visitor journey: restrict the other places those visitors go to these categories, one per line. Leave empty for every category.", "items": { "type": "string" } }, "minimalVisitFrequency": { "title": "Minimum visits elsewhere", "minimum": 0, "maximum": 99, "type": "integer", "description": "Visitor journey: how often a visitor must have gone to the other place for it to count, from 0 to 99." }, "journeyLimit": { "title": "Visitor journey results", "minimum": 1, "maximum": 50, "type": "integer", "description": "Visitor journey: how many destinations to return, up to 50." }, "rankingPeriod": { "title": "Ranking period", "enum": [ "", "lastWeek", "lastMonth", "lastQuarter", "last3Months", "last6Months", "last12Months", "yearToDate" ], "type": "string", "description": "A named window for a ranking. The provider refuses a request carrying both a named period and explicit dates, so setting this drops the start and end dates rather than sending both.", "default": "" }, "rankingScope": { "title": "Ranking scope", "enum": [ "category", "chain", "groupCategory" ], "type": "string", "description": "What the place is ranked against: the other locations of its own chain, the other places in its category, or the whole business domain.", "default": "category" }, "rankingMetric": { "title": "Ranking metric", "enum": [ "visits", "visitsPerSqft" ], "type": "string", "description": "Rank on raw visits, or on visits per square foot, which is the fairer comparison between a big box and a kiosk.", "default": "visits" }, "rankingRegion": { "title": "Ranking region", "enum": [ "5", "10", "15", "30", "50", "nationwide", "state", "dma", "cbsa" ], "type": "string", "description": "Top ranked and closely ranked: the geography to rank inside. A number is a radius in miles around the place; the rest are administrative areas.", "default": "15" }, "rankingDistanceMiles": { "title": "Ranking overview radius", "enum": [ "", "5", "10", "15", "30", "50" ], "type": "string", "description": "Ranking overview: the radius in miles used for the local rank, alongside the nationwide, state, DMA and CBSA ranks it always returns.", "default": "" }, "rankingLimit": { "title": "Ranking index results", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Top ranked and closely ranked: how many neighbouring venues to return, up to 1000." }, "cbgTrafficVolumePercent": { "title": "Block group traffic threshold", "enum": [ "", "70", "100" ], "type": "string", "description": "Visits by block group: whether to list the block groups covering 70 percent of the traffic or all of it.", "default": "" }, "maxResults": { "title": "Maximum rows", "minimum": 1, "type": "integer", "description": "Stop after this many rows. Each row is one charged result, so this is the ceiling on what a run can cost.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 600, "type": "integer", "description": "How fast to call the provider. The published ceiling is ten calls a second with five concurrent processes, and a rate limit response is honoured with the wait the provider publishes.", "default": 120 }, "baseUrl": { "title": "API base URL", "type": "string", "description": "Only set this if the provider has given you a different host. Leave blank for the standard one." }, "apiKey": { "title": "API key", "type": "string", "description": "Your own location intelligence API key. API access needs a paying account with the API add-on enabled; your customer success manager issues the key. Leave blank to use the DATA_API_KEY environment secret instead." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }