--- name: api-portale-bgg description: "I tre endpoint del portale BGG, cosa danno che prima non avevamo, e le due trappole nei numeri delle partite" metadata: node_type: memory type: reference originSessionId: c3e2fc4c-be09-400e-b164-29944c983cf8 modified: 2026-09-03T15:44:37.426Z --- Documentazione completa scritta da Paolo il 2026-09-03 in `~/Desktop/api-portale-bgg.md`. Qui c'è solo quello che serve a noi. Base: `https://bgg-app-weld.vercel.app` (risponde ancora anche il vecchio `bgcollezione.vercel.app`, che è quello cablato in `codice/portale.py`). Pubblici, senza autenticazione, JSON. | endpoint | a cosa ci serve | |---|---| | `/api/gioco/{bggId}` | la scheda: editore italiano, peso, meccaniche, video, `partiteStats` | | `/api/partite/{utente}?gioco={bggId}` | **le singole partite**: data, durata, luogo, punteggi | | `/api/collezione/{utente}?espansioni=1` | i giochi posseduti, col voto personale e l'ultima partita | Username del gruppo: `paoloalby`, `madnessvale` (Valentina), `henryboarder` (Enrico), `fuocaria` (Sonia), `violentvioletcat` (Nano), `vagamundo` (Roberto), `nekar`, `dobleace11`, `starkalif96`, `sof80`. ## Perché cambia il lavoro sulla slide della durata `partiteStats` dà solo le mediane già aggregate. `/api/partite` dà le partite una per una, **con la data**, e serve a smascherare due cose che l'aggregato nasconde: - **le partite vecchie**, quelle di quando il gioco lo si stava imparando, che gonfiano la mediana; - ~~le durate tonde~~: **regola ritirata il 2026-09-04.** Un 60 tondo è una stima consapevole di Paolo, non un errore, e va usata come qualsiasi altra durata. Vedi [[slide-durata-vera]]. È così che il 2026-09-03 è caduta la slide della durata di **Azul Sintra**: la mediana di 60' in quattro erano tre partite del 2020 da "60" tondi, mentre l'unica partita recente in quattro dura 33'. Controllati tutti e otto i post con la slide: sei reggono, e resta da rivedere **Terraforming Mars** (12 ottobre), dove lo strillo "non cambia con quanti si è" regge sui totali ma non sulle partite dal 2023 in poi, che in due scendono a 107'. **Controllo da fare prima di ogni slide della durata**: scaricare le partite di tutti gli utenti per quel gioco, guardare gli anni e le durate tonde, e rifare la mediana solo sul recente. Se cambia di più di dieci minuti, la slide non si fa oppure si riscrive lo strillo. ## Due trappole nei numeri **Il campo `partite` di `/api/gioco` è del gruppo, non di Paolo.** Kingdomino: 63 per il gruppo, 13 per Paolo. Wingspan: 94 contro 27. Sintra: 18 contro 10. Anche `partiteStats` aggrega tutti. Le didascalie hanno sempre usato il numero grande, e va bene finché la frase dice che è il tavolo, non lui: il primo post, Draftosaurus, diceva *"Centodue partite in casa nostra"*, ed è la formula giusta. **Regola dal 2026-09-03**, decisa da Paolo: il numero resta quello del gruppo e l'attacco lo dichiara, alternando **"in casa nostra"** e **"sul nostro tavolo"** per non ripetere sempre la stessa formula. Corretto tutto lo stesso giorno: le nove didascalie già scritte nelle schede e **tutti i post in coda su Buffer**, sui due canali. **Una serata registrata da due persone compare due volte** se si uniscono le partite di più utenti. Vanno deduplicate su data più durata più punteggi. Il portale lo fa già dentro `partiteStats`, dove `considerate` dice quante partite stanno davvero dietro le mediane, e scarta anche le durate assurde (sotto i 5 minuti, sopra le 10 ore). Un conto fatto a mano sui dati grezzi non coincide mai al centesimo con il suo. Vedi [[slide-durata-vera]] e [[pipeline-pubblicazione]]. ## Leggere BGG: si passa dal browser Verificato il 2026-09-04 cercando le opinioni su SETI. - **L'API XML di BGG (`xmlapi2`) risponde 401**, non è più aperta. - **WebFetch prende 403** su qualsiasi pagina `boardgamegeek.com`. - L'unica strada che funziona è **aprire il sito con Chrome** e leggere la pagina, perché il browser di Paolo è già loggato. Cosa serve davvero, e dove sta: | cosa | dove | |---|---| | distribuzione dei voti, uno per uno | scheda `/stats`, tabella RATINGS BREAKDOWN | | i commenti scritti | scheda `/ratings?rated=1&comment=1` | | i thread | scheda `/forums/0`, gli href si tirano fuori con una riga di javascript | C'è anche l'endpoint interno `api.geekdo.com/api/collections?ajax=1&objectid= {bggId}&objecttype=thing&oneperuser=1&require_review=true&showcount=50&pageid=N`, che restituisce JSON coi voti e i commenti. Funziona **solo chiamandolo da una scheda già aperta su quel dominio** (altrove è CORS), ordina per voto decrescente e **ignora `sortdir` e `rating_max`**: per arrivare ai voti bassi bisogna andare avanti di pagina. Il tetto di `showcount` è 50. **How to apply:** per capire cosa pensa la gente di un gioco non bastano le recensioni, che sono quasi sempre diplomatiche. Regola di Paolo, 2026-09-04: *"chi fa recensioni non può sparare a zero, mentre la community sui social e sui forum è la voce della verità"*. Quindi si guardano **la distribuzione dei voti**, che dice quanto è grande davvero la minoranza scontenta, e **i commenti col voto basso**, che dicono perché. Il primo numero serve a non gonfiare il dissenso: su SETI chi vota 6 o meno è il 6,7%. ## Le API nuove del 2026-09-05, e cosa cambiano nel metodo Paolo ha fatto aggiornare il portale. La documentazione completa sta in `~/Desktop/api-portale-bgg.md` e va riletta da lì, qui c'è solo cosa cambia per noi. Base: `https://bgg-app-weld.vercel.app`. ### `GET /api/gioco/{bggId}?utente=paoloalby` Aggiunge il blocco `utente` con **inCollezione, haGiocato, partite, ultimaPartita** per quella persona. Sono le partite registrate da lei nel suo diario BGG, non chi era al tavolo nelle partite altrui. **Regola nuova: le didascalie sono in prima persona, quindi prima di scriverne una si guarda questo blocco.** Due numeri cambiano la voce: - **la quota**, cioè `utente.partite` su `partiteTavoli`. Se è bassa il post parla di "casa nostra" e non di "io"; - **`ultimaPartita`**. Una frase come "lo rimetto sul tavolo volentieri" su un gioco che Paolo non tocca da due anni è falsa anche se i tavoli sono tanti. Casi veri misurati il 5 settembre: **Dixit 12 tavoli e Paolo zero partite** (uscito il 4, per fortuna la didascalia diceva "tiriamo fuori", al plurale); **7 Wonders Duel 11 su 77 e ultima partita giugno 2024**; Century 17 su 37 con ultima partita aprile 2025, e la prima riga dice "è ancora il deck building che rimetto sul tavolo più volentieri". Gli username del gruppo: `paoloalby`, `madnessvale` (Valentina), `henryboarder` (Enrico), `fuocaria` (Sonia, esclusa dai conteggi, vedi [[conteggio-partite-gonfiato]]), `dobleace11` (Lorenzo L.), `nekar` (Lorenzo S.), `vagamundo` (Roberto), `violentvioletcat` (Nano), `starkalif96` (Giulio), `sof80` (Sofia). ### `GET /api/collezione/{utente}?giocati=1` Aggiunge i giochi **giocati ma non posseduti**, marcati `inCollezione: false`. Su Paolo: **166 posseduti, 290 giocati e non posseduti, 456 in tutto.** **Regola nuova: non si dice più "non ce l'abbiamo" guardando solo la collezione.** Il gruppo è grande e i giochi girano. Il 5 settembre questo ha corretto tre affermazioni sbagliate fatte lo stesso giorno: - **Lorenzo il Magnifico**: detto "non in collezione", in realtà 4 tavoli di gruppo e 2 partite di Paolo; - **Viticulture**: detto "non ce l'abbiamo", in realtà **posseduto**, 54 tavoli, 15 partite di Paolo, ultima il 18 agosto 2026; - **Cities**: detto "non l'abbiamo provato", in realtà 3 tavoli e una partita di Paolo il 2 agosto 2026. ### L'archivio foto è solo roba di Paolo Verificato il 5 settembre incrociando i 126 giochi con foto e la collezione: **zero foto di giochi che Paolo non possiede.** Quindi le nuove API non allargano da sole la scaletta, che resta legata alle foto. I 290 giocati e non posseduti sono soggetti possibili solo se Paolo li fotografa alle serate: i più giocati da lui sono Gloomhaven Jaws of the Lion e Hitster (19 partite), 7 Wonders Seconda Edizione (14), Legacy of Yu e Realm of Sand (11). Vedi [[dati-sempre-freschi]] e [[stato-scaletta-e-coda]]. ## BGG da riga di comando: l'API XML no, `api.geekdo.com` si' Trovato dagli agenti il 2026-09-10 lavorando su Era. L'API XML di BGG (`boardgamegeek.com/xmlapi2/...`) risponde **Unauthorized** da curl, verificato il 9 settembre su Century. Ma **`https://api.geekdo.com/api/geekitems?objectid=&objecttype=thing` risponde 200** da riga di comando, e dentro ci sono anche i premi e le nomination (su Era e' saltata fuori la nomination 2021 ai Geek Media Awards). Vale come fonte primaria per i dati di scheda quando il portale non li ha. Le immagini delle singole edizioni restano invece solo dal browser.