Referência de Campos da Expansion

Este é o dicionário de campos da Expansion API: o que cada filtro de requisição faz e o que cada campo de resposta significa. Para entender o porquê por trás do modelo, veja How Expansion Signals Work e o catálogo de valores em How Expansion Signals Work. Para uma lista sempre atualizada dos valores permitidos, chame o endpoint Expansion Taxonomy.

Dimensões principais

Toda expansão é descrita ao longo de alguns eixos independentes. Não os confunda:

Campo	O que captura	Valores de exemplo
`stage`	O quanto uma empresa avançou em um mercado	`exploring`, `committing`, `expanding`, `scaling`
`presence.level`	O quão consolidada já é a presença da empresa, independentemente do estágio	`established`, `emerging`, `none`, `no_data`
`momentum`	A trajetória do movimento neste momento	`advancing`, `steady`, `pulling_back`
flow	A direção do movimento entre mercados, expressa com `froms` / `tos`	saída (`froms`), entrada (`tos`), corredor (`froms`→`tos`)
`freshness`	O quão recente é a evidência	`fresh`, `cooling`, `stale`, `cold`
`scope`	Se é um novo mercado ou crescimento dentro de uma presença já existente	`entering_new_market`, `expanding_within_presence`, `established_only`
`expansion_score`	Uma classificação ordenável de 0 a 1 sobre o quão significativa é a expansão	`0.72`

Os slugs de estágio são exploring, committing, expanding e scaling — Exploring, Committing, Expanding, Scaling. established não é um estágio; é um presence.level, então filtrar por stages: ["established"] não corresponde a nada e retorna silenciosamente resultados sem filtro.

Flow (a direção do movimento) e momentum (a trajetória) são coisas diferentes. Filtrar por “empresas avançando” é momentum: ["advancing"]; filtrar por “empresas se expandindo para os EUA” é tos: ["US"]. Não existe um campo de requisição direction separado — o flow é definido inteiramente por froms / tos.

Filtros de requisição

Mercados (`froms` / `tos`)

Geografia é uma relação direcionada: empresas se expandem de uma origem para um destino. Duas listas expressam todos os casos — sem uma flag de direção separada.

Parâmetro	Tipo	Significado
`froms`	string[] (ISO alpha-2)	Mercados de origem — de onde a empresa está se expandindo (sua sede / matriz).
`tos`	string[] (ISO alpha-2)	Mercados de destino — para onde a empresa está se expandindo.
`exclude_froms`	string[] (ISO alpha-2)	Mercados de origem a excluir.
`exclude_tos`	string[] (ISO alpha-2)	Mercados de destino a excluir.

Você envia	Você recebe
`tos: ["US"]`	Todos que estão se expandindo para os EUA (entrada).
`froms: ["CN"]`	Empresas chinesas se expandindo para qualquer lugar (saída).
`froms: ["CN"]`, `tos: ["US"]`	Apenas o corredor CN → US.
nenhum	Todas as expansões, no mundo todo.

Filtros de sinais de expansão

Parâmetro	Tipo	Significado
`stages`	string[]	Limita a um ou mais estágios de expansão.
`momentum`	string[]	Limita pela trajetória (`advancing`/`steady`/`pulling_back`).
`freshness`	string[]	Limita pela atualidade da evidência (`fresh`/`cooling`/`stale`/`cold`).
`scopes`	string[]	Limita por `entering_new_market` / `expanding_within_presence` / `established_only`.
`signal_types`	string[]	Restringe a tipos de sinal específicos (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …).
`signal_strengths`	string[]	Filtra por faixa de confiança da evidência: `low`, `medium` ou `high`. (Diferente do `signal_strength_slug` por sinal, que vai até `very_high`.)
`min_signal_count`	integer	Número mínimo de sinais de expansão — destaca movimentos com pegada intensa.
`ahead_of_pace`	boolean	Apenas empresas se movendo mais rápido que o ritmo típico daquele mercado.
`only_contraction`	boolean	Apenas mercados em risco / em retração.
`min_markets`	integer	Número mínimo de novos mercados distintos que uma empresa entrou na janela.

Firmográficos

Parâmetro	Tipo	Significado
`verticals`, `technologies`	string[]	Filtros de indústria / stack de tecnologia da empresa.
`employees`	number[][]	Faixas de número de funcionários, por exemplo `[[50, 200]]`.
`founded_dates`	number[]	Faixa de ano de fundação `[de, até]`.
`revenues`	number[]	Faixa de receita em USD `[de, até]`.
`keywords`	string[]	Delimitação de tema por texto livre.
`companies`	string[]	Restringe a empresas específicas por qualquer combinação de `domain_search_id`, domínio ou URL do LinkedIn (domínios / URLs são resolvidos para a empresa de melhor classificação).

Janela de tempo e busca

Parâmetro	Tipo	Significado
`transitioned_dates`	string[]	Janela de sinal/transição como uma faixa ISO `[de, até]`.
`window_days`	integer	Janela móvel em dias, usada quando `transitioned_dates` não é informado.
`query`	string	Busca em linguagem natural — a Pubrio a interpreta em filtros (ecoada de volta em `filters`).
`is_explain_match`	boolean	Adiciona um `match_summary` de IA por empresa, fundamentado em seus sinais reais. A contagem de sinais citados e o tamanho do lote escalam com `per_page`; fontes de alto volume (vagas de emprego, campanhas de anúncios) são resumidas como uma contagem em vez de listadas individualmente.
`sort_by`	string	Ordenação dos resultados: `recent`, `expansion_score`, `signal_count` ou `company_ranking`. Omita para a ordem de relevância padrão — pares corroborados (2+ tipos de sinal distintos) primeiro, depois pares com evidência repetida (3+ sinais), mais recentes primeiro dentro de cada nível. Use `recent` para pura recência.

Campos de resposta

`stage` por empresa / por mercado

Campo	Significado
`stage.slug`	O estágio atual (`exploring` … `scaling`).
`stage.expansion_score`	Classificação ordenável de significância de 0 a 1.
`stage.scope`	Novo mercado vs. dentro de uma presença já existente.
`stage.direction`	Trajetória do estágio: `advancing`, `steady`, `retreating` ou `new`. Esta é a visão do lado da resposta do mesmo eixo de trajetória que você filtra com o parâmetro de requisição `momentum` — os dois usam conjuntos de valores diferentes, então mapeie de acordo.
`stage.freshness`	Faixa de atualidade da evidência mais recente.
`stage.signal_count`	Número de sinais de expansão ativos nesse mercado.
`stage.first_signal_at` / `latest_signal_at` / `last_transition_at`	Marcações de tempo importantes.

Sinais, presença e explicação

Campo	Significado
`signals[]`	A evidência subjacente: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`.
`presence[]`	Pegada conhecida no mercado (escritórios/entidades): `presence_type`, `presence_strength`, `address`, `known_since`.
`timeline[]`	Histórico de transição de estágios: `stage_slug`, `transitioned_at`, `transition_kind`.
`other_markets[]`	Os outros mercados ativos da empresa, cada um com seu estágio + contagens.
`match_summary`	(quando `is_explain_match: true`) `{ text, citations }` — um “por que corresponde” gerado por IA, citado a partir dos sinais reais dessa empresa. Cada citação carrega um campo `count`: `null` para um sinal individual real, ou um número inteiro quando a citação é uma contagem de volume delimitada por janela (vagas de emprego, campanhas de anúncios) em vez de um evento único.

expansion_score é uma classificação ordenável (comparável entre empresas). É diferente da confiança do modelo, que as respostas com chave de API incluem apenas quando is_include_metadata: true está definido.

Base de Conhecimento

Guias

Conceitos

Estudos de Caso

Dimensões principais

Filtros de requisição

Mercados (`froms` / `tos`)

Filtros de sinais de expansão

Firmográficos

Janela de tempo e busca

Campos de resposta

`stage` por empresa / por mercado

Sinais, presença e explicação

​Dimensões principais

​Filtros de requisição

​Mercados (froms / tos)

​Filtros de sinais de expansão

​Firmográficos

​Janela de tempo e busca

​Campos de resposta

​stage por empresa / por mercado

​Sinais, presença e explicação

Dimensões principais

Filtros de requisição

Mercados (`froms` / `tos`)

Filtros de sinais de expansão

Firmográficos

Janela de tempo e busca

Campos de resposta

`stage` por empresa / por mercado

Sinais, presença e explicação