Documentation — BistroPing

Étapes de fonctionnement

Le projet fonctionne de manière automatisée pour collecter, filtrer et présenter les données des établissements de la région :

Étape	Description de l'activité
1. Définition géographique	Ciblage précis de la zone d'exploration géographique.
2. Recherche & Découverte	Exploration automatique de la zone géographique pour détecter les nouveaux établissements et les fiches non encore recensées.
3. Actualisation des fiches	Mise à jour régulière des établissements existants (notes, avis, coordonnées, téléphone, site web) pour maintenir l'exactitude des données.
4. Filtrage & Exclusions	Retrait automatique des établissements situés hors-limites ou hors-sujet (commerces non alimentaires, etc.) sur la base de critères de nom et de catégorie.
5. Détection des changements	Comparaison systématique entre l'ancien état et le nouvel état d'une fiche pour enregistrer les ouvertures, fermetures, et autres événements marquants.
6. Visualisation & Outils	Génération automatique des pages de consultation pour les utilisateurs (carte interactive, tableau de recherche rapide, rapport des nouveaux établissements à tester et des changements importants, audit des catégories).

Stratégie de recherche

Pour recenser les établissements de la région de manière exhaustive, le système s'appuie sur un quadrillage géographique configurable dans config_main.yaml :

Stratégie par Grille géographique (Quadrillage)

Le système définit une zone rectangulaire (Bounding Box) et y génère un quadrillage régulier de points de recherche espacés de quelques kilomètres (paramètre step_km). À chaque point de la grille, une recherche de type restaurants est lancée avec un niveau de zoom précis (paramètre zoom).

Pourquoi cette stratégie ? : En resserrant le zoom (ex. zoom 16), la zone visible à chaque recherche est très petite, ce qui force Google Maps à afficher la totalité des établissements locaux (y compris les petits bistrots de quartier ou de campagne) qui auraient été invisibles lors d'une recherche globale.
Contrôle géographique au démarrage : Avant de démarrer une requête, le système vérifie si le point de recherche se situe bien dans la Bounding Box géographique configurée. Si un point sort des limites, il est immédiatement ignoré pour économiser les requêtes et éviter le bruit.

Mécanisme de scraping et de parsing

Une fois les résultats de recherche affichés, le scraper Playwright entreprend l'extraction détaillée des informations de chaque fiche. Ce processus suit des règles strictes pour préserver la qualité des données :

1. Paramètres de langue et de région

Chaque URL de fiche Google Maps est forcée avec les paramètres régionaux suisses (hl=fr et gl=ch). Cela garantit que les informations textuelles (catégories d'activités, statuts d'ouverture, etc.) soient récupérées de manière homogène en français et au format helvétique.

2. Déduplication et économie de requêtes

Déduplication amont (Prospection) : Le scraper analyse l'URL d'une fiche dans les résultats de recherche avant de la charger. Si son identifiant unique Google (Place ID, CID, etc.) est déjà connu dans la base de données existante, la fiche est ignorée pour économiser du temps et des requêtes réseau.
Déduplication aval (Merge) : Lors de l'écriture dans le fichier CSV final, les établissements sont fusionnés à l'aide d'un identifiant stable calculé sur la clé Google la plus forte disponible. Cela évite les doublons physiques si une fiche a changé d'URL ou d'adresse.

3. Extraction de la Catégorie

La détection de la catégorie d'activité Google Maps d'un établissement (ex. Restaurant, Boulangerie) est essentielle pour sa classification (food_kind). Le scraper utilise deux niveaux d'extraction :

Sélecteur de catégorie principal : Le scraper cherche les éléments HTML cliquables spécifiques aux catégories de commerces dans le DOM Google Maps.
Mécanisme de repli (Fallback) : Si aucun sélecteur n'est trouvé (ce qui se produit sur les pages de communes, d'administrations ou d'hôtels/campings utilisant une structure d'affichage d'hébergement différente), le scraper cherche des mots-clés dans les 80 premières lignes de texte de la page.

4. Sources multiples d'enrichissement

Pour chaque établissement à gratter en profondeur, BistroPing interroge séquentiellement les sources d'information suivantes :

Google Maps (Playwright Scraper) : Extrait les horaires, l'adresse, le téléphone, le site web, la note et le volume d'avis.
Guide Michelin : Recherche si l'établissement fait partie de la sélection officielle Michelin.
Guide Raisin : Vérifie le référencement sur la plateforme des vins naturels Raisin.

Règles de filtrage et exclusions

Pour ne conserver que les établissements pertinents (activités de restauration ou d'alimentation dans la région cible), BistroPing applique plusieurs niveaux de filtres automatiques lors de la collecte et de la consolidation des données :

1. Exclusions par nom (17)

Les établissements dont le nom contient l'un de ces mots-clés (insensible à la casse, sous-chaîne après normalisation sans accent) sont immédiatement ignorés : ils ne sont jamais scannés ni enregistrés dans les résultats, et sont retirés des données existantes si déjà présents.

B&B Bed & Breakfast Camping Chambre d'hôtes Chambres d'Hôtes Château de Mathod Coop Donald Double or Twin Room Family Room Fondation Migros Single Room Small Double Room Swiss Lodge Triple Room Twin Room

2. Exclusions par catégorie (111)

Les établissements dont la catégorie Google Maps contient l'un de ces termes (insensible à la casse, sous-chaîne) sont exclus après scan, sauf si leur nom suggère explicitement une activité alimentaire (ex. restaurant, café, pizzeria).

Administration Agence de location de maisons de vacances Agence immobilière Agence événementielle Aire de pique-nique Arrêt Arrêt de bus Arrêt de transports en commun Association agricole Association artistique Association ou organisation Atelier de réparation automobile Atelier de réparation pour motos Attraction touristique Auto-école Bain thermal Bed & breakfast Boutique de cadeaux Bureau de recrutement militaire Cabanes en rondins Camping Centre aéré et de loisirs pour enfants Centre commercial Centre d'escalade Centre d'exposition Centre d'hébergement pour étudiants Centre de bien-être Centre de loisirs Charpentier Château Cinéma Clinique Club de football Club de sport Coiffeur Complexe sportif Concessionnaire automobile Constructeur immobilier Cours de cuisine Discothèque Déchetterie Escalade Ferme Ferme à visiter Fournisseur de machine à café Garage Gare Gare routière Hostellerie Hébergement Hébergement d'intérieur Hôpital Hôtel Imprimerie Institut de beauté Institut de massages Karaoké vidéo Karting Lieu de culte Location d'installations et de machines Magasin Magasin de jouet Magasin de laine Magasin de pièces de rechange automobiles Magasin de pneu Magasin de vélo Mairie Maison de campagne Maison de soins et de retraite Monument culturel Moulin Musée d'histoire locale Musée militaire Office du tourisme ophta.* Organisateur d'exposition Organisme des services sociaux Parc de loisirs Parcours de golf Parking Patinoire Photographe Piscine Point de vue Port de plaisance Poste Refuge Réserve naturelle Salle de banquet Salle de fitness Salle de réception Salon de coiffure Service de location d'équipement de construction Service de sécurité routière Service de taxi minibus Services aux entreprises Site historique Siège social Société d'horlogerie Sommet montagneux Stand de tir Station de ski Station service Tennis club Terminal de ferry Terrain de camping Terrain de golf couvert Terrain de jeu Théâtre École professionnelle Établissement d'enseignement secondaire

3. Traitement des puces de navigation et fiches sans catégorie

Pour éviter que des localités (communes), des zones géographiques ou des fiches d'hôtels/campings ne soient classées par erreur comme des restaurants, le système applique des règles de sécurité complémentaires :

Filtre des puces d'exploration (au pluriel) : Lors de la recherche de la catégorie en mode de repli, les boutons de navigation de Google Maps (au pluriel, tels que restaurants, hôtels, bars, cafés, activités, transit...) sont ignorés pour ne pas être confondus avec l'activité principale de la fiche. Cela évite par exemple de classifier des villages entiers (comme Mathod) ou des campings en restaurants à cause des boutons de suggestions destinés aux visiteurs.
Exclusion des fiches sans catégorie : Toute fiche ne présentant aucune catégorie d'activité (ce qui caractérise les localités, les repères géographiques ou les erreurs de chargement) est automatiquement exclue, à moins que son nom ne contienne explicitement un mot-clé alimentaire ou de boisson.

4. Limites géographiques (Bounding Box)

Pour garantir la pertinence locale des données (centrées sur la région d'Yverdon-les-Bains), les établissements font l'objet d'une validation géographique :

Validation géographique : Les coordonnées réelles (latitude et longitude) de chaque établissement après scan sont vérifiées. S'il se trouve en dehors du périmètre autorisé, il est automatiquement écarté de la base de données principale.

Zone de couverture active : Yverdon : Latitude [46.64, 47.0] · Longitude [6.3, 7.1]
Clermont : Latitude [45.55, 45.93] · Longitude [2.835, 3.359]
Cornillon : Latitude [44.1015, 44.336] · Longitude [4.3076, 4.7]

5. Historique des exclusions

Pour des raisons de transparence et pour faciliter les ajustements futurs, les établissements écartés par les filtres (nom, catégorie ou motif géographique) sont conservés dans un fichier d'historique dédié (places.excluded.csv dans le dossier des données). Cela permet de documenter le motif de l'exclusion sans avoir à réinterroger inutilement ces établissements lors des prochaines explorations.

Regroupements `food_kind`

La colonne food_kind est calculée depuis category à chaque lecture des données. Elle ne génère pas d'événement de modification. Quatre valeurs possibles :

`eat` — manger sur place ou à emporter

La catégorie Google Maps contient l'un de ces mots-clés (correspondance exacte sur mot, ou préfixe pour les mots de 5 caractères ou plus) :

aire de restauration auberge burger cantine crêperie cuisine française moderne dîner fast food fastfood food court grillades hamburger kebab livraison de pizza livraison de repas pizza pizzeria restaurant restauration rapide sandwich sandwicherie snack steakhouse sushi tacos take away à emporter

`drink` — consommer des boissons (bars, cafés, tea-rooms, brasseries, etc.)

Priorité inférieure à eat. La catégorie contient l'un de ces mots-clés :

bar(s)? beer garden biergarten bistro[ts]? brasserie brewery café microbrasserie pub salon de thé taproom tea room

`buy_food` — acheter des produits alimentaires

Priorité inférieure à drink. La catégorie contient l'un de ces mots-clés :

alimentation boucherie boulangerie cave cave à vins caviste charcuterie chocolatier commerce alimentaire confiserie distillerie fournisseur de bières fromagerie grossiste alimentaire kiosque magasin alimentaire magasin bio magasin d'alimentation magasin de produits de la ferme magasin de thé marchand de glaces marchand de pâtes marché pastelaria poissonnerie primeur producteur agroalimentaire producteur de nourriture pâtisserie supermarché supermarket traiteur vendeur de viande vignoble épicerie

`other` — tout le reste

Valeur par défaut si aucun mot-clé ne correspond. Peut inclure des établissements mal classés ou des libellés Google Maps inattendus. Le rapport d'audit des catégories permet d'identifier les fiches classées en other pour enrichir les listes ci-dessus si nécessaire.

Structure du fichier de données (33 colonnes)

Lorsque vous téléchargez le fichier de données (au format CSV pour l'ouvrir dans Excel ou Google Sheets), il contient les colonnes suivantes :

Colonne	Type	Description
`id`	str	Identifiant stable unique généré pour chaque établissement.
`id_source`	str	Identifiant Google interne (ex. ChIJ...) extrait de l'adresse Maps.
`source_key`	str	Lien de référence unique pour la déduplication des fiches.
`status`	str	Statut courant : active (ouvert) · closed (fermé) · temporarily_closed (fermé temporairement) · missing (non trouvé).
`seen_in_latest_run`	bool	Indique si l'établissement a été détecté lors de la dernière recherche.
`name`	str	Nom de l'établissement.
`category`	str	Catégorie d'activité sur Google Maps (ex. Restaurant, Boulangerie).
`food_kind`	str calculé	Classification alimentaire : eat (restauration) · drink (café/bar) · buy_food (commerce) · other (autre).
`rating`	float	Note moyenne attribuée par les clients (1 à 5).
`review_count`	int	Nombre total d'avis clients publiés.
`quality_score`	float calculé	Score de qualité global de 0 à 100 (note Google lissée + volume d'avis, avec bonus pour le Guide Raisin et les distinctions Michelin), recalculé à chaque parse selon config_scoring.yaml.
`address`	str	Adresse physique de l'établissement.
`postal_code`	str calculé	Code postal extrait automatiquement de l'adresse.
`locality`	str calculé	Localité (commune) extraite de l'adresse.
`phone`	str	Numéro de téléphone de contact.
`website`	str	Lien vers le site internet officiel de l'établissement.
`plus_code`	str	Code de localisation géographique abrégé (Google Plus Code).
`latitude`	float	Coordonnées géographiques : Latitude.
`longitude`	float	Coordonnées géographiques : Longitude.
`google_maps_url`	str	Lien direct vers la fiche Google Maps.
`source_queries`	str	Recherches associées ayant mené à cet établissement.
`first_seen`	datetime	Date de première détection dans BistroPing.
`last_seen`	datetime	Date de dernière modification des informations principales.
`last_scraped`	datetime	Date du dernier contrôle des détails de l'établissement.
`last_changed`	datetime	Date du dernier changement constaté sur une information clé.
`missing_since`	datetime	Date à partir de laquelle l'établissement a cessé d'apparaître dans les recherches.
`change_count`	int	Nombre total d'actualisations d'informations clés enregistrées.
`scrape_status`	str	Statut technique de la collecte (ok en cas de succès, error en cas de problème).
`scrape_error`	str	Description abrégée du problème technique s'il y a lieu.
`is_raisin`	str	Indique si l'établissement figure sur le Guide Raisin des vins naturels (yes / no).
`raisin_url`	str	URL de la fiche du Guide Raisin (vide si l'établissement n'y figure pas).
`michelin_distinction`	str	Distinction au Guide Michelin : 3_stars, 2_stars, 1_star, bib_gourmand, selected (vide sinon).
`michelin_url`	str	URL de la fiche du Guide Michelin (vide si l'établissement n'y figure pas).

Modes d'exploration

Le système propose trois approches complémentaires pour scruter et actualiser la région :

Mode	Fonctionnement	Objectif principal
Découverte (`prospect`)	Recherche les nouveaux établissements dans la région géographique et les ajoute au répertoire s'ils sont jugés conformes. N'interroge pas les fiches déjà enregistrées pour économiser le temps de traitement.	Découverte et intégration des nouveaux établissements.
Mise à jour (`update`)	Actualise les informations (notes, avis, site web, téléphone...) des établissements déjà enregistrés en commençant par les plus anciens (ceux n'ayant pas été actualisés depuis au moins 7 jours). Les fiches incomplètes ou comportant des erreurs sont traitées en priorité.	Maintien de la fraîcheur et de la précision des données sans lancer de nouvelles recherches.
Analyse locale (`reparse`)	Analyse le cache HTML brut stocké en base de données SQLite localement et relance l'extraction des données sans charger de pages web ni interroger le réseau.	Permet de mettre à jour le parsing des données hors-ligne de façon ultra-rapide.

Aucun mode courant ne marque automatiquement des établissements comme disparus.

Fiabilité et automatisation quotidienne

Le système a été conçu pour fonctionner de manière autonome et transparente :

Sauvegarde en cours de route & Reprise après interruption : Lors d'explorations importantes, les données collectées sont sauvegardées périodiquement. Si la recherche est interrompue (perte de réseau, arrêt manuel, etc.), le système reprend automatiquement là où il s'est arrêté lors du lancement suivant, sans perdre les informations déjà acquises ni solliciter à nouveau inutilement Google Maps.
Prospection lissée dans le temps : Pour ne pas surcharger la collecte et rester discret, les recherches de nouveaux établissements peuvent être découpées en plusieurs tranches distinctes. La recherche progresse de tranche en tranche chaque jour.
Automatisation quotidienne : Un script d'automatisation s'exécute chaque jour. Il recherche les nouveaux établissements par tranche, rafraîchit les anciennes fiches éligibles, vérifie la qualité des données, puis régénère l'intégralité de ce site web (la carte, le tableau, et le rapport d'activité) avant de publier les résultats s'ils ont changé.