{ "openapi": "3.0.1", "info": { "title": "Retail & Franchise Site Selection Intelligence", "description": "Find and rank underserved expansion zones for any retail or service business. Analyze direct and adjacent competitors, demand generators, transport access, and amenities. Export an auditable Excel report, interactive map, Dataset, JSON, and QGIS-ready GeoJSON layers.", "version": "1.0", "x-build-id": "2Msgb8sYxqcSVxlck" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/adinfosys-labs~retail-site-opportunity-finder/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-adinfosys-labs-retail-site-opportunity-finder", "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/adinfosys-labs~retail-site-opportunity-finder/runs": { "post": { "operationId": "runs-sync-adinfosys-labs-retail-site-opportunity-finder", "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/adinfosys-labs~retail-site-opportunity-finder/run-sync": { "post": { "operationId": "run-sync-adinfosys-labs-retail-site-opportunity-finder", "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", "required": [ "location_query", "business_category" ], "properties": { "location_query": { "title": "City or study area", "type": "string", "description": "A geocodable place such as Austin, Texas, USA.", "default": "Austin, Texas, USA" }, "business_category": { "title": "Business category", "enum": [ "pharmacy", "supermarket", "clinic", "coffee_shop", "gym", "ev_charging", "bank", "restaurant", "bakery", "hotel", "fuel_station", "custom" ], "type": "string", "description": "The business type whose expansion opportunities will be analyzed.", "default": "pharmacy" }, "analysis_mode": { "title": "Analysis mode", "enum": [ "discover_opportunity_zones", "compare_candidate_sites" ], "type": "string", "description": "Choose whether to discover and rank opportunity zones or compare user-supplied candidate sites.", "default": "discover_opportunity_zones" }, "search_radius_km": { "title": "Study radius (km)", "minimum": 1, "maximum": 25, "type": "number", "description": "Radius around the geocoded study-area centre.", "default": 5 }, "grid_cell_size_m": { "title": "Analysis cell size (m)", "minimum": 250, "maximum": 2500, "type": "integer", "description": "Smaller cells increase detail and runtime.", "default": 750 }, "catchment_radii_m": { "title": "Catchment radii (m)", "type": "array", "description": "Distances used for competitor and POI counts.", "items": { "type": "integer", "minimum": 100, "maximum": 20000 }, "default": [ 1000, 3000, 5000 ] }, "top_n": { "title": "Recommended zones", "minimum": 1, "maximum": 50, "type": "integer", "description": "Number of top-ranked zones highlighted in reports.", "default": 10 }, "candidate_sites": { "title": "Candidate sites (optional)", "type": "array", "description": "Optional named addresses or coordinates for comparison mode.", "items": { "type": "object", "properties": { "id": { "title": "Site ID", "type": "string", "description": "Unique identifier for the candidate site." }, "name": { "title": "Site name", "type": "string", "description": "Human-readable candidate-site name." }, "address": { "title": "Site address", "type": "string", "description": "Address to geocode when coordinates are not supplied." }, "latitude": { "title": "Latitude", "type": "number", "description": "Candidate-site latitude in WGS84 decimal degrees.", "minimum": -90, "maximum": 90 }, "longitude": { "title": "Longitude", "type": "number", "description": "Candidate-site longitude in WGS84 decimal degrees.", "minimum": -180, "maximum": 180 } }, "required": [ "id", "name" ] }, "default": [] }, "custom_osm_tags": { "title": "Custom primary competitor tags", "type": "array", "description": "Required only for the custom business category, for example [{\"key\":\"shop\",\"value\":\"bakery\"}].", "items": { "type": "object", "properties": { "key": { "title": "OSM key", "type": "string", "description": "OpenStreetMap tag key." }, "value": { "title": "OSM value", "type": "string", "description": "OpenStreetMap tag value." } }, "required": [ "key", "value" ] }, "default": [] }, "custom_fallback_tags": { "title": "Custom adjacent competitor tags", "type": "array", "description": "Broader competitor definition collected independently on every run. Tags already listed as primary are removed; remaining matches are adjacent competitors.", "items": { "type": "object", "properties": { "key": { "title": "OSM key", "type": "string", "description": "OpenStreetMap tag key." }, "value": { "title": "OSM value", "type": "string", "description": "Optional OpenStreetMap tag value; omit it to match any value for the key." } }, "required": [ "key" ] }, "default": [] }, "adjacent_competitor_weight": { "title": "Adjacent competitor weight", "minimum": 0, "maximum": 1, "type": "number", "description": "Relative competition impact of adjacent businesses collected independently from direct competitors. Direct competitors always have weight 1.0.", "default": 0.4 }, "custom_demand_generators": { "title": "Custom demand-generator groups", "type": "object", "description": "Named groups with role (primary_demand, transport, or support) and OSM tags. Legacy tag-list groups remain accepted.", "default": {} }, "weights": { "title": "Opportunity-score weights", "type": "object", "description": "Advanced setting. Values must sum to 1.0.", "default": { "competition_gap": 0.4, "demand_proxy": 0.25, "transport_access": 0.2, "amenity_support": 0.15 } }, "basemap_url": { "title": "Basemap tile URL", "type": "string", "description": "Advanced setting. HTTPS raster-tile template containing {z}, {x}, and {y}. Provider terms and attribution remain the user's responsibility.", "default": "https://tile.openstreetmap.org/{z}/{x}/{y}.png" }, "basemap_attribution": { "title": "Basemap attribution", "type": "string", "description": "Visible attribution required by the selected basemap provider.", "default": "© OpenStreetMap contributors" }, "business_economics": { "title": "Business economics (optional)", "type": "object", "description": "Financial assumptions used to test candidate-property rent affordability.", "default": { "projected_monthly_sales_amd": 0, "target_occupancy_cost_ratio": 0.12, "monthly_other_occupancy_costs_amd": 0, "gross_margin_rate": 0.35 } }, "candidate_properties": { "title": "Candidate commercial properties (optional)", "type": "array", "description": "User-verified listings to evaluate against the top opportunity zone and business economics.", "items": { "type": "object", "properties": { "property_id": { "title": "Property ID", "type": "string", "description": "Unique identifier for the property listing." }, "address": { "title": "Property address", "type": "string", "description": "Street address of the candidate property." }, "latitude": { "title": "Latitude", "type": "number", "description": "Property latitude in WGS84 decimal degrees.", "minimum": -90, "maximum": 90 }, "longitude": { "title": "Longitude", "type": "number", "description": "Property longitude in WGS84 decimal degrees.", "minimum": -180, "maximum": 180 }, "area_sqm": { "title": "Area (sqm)", "type": "number", "description": "Usable property area in square metres.", "minimum": 0.01 }, "monthly_rent_amd": { "title": "Monthly rent (AMD)", "type": "number", "description": "Advertised monthly rent in Armenian drams.", "minimum": 0 }, "floor": { "title": "Floor", "type": "integer", "description": "Floor number of the commercial unit.", "default": 1 }, "street_entrance": { "title": "Street entrance", "type": "boolean", "description": "Whether the unit has a direct street entrance.", "default": false }, "frontage_m": { "title": "Frontage (m)", "type": "number", "description": "Approximate street frontage in metres.", "minimum": 0 }, "parking_available": { "title": "Parking available", "type": "boolean", "description": "Whether customer parking is available.", "default": false }, "verified_listing": { "title": "Verified listing", "type": "boolean", "description": "Whether the listing details were independently checked.", "default": false }, "active_listing": { "title": "Active listing", "type": "boolean", "description": "Whether the property is currently advertised as available.", "default": false }, "demonstration_only": { "title": "Demonstration only", "type": "boolean", "description": "Marks fictional or portfolio-only example data.", "default": false }, "listing_url": { "title": "Listing URL", "type": "string", "description": "Source URL for the property listing." }, "listing_checked_at": { "title": "Listing checked at", "type": "string", "description": "Date or timestamp when listing availability was checked." } }, "required": [ "property_id", "latitude", "longitude", "area_sqm", "monthly_rent_amd" ] }, "default": [] }, "property_comparable_rules": { "title": "Market-comparable eligibility rules", "type": "object", "description": "Strict filters used only for the market rent benchmark. Rejected listings remain visible with exclusion reasons.", "properties": { "radius_m": { "title": "Comparable radius (m)", "type": "number", "description": "Maximum distance from the top zone for an eligible comparable.", "minimum": 100, "maximum": 10000 }, "minimum_area_sqm": { "title": "Minimum area (sqm)", "type": "number", "description": "Minimum eligible comparable-property area.", "minimum": 0.01 }, "maximum_area_sqm": { "title": "Maximum area (sqm)", "type": "number", "description": "Maximum eligible comparable-property area.", "minimum": 0.01 }, "minimum_comparables": { "title": "Minimum comparables", "type": "integer", "description": "Minimum eligible listings required to calculate a market-rent median.", "minimum": 1, "maximum": 20 }, "require_first_floor": { "title": "Require first floor", "type": "boolean", "description": "Exclude listings that are not on the first floor." }, "require_street_entrance": { "title": "Require street entrance", "type": "boolean", "description": "Exclude listings without a direct street entrance." } }, "default": { "radius_m": 1500, "minimum_area_sqm": 50, "maximum_area_sqm": 250, "minimum_comparables": 3, "require_first_floor": true, "require_street_entrance": true } }, "output_formats": { "title": "Output formats", "type": "array", "description": "Dataset is always produced; select additional export formats.", "items": { "type": "string", "enum": [ "dataset", "xlsx", "geojson", "json" ] }, "default": [ "dataset", "xlsx", "geojson", "json" ] } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }