# Franchise Direct Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/franchisedirect/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/franchisedirect-search |

## Description

Search Franchise Direct listings by keyword or listing URL. Each card includes a USD cash figure and a numeric minimum.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/franchisedirect/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### CoffeeNow

```json
{
  "results": [
    {
      "url": "https://www.franchisedirect.com/coffee-franchises/coffeenow",
      "name": "CoffeeNow",
      "image": "https://static4.franchisedirect.ie/dims4/default/5f4574f/2147483647/strip/true/crop/350x220+0+0/resize/255x160!/quality/95/?url=https%3A%2F%2Ffranchisedirect-40-prod-ops.s3.amazonaws.com%2F6b%2F9b%2F473082ad4c1b8cfef7f36c4f428c%2Fcn-logo.jpeg",
      "category": "Coffee Franchises",
      "description": "Bring the coffee shop experience directly to local workplaces with a technology-driven mobile franchise that eliminates the need for a traditional storefront. CoffeeNow combines custom-outfitted coffee vans, proprietary ordering technology, and recurring B2B routes to help entrepreneurs build a scalable business around the weekday workday.",
      "minimum_cash_required": 60000,
      "minimum_cash_required_display": "$60,000"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 6,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview

Search franchise cards on Franchise Direct. Send a keyword such as `coffee` or `food`, or a listing URL on franchisedirect.com (search, directory, or category). The response is `{ results, pagination }`.

Each card has `minimum_cash_required_display` as printed, for example `$60,000`, and `minimum_cash_required` as the matching whole-dollar number, `60000`. Pass `results[].url` to `/v2/franchisedirect/franchise`.

## Quickstart

GET and POST take the same `query`.

```
GET https://api.piloterr.com/v2/franchisedirect/search?query=coffee
GET https://api.piloterr.com/v2/franchisedirect/search?query=food
```

`coffee` returns CoffeeNow at `https://www.franchisedirect.com/coffee-franchises/coffeenow` with `$60,000` / `60000`. The same brand's profile call returns that same cash pair.

## Parameters

| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `coffee` |

`query` is required. An empty value returns 400. A URL must be on `franchisedirect.com`. A profile path (two segments, such as `/coffee-franchises/coffeenow`) returns 400 here because it belongs on the franchise endpoint. A search, directory, or category URL is a listing.

## Pagination

Keyword listings such as `coffee`, `food`, and `cleaning` come back as one page. `pagination.page` is `1`. `pagination.next` is `null` when the HTML has no Next link. `pagination.total_results` and `pagination.total_pages` are `null` because the page does not print those totals. `pagination.per_page` is the number of cards parsed.

The site does not honor a hand-built `page=2` on a listing that has no pager. `https://www.franchisedirect.com/search?q=coffee&page=2` returns the same six coffee cards, `page` stays `1`, and `next` stays `null`. When the HTML does contain a Next or Previous link, `next` is that URL and `page` is read from the `page` query parameter.

Card URLs are unique. `minimum_cash_required` is the first number inside `minimum_cash_required_display`.

## Response fields

| Field | Type | Meaning |
|---|---|---|
| `results[].name` | string | Franchise name |
| `results[].url` | string | Profile URL |
| `results[].description` | string or null | Card summary |
| `results[].category` | string or null | Category from the profile path, such as `Coffee Franchises` |
| `results[].minimum_cash_required` | number or null | Minimum cash in whole dollars |
| `results[].minimum_cash_required_display` | string or null | Printed USD amount, such as `$60,000` |
| `results[].image` | string or null | Logo URL |
| `pagination.page` | integer | `1` when the page has no pager |
| `pagination.per_page` | integer or null | Cards on this page |
| `pagination.total_results` | null | Not printed on these listings |
| `pagination.total_pages` | null | Not printed on these listings |
| `pagination.next` | string or null | Next listing URL, or `null` when no Next link is present |

## Use cases

- Compare minimum cash for coffee concepts, using `$60,000` on CoffeeNow against `$175,000` on PJ's Coffee in the same `coffee` response.
- Scan a `food` keyword for mobile and storefront brands, then keep each profile URL for a fee and investment lookup.
- Build a shortlist where the displayed dollars and the numeric minimum describe the same amount before anyone opens the profile.

## Error codes

| Code | Meaning |
|---|---|
| `400` | Empty query, a profile URL, or a domain outside franchisedirect.com |
| `401` | Missing API key |
| `404` | The page was not a listing |
| `500` | The fetch failed |

## Related endpoints

[Franchise Direct Franchise](https://www.piloterr.com/library/franchisedirect-franchise)