> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Référence des champs d'expansion
> Un dictionnaire champ par champ pour l'Expansion API — chaque filtre de requête et champ de réponse, son type, ses valeurs autorisées et sa signification.
Ceci est le **dictionnaire des champs** de l'Expansion API : ce que fait chaque filtre de requête et ce que signifie chaque champ de réponse. Pour le *pourquoi* derrière le modèle, voir [How Expansion Signals Work](/fr/knowledge-base/concepts/how-expansion-signals-work) et le catalogue de valeurs dans [How Expansion Signals Work](/fr/knowledge-base/concepts/how-expansion-signals-work). Pour une liste toujours à jour des valeurs autorisées, appelez le point de terminaison [Expansion Taxonomy](/fr/api-reference/endpoint/expansions/types).
## Dimensions fondamentales
Chaque expansion est décrite selon quelques axes indépendants. Ne les confondez pas :
| Champ | Ce qu'il capture | Exemples de valeurs |
| ----------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `stage` | Jusqu'où une entreprise a progressé sur un marché | `exploring`, `committing`, `expanding`, `scaling` |
| `presence.level` | À quel point l'**empreinte** de l'entreprise est déjà établie, indépendamment de l'étape | `established`, `emerging`, `none`, `no_data` |
| `momentum` | La **trajectoire** du mouvement en ce moment | `advancing`, `steady`, `pulling_back` |
| flow | La **direction** du mouvement entre marchés, exprimée avec `froms` / `tos` | sortant (`froms`), entrant (`tos`), corridor (`froms`→`tos`) |
| `freshness` | À quel point la preuve est **récente** | `fresh`, `cooling`, `stale`, `cold` |
| `scope` | S'il s'agit d'un nouveau marché ou d'une croissance au sein d'une présence existante | `entering_new_market`, `expanding_within_presence`, `established_only` |
| `expansion_score` | Un rang triable de 0 à 1 indiquant l'importance de l'expansion | `0.72` |
Les slugs d'étape sont `exploring`, `committing`, `expanding` et `scaling` — Exploration, Engagement, Expansion, Montée en puissance. `established` n'est **pas** une étape ; c'est un `presence.level`, donc filtrer avec `stages: ["established"]` ne correspond à rien et renvoie silencieusement des résultats non filtrés.
Le **flux** (la direction du mouvement) et le `momentum` (la trajectoire) sont des choses différentes. Filtrer par « entreprises en progression » se fait avec `momentum: ["advancing"]` ; filtrer par « entreprises s'étendant *vers* les États-Unis » se fait avec `tos: ["US"]`. Il n'existe pas de champ de requête `direction` séparé — le flux est entièrement défini par `froms` / `tos`.
## Filtres de requête
### Marchés (`froms` / `tos`)
La géographie est une relation orientée : les entreprises s'étendent **depuis** une origine **vers** une cible. Deux listes expriment chaque cas — pas de drapeau de direction séparé.
| Paramètre | Type | Signification |
| --------------- | ----------------------- | ------------------------------------------------------------------------------- |
| `froms` | string\[] (ISO alpha-2) | Marchés d'**origine** — d'où l'entreprise s'étend (son pays d'origine / siège). |
| `tos` | string\[] (ISO alpha-2) | Marchés **cibles** — vers où l'entreprise s'étend. |
| `exclude_froms` | string\[] (ISO alpha-2) | Marchés d'origine à exclure. |
| `exclude_tos` | string\[] (ISO alpha-2) | Marchés cibles à exclure. |
| Vous envoyez | Vous obtenez |
| ------------------------------ | ---------------------------------------------------------------- |
| `tos: ["US"]` | Tout le monde s'étendant **vers** les États-Unis (entrant). |
| `froms: ["CN"]` | Les entreprises chinoises s'étendant **n'importe où** (sortant). |
| `froms: ["CN"]`, `tos: ["US"]` | Uniquement le **corridor CN → US**. |
| ni l'un ni l'autre | Toutes les expansions, dans le monde entier. |
### Filtres de signaux d'expansion
| Paramètre | Type | Signification |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stages` | string\[] | Filtrer sur une ou plusieurs étapes d'expansion. |
| `momentum` | string\[] | Filtrer par trajectoire (`advancing`/`steady`/`pulling_back`). |
| `freshness` | string\[] | Filtrer par ancienneté des preuves (`fresh`/`cooling`/`stale`/`cold`). |
| `scopes` | string\[] | Filtrer par `entering_new_market` / `expanding_within_presence` / `established_only`. |
| `signal_types` | string\[] | Restreindre à des types de signaux spécifiques (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …). |
| `signal_strengths` | string\[] | Filtrer par tranche de confiance des preuves : `low`, `medium`, ou `high`. (Distinct du `signal_strength_slug` par signal, qui va jusqu'à `very_high`.) |
| `min_signal_count` | integer | Nombre minimum de signaux d'expansion — fait ressortir les mouvements à empreinte forte. |
| `ahead_of_pace` | boolean | Uniquement les entreprises évoluant plus vite que le rythme typique de ce marché. |
| `only_contraction` | boolean | Uniquement les marchés à risque / en contraction. |
| `min_markets` | integer | Nombre minimum de nouveaux marchés distincts qu'une entreprise a intégrés durant la fenêtre. |
### Données firmographiques
| Paramètre | Type | Signification |
| --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verticals`, `technologies` | string\[] | Filtres de secteur d'activité / stack technique de l'entreprise. |
| `employees` | number\[]\[] | Fourchettes d'effectifs, par ex. `[[50, 200]]`. |
| `founded_dates` | number\[] | Fourchette d'année de création `[from, to]`. |
| `revenues` | number\[] | Fourchette de revenus en USD `[from, to]`. |
| `keywords` | string\[] | Ciblage thématique en texte libre. |
| `companies` | string\[] | Cibler des entreprises spécifiques par n'importe quel mélange de `domain_search_id`, domaine, ou URL LinkedIn (les domaines / URL sont résolus vers leur entreprise la mieux classée). |
### Fenêtre temporelle et recherche
| Paramètre | Type | Signification |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transitioned_dates` | string\[] | Fenêtre de signal/transition sous forme de plage ISO `[from, to]`. |
| `window_days` | integer | Fenêtre glissante en jours, utilisée quand `transitioned_dates` n'est pas fourni. |
| `query` | string | Recherche en langage naturel — Pubrio l'interprète en filtres (renvoyés dans `filters`). |
| `is_explain_match` | boolean | Ajoute un `match_summary` généré par IA par entreprise, ancré dans ses signaux réels. Le nombre de signaux cités et la taille du lot évoluent avec `per_page` ; les sources à fort volume (offres d'emploi, campagnes publicitaires) sont résumées sous forme de comptage plutôt que listées individuellement. |
| `sort_by` | string | Ordre des résultats : `recent`, `expansion_score`, `signal_count`, ou `company_ranking`. Omettez pour l'ordre de pertinence par défaut — les paires corroborées (2+ types de signaux distincts) en premier, puis les paires à preuves répétées (3+ signaux), les plus récentes en premier au sein de chaque palier. Utilisez `recent` pour une pure récence. |
## Champs de réponse
### `stage` par entreprise / par marché
| Champ | Signification |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stage.slug` | L'étape actuelle (`exploring` … `scaling`). |
| `stage.expansion_score` | Rang de signification triable de 0 à 1. |
| `stage.scope` | Nouveau marché vs au sein d'une présence existante. |
| `stage.direction` | Trajectoire de l'étape : `advancing`, `steady`, `retreating`, ou `new`. C'est la vue côté réponse du même axe de **trajectoire** que vous filtrez avec le paramètre de requête `momentum` — les deux utilisent des jeux de valeurs différents, faites donc la correspondance en conséquence. |
| `stage.freshness` | Tranche d'ancienneté de la preuve la plus récente. |
| `stage.signal_count` | Nombre de signaux d'expansion actifs sur ce marché. |
| `stage.first_signal_at` / `latest_signal_at` / `last_transition_at` | Horodatages clés. |
### Signaux, présence et explication
| Champ | Signification |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signals[]` | La preuve sous-jacente : `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`. |
| `presence[]` | Empreinte connue sur le marché (bureaux/entités) : `presence_type`, `presence_strength`, `address`, `known_since`. |
| `timeline[]` | Historique des transitions d'étape : `stage_slug`, `transitioned_at`, `transition_kind`. |
| `other_markets[]` | Les autres marchés actifs de l'entreprise, chacun avec son étape et ses comptages. |
| `match_summary` | *(quand `is_explain_match: true`)* `{ text, citations }` — un « pourquoi ça correspond » généré par IA, ancré dans les signaux réels de cette entreprise. Chaque citation porte un champ `count` : `null` pour un signal individuel réel, ou un entier lorsque la citation est un comptage de volume sur une fenêtre (offres d'emploi, campagnes publicitaires) plutôt qu'un événement unique. |
`expansion_score` est un **rang triable** (comparable entre entreprises). Il est distinct de la confiance du modèle, que les réponses par clé API n'incluent que lorsque `is_include_metadata: true` est défini.