FR
Copied
Modules

Extra phones

Extra phones

The phones_extra module digs past the single switchboard line returned by a typical map listing and surfaces the additional voice channels a business exposes on its own site: direct lines, mobile numbers, sales desks and support hotlines.

Purpose

Discovery sources publish one canonical phone per location. Real organisations publish several across homepage, landing pages, team bios, and legal notices. phones_extra reads the public-facing pages of each website attached to a POI, extracts every phone-shaped token, validates them through Google's phonenumbers library, normalises to E.164, and deduplicates against the primary number already on file.

Inputs

The module operates on an enriched POI list: typically the result of a prior discovery run.

Field Required Notes
site_web yes POIs without a website are filtered out at submit.
name no Used for output labelling and audit trail.
phone no When present, used as the dedupe reference.
address no Used to bias country detection for ambiguous formats.

Items missing site_web are silently dropped; if the filtered list is empty the request is rejected with a validation error.

Outputs

Each input row keeps its original columns and gains the fields below. Multiple numbers are joined with |. Empty strings indicate the module ran but found nothing of that kind. The primary telephone of the row is never repeated here, and at most 5 numbers are kept per site.

Column Type Description
phones_extra string Every additional number found on the site, E.164.
phones_extra_count string How many numbers phones_extra holds.
phones_source_urls string Pages the numbers were read from.
phones_mobile string The numbers of phones_extra that are mobile lines, E.164.
phones_fixed string The other numbers (landline, VoIP, special numbers), E.164.

Mobile vs fixed is decided from the national numbering plan of each number (for France, 06 and 07 are mobile). Numbers a plan cannot tell apart (such as US fixed-or-mobile ranges) are listed as fixed. All numbers are validated and normalised; anything that fails validation is discarded rather than surfaced as a best-effort guess.

Lifecycle

Standard job lifecycle. See Jobs lifecycle. Progress is reported in sites and final volume in numéros.

Pipeline

phones_extra is an enrichment module: it augments an existing POI list rather than generating one.

needs:    poi_list
produces: enriched_list

Typical chain:

scrap → phones_extra → filter → export

Endpoints

POST /api/jobs/phones-extra

Create a new extra-phones job from a list of POIs.

Body

Field Type Required Description
items array yes POIs to enrich, each with at least site_web.
source_job_id string (uuid) no Parent job ID when chaining from a prior run.

Response

Returns the standard JobPublic envelope (id, status, job_type, output_filename, quota cost, timestamps).

Example

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

{
  "source_job_id": "f3c2…",
  "items": [
    { "name": "Acme SAS", "site_web": "https://acme.example", "phone": "+33123456789" },
    { "name": "Beta Co",  "site_web": "https://beta.example" }
  ]
}

{
  "id": "9a7b…",
  "status": "pending",
  "job_type": "phones_extra",
  "output_filename": "telephones-extra-2-sites.xlsx"
}

Global quotas and per-job ceilings: see Limits.

Errors

Condition Response
No item carries a site_web 400: Aucun établissement avec site web.
Estimated cost above the per-job quota 400: quota exceeded, with the numeric overage.
Account quota exhausted 400: quota check failure before insert.
Malformed body (missing items, wrong types) 422: request validation error.

Runtime errors on individual sites do not abort the job: the affected POI is recorded with empty extra-phone fields and the worker moves on.

What's next