# Changelog of Restaurant Chain Locations Spain — Openings Tracker (`rastriq/spain-restaurant-chain-locations`) Actor

- **URL**: https://apify.com/rastriq/spain-restaurant-chain-locations/changelog.md
- **Full Actor documentation**: https://apify.com/rastriq/spain-restaurant-chain-locations.md

## Changelog

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

Four more chains, 25 in total, picked from the Topfranquicias directory by network size (SONDEO.md
§2d). No change to `normalize.py`, `snapshot.py` or the output schema. New offline suite
`tests/test_v03.py`, run by `make test-locators`.

**Measured live on 2026-11-14 from a home (residential) connection** with `tools/live_check.py`.
Two runs about 20 minutes apart gave the same uids. **Not yet tested from a datacenter IP**: that
is the last step, left to the owner, before any platform smoke test of these four.

| Brand | Stores | Time | Source | Notes |
|---|---:|---:|---|---|
| Pizzerías Carlos | 93 | 0.3 s | pizzagest ordering backend (1 call) | **Operator CIF and legal name**: 71 franchisor-operated, 22 by 18 franchisees. Today-only hours left out |
| Häagen-Dazs | 35 | 1.2 s | Global shop locator (1 call, 142 shops in 13 countries, ES kept) | Weekly hours; delivery / take-out / dine-in |
| Taberna del Volapié | 25 | 0.3 s | Foodbox `/mapa` markers, the same platform as Santagloria (1 call) | 2 without postal code |
| Tony Roma's | 20 | 0.7-13 s | WordPress REST `fw-portfolio` (1 call) | No coordinates published: address with postal code 20/20, province from the postal code |

**Not added**: Pannus Café, La Andaluza, Croqueta y Presumida, Pomodoro, Grupo Terraminium,
Mercado Provenzal, La Meiga das Empanadas, Cantina Mariachi, Mundopan, Luzzo, Horno Santa Eulalia,
Miu Japonés, Il Caffè di Roma and Dehesa Santa María. Evidence in SONDEO.md §2d.

### 0.2 — 2026-11-14

Deployment:

- **latest = `0.2.2`**: 14 chains plus the Google Maps checker.
- **beta = `0.2.3`**: all 21 chains. The seven new ones passed a platform smoke test (7/7 `ok`,
  570 stores).

See `docs/DEPLOY.md`.

**Fix:** HTTP 409 is now retried. A transient Cloudflare edge error on one Subway store page failed
the whole brand from a datacenter IP.

**Google Maps checker.** New input `googleMapsCheck` (`off` / `closures` / `changes` / `all`,
default `changes`) and `googleMapsMaxPlaces` (default 300).

- **What it does:** one batched sub-run of **our** actor `rastriq/gmaps-discover-enrich` looks the
  selected stores up on Google Maps. Each store gets a `googleMaps` object: status
  (`operational` / `temporarily_closed` / `permanently_closed` / `not_found`), place id, URL,
  rating, review count, match confidence and distance. `removed` stores get `_closure_check`:
  `confirmed`, `temporary`, `contradicted` or `unverified`.
- **Why:** on 2026-11-14 Muerde la Pasta dropped El Muelle (Las Palmas) and Torresevilla
  (Sevilla) from its API, which now answers 404 for their ids. Google Maps still lists both as
  operating, with 235 and 496 reviews. They were unpublished, not closed, and a bare `removed`
  would have reported two false closures. The live check returns `contradicted` for both, and
  `operational` with high confidence (17-19 m) for the two control stores.
- **Matching:** the result's name must contain the brand key and the place must be within 600 m
  (high confidence ≤150 m). Without coordinates, the postal code must agree instead. No match
  gives `not_found`, never a guess.
- **Measured behaviour of the Google Maps actor:** it dedupes places *across* searches, so a store
  whose own search comes back empty is matched against the whole batch.
- **Cost:** about $0.0015 for 4 searches.
- **Only `rastriq/*` actors can be called**, enforced in code.
- **Failure handling:** a failing sub-run never fails the actor. Rows are emitted without the
  check and `SUMMARY.googleMaps.error` says why.
- **Pipeline change:** rows are pushed after all brands and the Google Maps check finish, not
  brand by brand.
- **SDK compatibility:** `apify>=1.7.0` resolves to apify 4.2.1 / apify-client 3.5.1, where
  `call()` takes `run_timeout` and returns a `Run` model. The runner handles both that and the
  1.x dict API; verified against the real client.
- **Tests:** 122 offline checks (17 new for the checker), plus one live call through the real
  client.

**Seven more chains**, 21 in total. The new adapters only call `make_store()`: no change to
`normalize.py`, `snapshot.py` or the output schema for them. New offline suite `tests/test_v02.py`, run by
`make test-locators` after `test_v01.py`.

**Measured live on 2026-11-14 from a home connection** (`tools/live_check.py`, outside the
platform). Two runs at least 15 minutes apart gave the same uids and the same fingerprints. None of these brands has been
tested from a datacenter IP yet, so `residential=False` is unconfirmed for all seven.

| Brand | Stores | Time | Source | Notes |
|---|---:|---:|---|---|
| Santagloria | 200 | 1.4 s | Google Maps markers inline in `/mapa` (1 call) | Id = restaurant id of the marker. Porto and 2 Andorra stores dropped; 18 without postal code |
| Papa John's | 96 | 12-16 s | Own JSON API, `limit=1000` (1 call, slow server) | Placeholder entry in France dropped; 51 without postal code (province from coordinates); pick-up hours |
| Sibuya Urban Sushi Bar | 74 | 0.6 s | Server-rendered map cards (1 call) | Id = booking page slug; Porto, Vila do Conde and Andorra dropped |
| Manolo Bakes | 68 | 1.3 s | JSON string embedded in `/encuentranos` (1 call) | 8 without postal code; delivery flag |
| Udon | 67 | 3.4 s | WordPress REST, `ubicacion=41` = Spain (1 call, 5.5 MB) | 14 without coordinates; 6 airport/station kiosks without address |
| Subway | 51 | 22 s | Yext pages: directory crawl + microdata (55 calls) | Matches the sitemap; weekly hours |
| Pizza Hut | 14 | 9 s | s4d finder by geo box, 10 per call, quad split (5 calls) + 14 store pages | Coordinates from each store page; today-only hours left out |

**Not added** (evidence in `proyectos/franquicias-restauracion/SONDEO.md`, section 2c):

- Tim Hortons: not on RBI; 15 stores with no id.
- 100 Montaditos: no stable id (2022 CRM export in the JS bundle).
- La Sureña and The Good Burger: no locator.
- La Famiglia (formerly La Mafia): 82 stable ids, but only 8 postal codes and 57 coordinates.
- Cañas y Tapas, Carl's Jr., Smöoy and Dunkin': no coordinates, postal code or id.
- Juan Valdez: no Spanish network.
- 365 Obrador and Wok to Walk: postponed.
- Llaollao, Granier and Panaria: no official site found.

**`live_check.py all` on 2026-11-14**: 20 of 21 OK. McDonald's failed with a Cloudflare 403 from
this home connection; the adapter did not change. The v0.1 notes say McDonald's decides on the
TLS fingerprint. Muerde la Pasta returned 28 (measured 30, floor 18): the two stores unpublished from its API, see above.

### 0.1 — 2026-11-14 (latest: build 0.1.2)

First version. Sweeps the official store locator of 14 restaurant chains in Spain and tracks
openings, changes and closures between runs.

**Sources.** One adapter per platform, all plain HTTP, no browser:

- RBI GraphQL (Burger King, Popeyes);
- Alsea / Salesforce Commerce Cloud (VIPS, Foster's Hollywood, Ginos);
- AmRest ordering (La Tagliatella);
- Domino's GOLO;
- WordPress REST (Goiko);
- Yext pages (Five Guys);
- server-rendered JSON (Telepizza);
- own JSON APIs (McDonald's, KFC, Muerde la Pasta);
- an adaptive grid for Starbucks, which caps every response at 50 stores.

The evidence for every endpoint is in `proyectos/franquicias-restauracion/SONDEO.md`.

**Change detection.** A snapshot per brand and stream, with the same output contract as the
ledger engine (`_delta_status`, `_changed_fields`). A locator returns a brand's complete network,
so a store missing from a trustworthy sweep is reported as `removed`. Closures are skipped when:

- the brand failed;
- it returned fewer stores than its registry floor (60 % of the measured network);
- it returned less than `closureGuardRatio` of the previous snapshot;
- the run was capped;
- it is the first run (baseline).

**Measured live from a datacenter IP on 2026-11-14** (adapters run directly, outside the
platform):

| Brand | Stores | Time | Notes |
|---|---:|---:|---|
| McDonald's | 674 | 0.6 s | 7 entries dropped: Andorra, Gibraltar and placeholder/test entries |
| Burger King | 991 | 7.5 s | The main sweep already includes the 45 Canary stores; the survey's "996 + 43" double-counted |
| Popeyes | 196 | 2.1 s | |
| KFC | 312 | 0.8 s | 58 without postal code (province from coordinates); 1 with broken coordinates (3715, -361), kept and flagged |
| Domino's | 409 | 0.7 s | 405 with operator CIF; 32 without postal code |
| La Tagliatella | 214 | 1.0 s | |
| Goiko | 114 | 6.1 s | 7 without postal code |
| Five Guys | 44 | 22.6 s | One page per store, paced at 0.5 s |
| Muerde la Pasta | 30 | 1.0 s | |
| Starbucks | 190 | 412 s | ~137 grid calls at 1 per 3 s, **no 429**; 1 without postal code |

**On the platform (smoke test, beta build 0.1.1):** Domino's 409 (direct) and **VIPS 175
through the residential proxy**, SUCCEEDED in 6 s.

**All 14 brands on the platform** (run `RolBKdxgCVuxqwMVN`): 14/14 `ok`, 4,311 stores, 419 s, about $0.03.
This was the first platform run of Foster's, Ginos and Telepizza. Telepizza publishes no postal
code; its province is inferred from the coordinates.

**Still pending before `latest`:** the change-tracking part of the protocol in `docs/DEPLOY.md`
(baseline, second run and guard test).

**Privacy.** Operator tax ids are output only when they belong to a legal entity (first letter of
the CIF). Operator contact e-mails and phones (McDonald's) are never read into the row.

**Left out:** Taco Bell (its API takes a fixed key from the site's JS bundle; owner decision
pending), Pans & Company (no stable id), Rodilla and 100 Montaditos (blocked even from
residential IPs).
