# Franchise Direct Scraper (`crawlerbros/franchise-direct-scraper`) Actor

Scrape FranchiseDirect.com franchise opportunity listings. Browse by industry, filter by investment range, filter by country or US state, or pull curated Top / New franchise lists.

- **URL**: https://apify.com/crawlerbros/franchise-direct-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Lead generation, Automation, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Franchise Direct Scraper

Scrape **FranchiseDirect.com** — one of the largest online franchise opportunity directories, covering thousands of brands across food, retail, home services, automotive, and more. Search by keyword, browse by industry category or curated collection (low-cost, home-based, veteran-friendly, master franchise, and more), filter by investment range, or drill into a specific US state or one of 190+ countries. No login, no API key, no cookies required.

### What this actor does

- **Four modes:** `search` (keyword + industry + location + investment filters), `topFranchises`, `newFranchises`, and `collection` (17 curated editorial lists)
- **Real industry taxonomy:** 36 official FranchiseDirect industry categories
- **Real location taxonomy:** every US state plus 190+ countries
- **Investment filtering:** cap results by minimum required investment, from under $10,000 up to under $500,000
- **Optional deep enrichment:** fetch each franchise's full profile page for financials, business type, training, home-based status, and financing assistance
- **Empty fields are omitted** — every record only contains what was actually found

### Output per franchise

- `name` — franchise brand name
- `tagline` — short marketing headline from the profile page (when `fetchDetails=true`)
- `shortDescription` — one-paragraph summary shown on the listing card
- `description` — full profile overview text (when `fetchDetails=true`)
- `category` — human-readable industry category (when `fetchDetails=true`)
- `categoryPathSlug` — industry path segment derived from the listing URL
- `minInvestment` — minimum cash required, as a number
- `minInvestmentDisplay` — minimum cash required, formatted (e.g. `$125,000`)
- `franchiseFee` — franchise fee, or fee tiers if the brand offers multiple options (when `fetchDetails=true`)
- `totalInvestmentRange` — total estimated investment range (when `fetchDetails=true`)
- `requiredNetWorth` — minimum net worth requirement (when `fetchDetails=true` and disclosed)
- `royaltyFee` — ongoing royalty fee/structure (when `fetchDetails=true` and disclosed)
- `supportFees` — ongoing support fee, if disclosed separately from royalties (when `fetchDetails=true` and disclosed)
- `territoryRestrictions` — territory/exclusivity terms, if disclosed (when `fetchDetails=true` and disclosed)
- `businessType` — e.g. `Franchise`, `Business Opportunity` (when `fetchDetails=true`)
- `trainingProvided` — boolean (when `fetchDetails=true` and disclosed)
- `homeBased` — boolean (when `fetchDetails=true` and disclosed)
- `financingAssistance` — e.g. `3rd Party`, `In-House` (when `fetchDetails=true` and disclosed)
- `availableLocations` — text describing where the franchise is currently offered (when `fetchDetails=true`)
- `businessStatus` — franchise listing status, e.g. `open` (when `fetchDetails=true`)
- `franchiseId` — FranchiseDirect's internal listing ID (when `fetchDetails=true`)
- `testimonials[]` — franchisee quotes with attribution, when the profile page publishes any (when `fetchDetails=true`)
- `logoUrl` — franchise logo image URL
- `profileUrl` / `sourceUrl` — canonical FranchiseDirect profile page URL
- `recordType: "franchise"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `topFranchises` / `newFranchises` / `collection` |
| `searchQuery` | string | `food` | Free-text keyword (mode=search) |
| `industry` | string (enum) | `food-franchises` | Browse by industry category (mode=search) |
| `location` | string (enum) | `any` | Filter by US state or country (mode=search) |
| `investmentTier` | string (enum) | `any` | Cap results to franchises under this investment amount |
| `collection` | string (enum) | `lowCostFranchises` | Which curated editorial list to pull (mode=collection) |
| `homeBasedOnly` | boolean | `false` | Only keep confirmed home-based opportunities (requires `fetchDetails=true`) |
| `fetchDetails` | boolean | `true` | Also fetch each franchise's profile page for a fuller record |
| `maxItems` | integer | `20` | Hard cap on emitted records (1–200) |

### Examples

#### Example: browse the food industry, low investment

```json
{
  "mode": "search",
  "industry": "food-franchises",
  "investmentTier": "100000",
  "maxItems": 30
}
````

#### Example: keyword search across all industries

```json
{
  "mode": "search",
  "searchQuery": "cleaning",
  "maxItems": 20
}
```

#### Example: franchises available in California

```json
{
  "mode": "search",
  "location": "california",
  "maxItems": 25
}
```

#### Example: curated low-cost franchise list

```json
{
  "mode": "collection",
  "collection": "lowCostFranchises",
  "maxItems": 20
}
```

### Use cases

- **Franchise brokers & consultants** — build a searchable database of current opportunities for clients
- **Market research** — track investment ranges and new brand launches across an industry
- **Lead generation** — surface franchise opportunities matching a specific budget or region
- **Franchise development teams** — monitor competitor listings and positioning
- **Investment analysis** — compare minimum cash requirements and total investment ranges across brands

### FAQ

**Is this affiliated with FranchiseDirect.com?**
No. This is an independent, third-party actor that reads FranchiseDirect's public listing pages. It is not affiliated with or endorsed by FranchiseDirect.

**Do I need an account or API key?**
No. All data comes from FranchiseDirect's public browse and search pages, which require no login.

**Why do some franchises have fewer fields than others?**
Franchise brands disclose different amounts of information on their profile pages. Fields like `franchiseFee`, `homeBased`, or `trainingProvided` are only included when the brand's page actually discloses them — the actor never fabricates or fills in placeholder values.

**Can I combine industry, location, and investment filters at once?**
The actor navigates by one primary filter at a time (location takes priority, then industry, then keyword, then investment tier) since that is how FranchiseDirect's own site reliably filters results. Any investment cap and keyword you also provide are then applied as an additional check on top of the primary filter's results, so combining them still narrows your results correctly. Combining `industry` and `location` together is not currently supported since FranchiseDirect does not expose a single reliable page for that combination.

**What does `homeBasedOnly` require?**
Home-based status is only disclosed on each franchise's profile page, so `homeBasedOnly` only takes effect when `fetchDetails` is also enabled.

**How fresh is the data?**
Each run fetches live pages directly from FranchiseDirect.com at request time — there is no caching.

**What are the curated collections?**
FranchiseDirect maintains editorial lists such as Low Cost Franchises, Home Based Franchises, Master Franchises, and Franchises for Veterans. The `collection` mode pulls directly from these lists.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `searchQuery` (type: `string`):

Free-text keyword (mode=search), e.g. a franchise name or niche like `pizza` or `cleaning`. If `industry` or `location` is also set, FranchiseDirect's own search only reliably filters by one axis server-side, so results are navigated by industry/location first and the keyword is then applied as a relevance check on top.

## `industry` (type: `string`):

Browse by FranchiseDirect's real industry taxonomy (mode=search).

## `location` (type: `string`):

Filter by country or US state, using FranchiseDirect's own location taxonomy (mode=search). Takes priority over `industry`/`searchQuery` for navigation since it is the most reliable single-axis browse path on the site. Note: FranchiseDirect's own filter uses one shared value for the US state of Georgia and the country of Georgia.

## `investmentTier` (type: `string`):

Filter to franchises whose minimum investment is at or under this amount. Applied both as the primary browse axis (when no location/industry/keyword is set) and as a client-side cap on every other mode, using each franchise's actual minimum-investment figure.

## `collection` (type: `string`):

Which curated collection page to pull (mode=collection only) — FranchiseDirect's own editorial lists such as low-cost, home-based, veteran-friendly, or master franchises.

## `homeBasedOnly` (type: `boolean`):

Only keep franchises whose profile page confirms a home-based business model. Requires `fetchDetails=true` to take effect (home-based status is only available on the profile page, not the listing card).

## `fetchDetails` (type: `boolean`):

Also fetch each franchise's profile page for a fuller record (financials, business type, training, home-based, financing). Roughly doubles request count.

## `maxItems` (type: `integer`):

Hard cap on emitted records. FranchiseDirect renders ~12-13 results per filter combination without a browser; widen filters or run several categories to collect more.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "food",
  "industry": "food-franchises",
  "location": "any",
  "investmentTier": "any",
  "collection": "lowCostFranchises",
  "homeBasedOnly": false,
  "fetchDetails": true,
  "maxItems": 20
}
```

# Actor output Schema

## `franchises` (type: `string`):

Dataset containing all scraped FranchiseDirect franchise opportunities.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "searchQuery": "food",
    "industry": "food-franchises",
    "location": "any",
    "investmentTier": "any",
    "collection": "lowCostFranchises",
    "homeBasedOnly": false,
    "fetchDetails": true,
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/franchise-direct-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "searchQuery": "food",
    "industry": "food-franchises",
    "location": "any",
    "investmentTier": "any",
    "collection": "lowCostFranchises",
    "homeBasedOnly": False,
    "fetchDetails": True,
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/franchise-direct-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "searchQuery": "food",
  "industry": "food-franchises",
  "location": "any",
  "investmentTier": "any",
  "collection": "lowCostFranchises",
  "homeBasedOnly": false,
  "fetchDetails": true,
  "maxItems": 20
}' |
apify call crawlerbros/franchise-direct-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/franchise-direct-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Franchise Direct Scraper",
        "description": "Scrape FranchiseDirect.com franchise opportunity listings. Browse by industry, filter by investment range, filter by country or US state, or pull curated Top / New franchise lists.",
        "version": "1.0",
        "x-build-id": "AFcnqU6LdsO7dfA6d"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/crawlerbros~franchise-direct-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-crawlerbros-franchise-direct-scraper",
                "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/crawlerbros~franchise-direct-scraper/runs": {
            "post": {
                "operationId": "runs-sync-crawlerbros-franchise-direct-scraper",
                "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/crawlerbros~franchise-direct-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-crawlerbros-franchise-direct-scraper",
                "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": [
                    "mode"
                ],
                "properties": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "search",
                            "topFranchises",
                            "newFranchises",
                            "collection"
                        ],
                        "type": "string",
                        "description": "What to fetch.",
                        "default": "search"
                    },
                    "searchQuery": {
                        "title": "Keyword search",
                        "type": "string",
                        "description": "Free-text keyword (mode=search), e.g. a franchise name or niche like `pizza` or `cleaning`. If `industry` or `location` is also set, FranchiseDirect's own search only reliably filters by one axis server-side, so results are navigated by industry/location first and the keyword is then applied as a relevance check on top.",
                        "default": "food"
                    },
                    "industry": {
                        "title": "Industry category",
                        "enum": [
                            "any",
                            "accounting-financial-franchises",
                            "advertising-marketing-franchises",
                            "automotive-franchises",
                            "business-opportunities",
                            "business-services-franchises",
                            "childrens-franchises",
                            "cleaning-franchises",
                            "coffee-franchises",
                            "computer-internet-franchises",
                            "consultant-business-broker-franchises",
                            "courier-franchises",
                            "employment-staffing-franchises",
                            "entertainment-franchises",
                            "fitness-franchises",
                            "food-franchises",
                            "franchise-service-providers",
                            "golf-franchises",
                            "health-beauty-franchises",
                            "healthcare-senior-care-franchises",
                            "home-based-franchises",
                            "home-services-franchises",
                            "industrial-franchises",
                            "mailing-shipping-franchises",
                            "moving-storage-franchises",
                            "pet-franchises",
                            "photography-franchises",
                            "post-covid-franchises",
                            "printer-copying-sign-franchises",
                            "real-estate-franchises",
                            "restaurant-franchises",
                            "retail-franchises",
                            "sports-franchises",
                            "tax-franchises",
                            "training-franchises",
                            "travel-franchises",
                            "vending-atm-franchises"
                        ],
                        "type": "string",
                        "description": "Browse by FranchiseDirect's real industry taxonomy (mode=search).",
                        "default": "food-franchises"
                    },
                    "location": {
                        "title": "Country / US state",
                        "enum": [
                            "any",
                            "alabama",
                            "alaska",
                            "arizona",
                            "arkansas",
                            "california",
                            "colorado",
                            "connecticut",
                            "delaware",
                            "district-of-columbia",
                            "florida",
                            "georgia",
                            "hawaii",
                            "idaho",
                            "illinois",
                            "indiana",
                            "iowa",
                            "kansas",
                            "kentucky",
                            "louisiana",
                            "maine",
                            "maryland",
                            "massachusetts",
                            "michigan",
                            "minnesota",
                            "mississippi",
                            "missouri",
                            "montana",
                            "nebraska",
                            "nevada",
                            "new-hampshire",
                            "new-jersey",
                            "new-mexico",
                            "new-york",
                            "north-carolina",
                            "north-dakota",
                            "ohio",
                            "oklahoma",
                            "oregon",
                            "pennsylvania",
                            "rhode-island",
                            "south-carolina",
                            "south-dakota",
                            "tennessee",
                            "texas",
                            "utah",
                            "vermont",
                            "virginia",
                            "washington",
                            "west-virginia",
                            "wisconsin",
                            "wyoming",
                            "afghanistan",
                            "albania",
                            "algeria",
                            "american-samoa",
                            "andorra",
                            "angola",
                            "anguilla",
                            "antigua-barbuda",
                            "argentina",
                            "armenia",
                            "aruba",
                            "australia",
                            "austria",
                            "azerbaijan",
                            "bahamas",
                            "bahrain",
                            "bangladesh",
                            "barbados",
                            "belarus",
                            "belgium",
                            "belize",
                            "benin",
                            "bermuda",
                            "bhutan",
                            "bolivia",
                            "bosnia-and-herzegovina",
                            "botswana",
                            "brazil",
                            "brunei-darussalam",
                            "bulgaria",
                            "burkina-faso",
                            "burundi",
                            "cambodia",
                            "cameroon",
                            "canada",
                            "cape-verde",
                            "cayman-islands",
                            "central-african-republic",
                            "chad",
                            "chile",
                            "china",
                            "christmas-island",
                            "cocos-islands",
                            "colombia",
                            "comoros",
                            "congo",
                            "cook-islands",
                            "coral-sea-islands",
                            "costa-rica",
                            "croatia",
                            "cuba",
                            "cyprus",
                            "czech-republic",
                            "democratic-republic-congo",
                            "denmark",
                            "djibouti",
                            "dominica",
                            "dominican-republic",
                            "east-timor",
                            "ecuador",
                            "egypt",
                            "el-salvador",
                            "equatorial-guinea",
                            "eritrea",
                            "estonia",
                            "ethiopia",
                            "falkland-islands",
                            "faroe-islands",
                            "fiji",
                            "finland",
                            "france",
                            "french-guiana",
                            "french-polynesia",
                            "gabon",
                            "gambia",
                            "gaza",
                            "germany",
                            "ghana",
                            "gibraltar",
                            "greece",
                            "greenland",
                            "grenada",
                            "guadeloupe",
                            "guam",
                            "guatemala",
                            "guinea",
                            "guinea-bissau",
                            "guyana",
                            "haiti",
                            "honduras",
                            "hong-kong",
                            "hungary",
                            "iceland",
                            "india",
                            "indonesia",
                            "iran",
                            "iraq",
                            "ireland",
                            "israel",
                            "italy",
                            "ivory-coast",
                            "jamaica",
                            "japan",
                            "jordan",
                            "kazakhstan",
                            "kenya",
                            "kiribati",
                            "kosovo",
                            "kuwait",
                            "kyrgyzstan",
                            "laos",
                            "latvia",
                            "lebanon",
                            "lesotho",
                            "liberia",
                            "libya",
                            "liechtenstein",
                            "lithuania",
                            "luxembourg",
                            "macau",
                            "madagascar",
                            "malawi",
                            "malaysia",
                            "maldives",
                            "mali",
                            "malta",
                            "marshall-islands",
                            "martinique",
                            "mauritania",
                            "mauritius",
                            "mexico",
                            "micronesia",
                            "moldova",
                            "monaco",
                            "mongolia",
                            "montenegro",
                            "montserrat",
                            "morocco",
                            "mozambique",
                            "myanmar",
                            "namibia",
                            "nauru",
                            "nepal",
                            "netherlands",
                            "netherlands-antilles",
                            "new-caledonia",
                            "new-zealand",
                            "nicaragua",
                            "niger",
                            "nigeria",
                            "niue",
                            "norfolk-island",
                            "northern-mariana-islands",
                            "north-korea",
                            "north-macedonia",
                            "norway",
                            "oman",
                            "pakistan",
                            "palau",
                            "panama",
                            "papua-new-guinea",
                            "paraguay",
                            "peru",
                            "philippines",
                            "pitcairn-island",
                            "poland",
                            "portugal",
                            "puerto-rico",
                            "qatar",
                            "reunion",
                            "romania",
                            "russia",
                            "rwanda",
                            "saint-helena-ascension-tristan-cunha",
                            "saint-kitts-nevis",
                            "saint-lucia",
                            "saint-pierre-and-miquelon",
                            "saint-vincent-grenadines",
                            "samoa",
                            "san-marino",
                            "sao-tome-principe",
                            "saudi-arabia",
                            "senegal",
                            "serbia",
                            "seychelles",
                            "sierra-leone",
                            "singapore",
                            "slovakia",
                            "slovenia",
                            "solomon-islands",
                            "somalia",
                            "south-africa",
                            "south-korea",
                            "spain",
                            "sri-lanka",
                            "sudan",
                            "suriname",
                            "swaziland",
                            "sweden",
                            "switzerland",
                            "syrian-arab-republic",
                            "taiwan",
                            "tajikistan",
                            "tanzania",
                            "thailand",
                            "togo",
                            "tokelau",
                            "tonga",
                            "trinidad-tobago",
                            "tunisia",
                            "turkey",
                            "turkmenistan",
                            "turks-caicos-islands",
                            "tuvalu",
                            "uganda",
                            "ukraine",
                            "united-arab-emirates",
                            "united-kingdom",
                            "unitedstatesofamerica",
                            "uruguay",
                            "us-outlying-islands",
                            "uzbekistan",
                            "vanuatu",
                            "venezuela",
                            "viet-nam",
                            "virgin-islands-british",
                            "virgin-islands-us",
                            "wake-islands",
                            "wallis-futuna",
                            "west-bank",
                            "western-sahara",
                            "yemen",
                            "zambia",
                            "zimbabwe"
                        ],
                        "type": "string",
                        "description": "Filter by country or US state, using FranchiseDirect's own location taxonomy (mode=search). Takes priority over `industry`/`searchQuery` for navigation since it is the most reliable single-axis browse path on the site. Note: FranchiseDirect's own filter uses one shared value for the US state of Georgia and the country of Georgia.",
                        "default": "any"
                    },
                    "investmentTier": {
                        "title": "Investment range (max)",
                        "enum": [
                            "any",
                            "10000",
                            "20000",
                            "30000",
                            "40000",
                            "50000",
                            "60000",
                            "70000",
                            "80000",
                            "90000",
                            "100000",
                            "200000",
                            "300000",
                            "400000",
                            "500000"
                        ],
                        "type": "string",
                        "description": "Filter to franchises whose minimum investment is at or under this amount. Applied both as the primary browse axis (when no location/industry/keyword is set) and as a client-side cap on every other mode, using each franchise's actual minimum-investment figure.",
                        "default": "any"
                    },
                    "collection": {
                        "title": "Curated collection",
                        "enum": [
                            "areaDevelopers",
                            "bestFranchises",
                            "discoveryDays",
                            "franchiseResales",
                            "veteranFranchises",
                            "greenFranchises",
                            "homeBasedFranchises",
                            "hotTrendingFranchises",
                            "internationalBusiness",
                            "lowCostFranchises",
                            "masterFranchises",
                            "mobileFranchises",
                            "multiUnitFranchises",
                            "partTimeFranchises",
                            "popularFranchises",
                            "recessionResilientFranchises",
                            "sbaApprovedFranchises"
                        ],
                        "type": "string",
                        "description": "Which curated collection page to pull (mode=collection only) — FranchiseDirect's own editorial lists such as low-cost, home-based, veteran-friendly, or master franchises.",
                        "default": "lowCostFranchises"
                    },
                    "homeBasedOnly": {
                        "title": "Home-based opportunities only",
                        "type": "boolean",
                        "description": "Only keep franchises whose profile page confirms a home-based business model. Requires `fetchDetails=true` to take effect (home-based status is only available on the profile page, not the listing card).",
                        "default": false
                    },
                    "fetchDetails": {
                        "title": "Fetch full profile details",
                        "type": "boolean",
                        "description": "Also fetch each franchise's profile page for a fuller record (financials, business type, training, home-based, financing). Roughly doubles request count.",
                        "default": true
                    },
                    "maxItems": {
                        "title": "Max items",
                        "minimum": 1,
                        "maximum": 200,
                        "type": "integer",
                        "description": "Hard cap on emitted records. FranchiseDirect renders ~12-13 results per filter combination without a browser; widen filters or run several categories to collect more.",
                        "default": 20
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
