By the end of this tutorial you will have a Python script that pulls the plumbers listed in one PagesJaunes category for Lyon into structured rows: name, activity, address, rating, review count and the website each business lists.
PagesJaunes is the French business directory. PagesJaunes Scraper (reventadata/pagesjaunes-scraper) is the Apify Actor that reads its public category pages and returns one row per business. It is not affiliated with PagesJaunes or Solocal; the name only says what it reads.
The sample rows in this guide come from a real run dated 18 November 2026 (20 rows), not from an invented example.
Prerequisites
You need three things:
- Python 3 with
pip. - A free Apify account.
- Your Apify API token.
Install the client and export the token:
pip install -U "apify-client~=3.0" export APIFY_API_TOKEN="your_apify_token_here" No scraping code is needed on your side. The Actor does the reading.
What you'll achieve
You will search the plumbers category in Lyon (lyon-69), read the businesses of the first page into Python and print two lines per business. Change the two slugs to search another category or another area.
The rows also carry fields that a plain category page does not show, such as the company identifiers, but only when you turn on the profile option. This guide keeps to the default and shows where that option changes the output.
Step 1: Open PagesJaunes Scraper
Open the PagesJaunes Scraper page on Apify Store for the Actor's description. This tutorial calls the Actor from Python, so you need only its name, reventadata/pagesjaunes-scraper.
Step 2: Choose the search
The search is described by a handful of input fields:
-
searches: a list of objects with two site slugs.locationis a city slug ending in the department number, such aslyon-69, ordepartement/rhone-69for a whole department.rubriqueis the category slug, such asplombiers. Copy both from a category URL on pagesjaunes.fr. Free-text keywords are not supported. -
startUrls: full category URLs of the formhttps://www.pagesjaunes.fr/annuaire/<location>/<rubrique>. A URL with a query string is refused, and so is a search URL with?quoiqui=. A refused input ends the run as FAILED with a message that names it. -
maxItems: the most businesses saved across all searches. -
maxPages: pages to read per search, from 1 to 500. A category page holds 20 businesses, and the site serves at most 500 pages (10,000 businesses) per search. -
fetchDetails: off by default. Turned on, it adds fields from each business's own page.
Give searches, startUrls, or both. Each business is saved once, even when a sponsored card repeats across pages.
The search in this guide, as the run received it:
{ "searches": [{"location": "lyon-69", "rubrique": "plombiers"}], "startUrls": [], "maxItems": 20, "maxPages": 1, "fetchDetails": false } Step 3: Run it from Python
This script starts the Actor, waits for it, reads the dataset and prints two lines per business:
import os from apify_client import ApifyClient # 1. Initialise the client with your token from the environment client = ApifyClient(os.environ["APIFY_API_TOKEN"]) # 2. Describe the search: plumbers in Lyon, one category page, up to 20 businesses run_input = { "searches": [{"location": "lyon-69", "rubrique": "plombiers"}], "startUrls": [], "maxItems": 20, "maxPages": 1, "fetchDetails": False, } # 3. Start the Actor and wait for it to finish run = client.actor("reventadata/pagesjaunes-scraper").call(run_input=run_input) if run is None or run.status != "SUCCEEDED": status = run.status if run else "unknown" raise SystemExit(f"Run did not succeed (status: {status}).") # 4. Read the rows from the run's default dataset items = client.dataset(run.default_dataset_id).list_items().items print(f"Retrieved {len(items)} businesses.\n") # 5. Print two lines per business for item in items: rating = "-" if item["rating"] is None else item["rating"] website = "-" if item["website"] is None else item["website"] print(f"{item['name']}, {item['city']} | {item['activity']} | rating {rating}") print(f" {item['address']} | website {website}") Step 4: Read the output
The loop prints two lines per business. This is the start of the output for the run of 18 November 2026, the first three of its 20 rows:
PLOMBERIE TOESCA, Lyon | plombiers | rating - 26 boulevard Jules Favre 69006 Lyon | website - Vila-Nova, Charvieu Chavagneux | plombiers | rating - 18 rue Fréminville 38230 Charvieu Chavagneux | website - Chauffageo, Lyon | plombiers | rating 5 73 cours Albert Thomas 69003 Lyon | website http://www.chauffageo.fr The run finished with status SUCCEEDED in 34.9 seconds.
Step 5: Add the profile fields (optional)
Set fetchDetails to true and the Actor also reads each business's own page. It adds the phone number as published, SIRET, SIREN, NAF code, legal form, company creation date, headcount bands, establishment type, latitude, longitude, opening hours and the main image. The run is slower.
A business whose page cannot be read still ships, with those fields null and detailStatus set to failed.
Understanding your results
Every row carries 29 fields. The ones you will use most:
-
name,activity,moreActivitiesCount: the business name, its main activity, and how many further activities the card announces. -
services,description: the service tags and the description shown on the card. -
rating,reviewCount: the average score out of 5, and the number of reviews. Both arenullwhen the card shows none. -
address,street,postalCode,city: the address as printed, then split up. -
website: the website the business lists, when it lists one. -
phone,siret,siren,nafCode,legalForm, and the other profile fields: empty unlessfetchDetailsis on. -
detailStatus:not_requestedwhenfetchDetailsis off,okwhen the profile was read,not_foundwhen the profile page is gone,failedwhen it could not be read, andskippedwhen the run stopped fetching profiles. -
searchUrl: the category URL the business was found under.
In this run, fetchDetails was set to false. The 13 profile fields (phone, siret, siren, nafCode, establishmentEmployees, establishmentType, legalForm, companyCreatedOn, companyEmployees, latitude, longitude, openingHours, imageUrl) are empty on all 20 rows, and detailStatus is not_requested on all 20.
Across the same 20 rows, rating is empty on 9, reviewCount on 6, website on 17 and description on 1. The rows name 9 towns: 10 are in Lyon, 3 in Villeurbanne and one each in the other 7 towns.
The first row of the run, copied as the run returned it:
{ "id": "06507333", "url": "https://www.pagesjaunes.fr/pros/06507333", "name": "PLOMBERIE TOESCA", "activity": "plombiers", "moreActivitiesCount": 1, "services": [ "réparation de sanibroyeur", "entretien de sanitaire", "pose de canalisation", "entretien de ballon d'eau chaude", "détection de fuite d'eau", "nettoyage de radiateur", "raccord de plomberie", "nettoyage de wc" ], "description": "Situé à LYON 69006, depuis 2021,Toesca Patrick se tient à votre disposition pour toute demande d'installation de chauffage. Pour plus d'informations, prenez contact.", "rating": null, "reviewCount": 3, "address": "26 boulevard Jules Favre 69006 Lyon", "street": "26 boulevard Jules Favre", "postalCode": "69006", "city": "Lyon", "website": null, "phone": null, "siret": null, "siren": null, "nafCode": null, "establishmentEmployees": null, "establishmentType": null, "legalForm": null, "companyCreatedOn": null, "companyEmployees": null, "latitude": null, "longitude": null, "openingHours": null, "imageUrl": null, "detailStatus": "not_requested", "searchUrl": "https://www.pagesjaunes.fr/annuaire/lyon-69/plombiers" } Pro tips
- Keep
maxPagesat 1 while you test. Each page holds 20 businesses, so one page is enough to check your code. - Split a large category. A search reaches at most 500 pages. For a bigger niche, use one search per city or per department.
- Turn on
fetchDetailsonly when you need it. It adds the profile fields and makes the run slower. - Compute your own counts. Count rows where
websiteis notnull, or group rows bycity, in plain Python on the list you get back.
Troubleshooting
- Zero rows, status SUCCEEDED. The site answered with no matches for the search. The status message says so. Check the slugs against a category URL on pagesjaunes.fr.
- Run FAILED with a message about the input. A malformed slug, a
startUrlsentry that is not a category URL, or a URL with a query string. The message names the input to fix. - Run FAILED with a reason and no rows. If the site refuses the pages and no row was saved, the run ends FAILED with the reason. If the run clock ends after some rows were saved, those rows are kept and the log says the sweep ended early.
- Phone numbers are empty. In the default run they are not returned. Turn on
fetchDetailsto get them.
The rows are public business data. Check your use of them against the site's terms and against applicable data-protection law.
Next steps
For current pricing and details, see the Store page.
Change the slugs to compare categories or cities side by side, and split a large niche by department before it reaches the page ceiling.
What are you planning to search for on PagesJaunes? Drop a comment below.
About the author: reventadata builds and publishes data extraction Actors on the Apify Store.
