Scrap (Google Maps)

Source module that extracts Google Maps listings for a set of search queries across one or more geographic zones, in any of ~199 countries.

Purpose

Source module: runs each query over every grid point covering the requested zones and returns a flat CSV of Google Maps establishments (name, phone, address, website, rating and review count).

Inputs

Request body:

{
  "queries": ["plombier", "chauffagiste"],
  "country": "FRA",
  "zones": ["75", "92"],
  "include_reviews": false
}

Targeting another country instead; zones are expressed in that country:

{
  "queries": ["plumber", "hvac"],
  "country": "USA",
  "zones": ["Texas", "Austin 30km"]
}

Effective Google Maps requests = len(queries) × grid_points(zones). Rejected at submit if cost exceeds the per-job EF ceiling.

Outputs

Result file: UTF-8 CSV, semicolon delimiter, BOM (Excel-safe). The same dataset is available in three formats through the download endpoint.

ville and code_postal come from the structured place data Google ships with each result, not from reverse geocoding, so they match Google exactly. The Maps list view only renders the street, which is why adresse alone never carries the city.

The file has no category, opening-hours or directory-flag column. Websites that are really a directory listing rather than the business's own site are recognised by dead_check (status = aggregator) and can be dropped with the exclude_aggregators rule of filter.

Optional columns

Three extra columns are off by default and enabled per job via extra_columns (a list). The default output is street + ville + code_postal.

Example request body: { "queries": ["plumber"], "zones": ["Paris 10km"], "extra_columns": ["gps", "departement", "region"] }.

Foreign phone numbers

A search area that touches a border also returns businesses from the other side: a scrape of Lille (France) brings back salons in Tournai (Belgium), with numbers in +32.

exclude_foreign_phones, on by default. A listing is dropped when its phone number explicitly carries the calling code of another country than the one you selected. Everything else is kept:

It works the same way in every country. Calling codes shared by several countries (+1 for the United States, Canada and the Caribbean, +7 for Russia and Kazakhstan, +44 for the United Kingdom and the Channel Islands) are resolved from the number range, not from the code alone. Numbers from a country's overseas territories count as that country's (Guadeloupe or Réunion for France, Puerto Rico for the United States).

Dropped listings do not count toward stop_at, and the job log ends with the number of listings dropped this way. Send "exclude_foreign_phones": false (or untick Exclude foreign phone numbers in the advanced settings) to keep them.

Duplicates

One listing = one row. Always, with no setting to turn it off. A business can sit within reach of several GPS grid points and match several of your queries, and Google's listing URL is not a stable identity: it also encodes the search context, so two captures of the same place come back with different URLs. Rows are therefore deduplicated on the 0x…:0x… feature id Google carries inside that URL (falling back to normalised name + address when it is absent). This is a correctness guarantee, not a preference.

max_per_phone: the one thing you can tune. Different listings sometimes share a phone number: a shared switchboard, an owner running several outlets, or a network of near-identical local listings pointing at one call centre. For a chain those are genuinely distinct establishments; for prospecting they are one contact. That trade-off is yours to make:

Numbers are compared in E.164 form, so +33 1 87 58 88 84 and 01 87 58 88 84 are the same number; the job's country sets the region used to parse national formats. Listings with no usable number are never dropped by this setting.

The quota applies across the whole job, queries and zones included, and is preserved when a cancelled job is resumed. Deduplication never changes which grid points get scraped, so it has no effect on EF cost or runtime.

Formats: csv (original), json, xlsx. Selected via ?format= on the download endpoint.

Lifecycle

Standard job lifecycle: see Jobs & lifecycle. While running, the SSE status event carries a query_stats payload of shape { "<query>": { "tiles": int, "with_results": int } }, updated in real time to expose per-query hit ratio.

Pipeline

Typical downstream modules chained against a scrap output:

• emails: find professional and personal emails from site_web.
• socials: extract social network handles from site_web.
• legal_ids: extract SIREN/SIRET from the establishment's website (legal-mentions page).
• reviews: collect full review threads from lien_google_maps.
• techstack, dead_check, brand_assets, ads_intelligence: site-level enrichments keyed on site_web.

Endpoints

Dedicated endpoint:

POST /api/jobs
Content-Type: application/json

{
  "queries": ["plombier"],
  "zones": ["75"],
  "include_reviews": false
}

Generic job endpoint (equivalent; same payload, job_type inferred from shape):

POST /api/jobs
Content-Type: application/json

{
  "job_type": "scrap",
  "queries": ["plombier"],
  "zones": ["75"]
}

Both responses return the created JobPublic object including id, status, grid_points_count, ef_cost and output_filename.

Download:

GET /api/jobs/{job_id}/download?format=csv|json|xlsx

Limits

Platform-wide quotas: see /docs/concepts/limits. Module-specific caps:

Errors

Queries refused by Google Maps surface in dead_queries on the job object.

Data sources & attribution

Worldwide zone resolution and reverse-geocoding are built on open datasets:

Worldwide administrative boundaries © geoBoundaries (CC BY 4.0) · Cities © GeoNames (CC BY 4.0).

What's next

• Jobs lifecycle
• Pipelines
• emails module