# Changelog of Spain Franchise Database — Investment & Royalty (`rastriq/spain-franchise-database`) Actor

- **URL**: https://apify.com/rastriq/spain-franchise-database/changelog.md
- **Full Actor documentation**: https://apify.com/rastriq/spain-franchise-database.md

## Changelog

### 0.4 — 2026-11-15

- New input `includeContactData` (off by default, owner's decision): adds `contactPerson`,
  `contactPhone`, `contactEmail` and `contactAddress` as each directory shows them openly
  (Topfranquicias contact block, Infofranquicias "Central:", franquicias.es listing e-mail), and
  stops withholding a franchisor that is not a company. Off, the output is as before plus four
  `null` fields. `SUMMARY.includeContactData` records the choice.
- Topfranquicias: label pairs are read before the site footer, which uses the same markup for the
  directory's own phone and e-mail (caught by the 0.4.1 beta smoke test, fixed in 0.4.2).
- Infofranquicias "Central:" is split: first line (person or department) -> `contactPerson`,
  the rest -> `contactAddress`.

### 0.3 — 2026-11-15 (beta)

- Infofranquicias: a capped run (`maxBrandsPerSource`) stops listing once it has enough brands
  instead of walking the ~1,000 listing pages of 212 subsectors. The 0.2 smoke test took 20
  minutes for 15 records, 1,192 s of them in Infofranquicias. `SUMMARY` marks it
  `listingTruncated`: `listed` and each brand's sectors are then incomplete. Uncapped runs are
  unchanged.

- README / Store page: five directories, all sectors, measured volumes.

- Amounts with a space as thousands separator ("Desde 130 000 €") were read as 130; now 130000
  (6 records in the 2026-11-14 extraction).

- `tools/dedupe.py`: `--decisions` applies a reviewed `revision_dudosos.csv` (misma merges,
  distinta forbids even transitive merges); new rules from the independent review: unit and
  transfer ads join their brand, two exactly equal figures (one an amount) are a strong signal,
  "Concesionario X / Y" and names inside more than 5 others are not listed for review, founding
  years no longer count against a merge. On the reviewed pairs the rules alone merge 119 of 310
  "misma" and 0 of 365 "distinta".

### 0.2 — 2026-11-14 (not deployed)

**All sectors** (`scope: "all"`, default; `"hosteleria"` keeps hospitality only), discovered from
each directory's home page. **Two more directories:**

- **franquicias.es**: one POST per sector returns JSON; analysed with Claude in Chrome
  (`docs/ANALISIS-INFOFRANQUICIAS-FRANQUICIASES.md`);
- **Infofranquicias**: Cloudflare; a plain HTTP client with a browser User-Agent, no challenge
  handling. Owner's decision, as for McDonald's.

**Live run from a datacenter IP, all sectors** (`tools/live_check.py`): 9,324 records, 0 detail
errors.

| Directory | Sectors | Records | Time |
|---|---:|---:|---:|
| Topfranquicias | 16 | 1,078 | 11 min |
| Mundofranquicia | 47 | 787 | 19 min |
| Franquicias Hoy | 30 | 1,877 | 17 min |
| franquicias.es | 21 | 665 / 667 | 6 min |
| Infofranquicias | 212 subsectors | 4,917 | 71 min |

- Infofranquicias doubles the "más de 2.500" its home page claims.
- At the default pace a full run takes over an hour: Infofranquicias sets the length. The
  directories run in parallel, so the actor's 1-hour default timeout must be raised before
  deploying.

**Dedupe** (`tools/dedupe.py`): 9,324 records → 6,333 brands, 678 pairs left for human review.
Fixed against the full data:

- a directory lists a brand once, so two names from one directory never merge (Telepizza /
  TelePóliza shared a wrong founding year);
- investment and store count are weak signals;
- short or ambiguous names ("Fresh") need a strong signal;
- a second exact key with naive singulars.

21 offline checks.

**Fixes:** franquicias.es detail pages are now fetched by absolute URL (the first live run failed on
`/adaix`). Progress is logged every 250 detail pages.

### 0.1 — 2026-11-14 (not deployed)

First version. Hospitality & restaurant section of three directories, one record per (directory,
brand). Plain HTTP, no proxy, no browser.

**Discovery, as measured on 2026-11-14:**

- **Topfranquicias**: the sector page caps at 120 brands, and `/2`, `/3` list *other* sectors.
  The union of the 9 subsector pages gives 187 brands. Result cards (`div.resultado-busqueda`) are
  told apart from banner links.
- **Mundofranquicia**: one 14 MB listing with 96 links; 95 resolve to a brand page.
- **Franquicias Hoy**: the sector page renders no brands. The list comes from
  `/ajax/franquicias/franquicias-de-hosteleria-y-restauracion?page=N`: 349 brands in 18 pages.

**Live run from a datacenter IP** (`tools/live_check.py all`): 631 records, 568 distinct
`brandKey`, 0 detail errors, about 3 minutes (the directories run in parallel).

| Directory | Records | Investment | Entry fee | Royalty % | Contract | Total stores |
|---|---:|---:|---:|---:|---:|---:|
| Topfranquicias | 187 | 178 | 144 | 116 | 156 | 138 |
| Mundofranquicia | 95 | 84 | 82 | 80 | 58 | 46 |
| Franquicias Hoy | 349 | 329 | 272 | 253 | 290 | 341 |

- All 21 chains of `restaurant-locators-es` appear in at least one directory.
- 49 brands are in two directories and 7 in all three; `brandKey` is exact-match only, so variant
  names ("TGB The Good Burger" / "The Good Burguer TGB") do not join.

**Fixed during the live check:**

- Mundofranquicia's "Organización y expansión" block (founding year, expansion start, network in
  Spain) uses `<li>` pairs. Its "Creación de empresa" was being read as the company name: 42 false
  withholds, and 0 store counts. Now 46 of 95 have a store count, and no false withholds.
- Brand names lose the "Franquicia " prefix that Franquicias Hoy and Mundofranquicia sometimes add,
  so `brandKey` joins across directories.

**Privacy:** the company name is kept only with a corporate form. Topfranquicias withholds 32,
e.g. "Seeker Solutions Spain" or "Mandarina y Calvo S.C": conservative on purpose.

**Tests:** 71 offline checks (`tests/test_v01.py`), including privacy and dataset-schema
conformance.

**Not in 0.1:**

- change tracking between runs;
- other sectors;
- the other two directories of the survey (Infofranquicias: Cloudflare; franquicias.es: AJAX
  endpoint not located).
