/companies/search, /people/search, /companies/advertisements/search) compartilham um único mecanismo de filtro. Você compõe um corpo de requisição uma vez e as mesmas regras se aplicam em todos os endpoints — incluindo a forma como os filtros multivalorados se combinam, como as localizações são comparadas e como você substitui o operador padrão com filter_conditions.
Por que um mecanismo de filtro unificado?
Um esquema, três endpoints
Filtros em nível de empresa como
technologies, verticals e founded_dates funcionam de forma idêntica em /companies/search, /people/search e dentro de company_filters em Monitores — você aprende uma vez.AND/OR por filtro
O padrão é OR (corresponde a qualquer). Promova filtros individuais para AND (corresponde a todos) adicionando uma entrada a
filter_conditions — sem tocar no restante do corpo.Filtrado antes de paginar
Todos os filtros são aplicados antes de os resultados serem retornados, então cada página e cada total refletem a sua requisição inteira. Sem pós-filtragem no lado da aplicação.
Os mesmos filtros em Monitores
O bloco
company_filters em Monitores aceita o mesmo formato, então um payload de busca funcional também é um payload de monitor funcional.Anatomia de uma requisição de busca
Toda requisição de busca é construída a partir de três camadas no mesmo corpo JSON:
Uma requisição mínima a
/people/search que usa as três camadas:
company_filters: mantenha as chaves de empresa agrupadas
O objeto wrapper company_filters: {...} é a forma recomendada de enviar filtros em nível de empresa — ele separa visualmente quais chaves filtram a pessoa das que filtram a empresa, e corresponde ao formato que os Monitores já usam, de modo que os payloads são transferidos sem atrito entre configurações de busca e de monitor.
Os dois estilos funcionam; o mecanismo achata a forma agrupada para o nível superior antes de processar, e as chaves de nível superior prevalecem em caso de conflito:
filter_conditions para uma chave em nível de empresa, coloque-a dentro de company_filters, para que ela viaje junto com as chaves que substitui.
Mesmo formato nas variantes /search/similar
POST /companies/search/similar e POST /people/search/similar aceitam o mesmo corpo de filtro que suas contrapartes não similares (incluindo o wrapper company_filters e filter_conditions). Cada uma adiciona uma etapa de similaridade por cima:
Os filtros restringem o conjunto de candidatos antes de a similaridade ser aplicada — então combinar
company_locations: ["US"] com /people/search/similar retorna as pessoas mais próximas baseadas nos EUA em relação aos seus cargos de referência, o que é o padrão “encontrar mais pessoas como X dentro destas restrições”.
/companies/search/similar retorna data como um array simples de empresas — não há um objeto pagination. Percorra os resultados com page e per_page. Use a busca por similaridade para encontrar as melhores correspondências, não para enumerar todas elas.AND vs OR — a única decisão que você toma por filtro
Filtros multivalorados (technologies, verticals, keywords, categories, …) aceitam um array. O operador decide o que “corresponder” significa:
- OR (padrão)
- AND
Corresponde a qualquer valor. Retorna linhas cujo array se sobrepõe à entrada.Uma empresa é incluída se a sua pilha de tecnologia contiver pelo menos uma de
Python, PostgreSQL ou Kubernetes.Use quando: você quer alcance amplo — “interessado em qualquer uma destas”, “localizada em qualquer um destes países”.Filtros não listados em
filter_conditions usam o operador padrão (OR dentro de um array, AND entre chaves de filtro distintas). Você só declara as substituições — nunca os padrões.O que você pode substituir
Cada endpoint aceita substituições para um conjunto diferente de chaves. As chaves vêm do enum OpenAPI em cada esquema*_filter_conditions:
Endpoint de empresa
Chaves de
company_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media, advertisement_target_locations, job_exclude_locations.Endpoint de pessoas
Chaves de
people_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media.Endpoint de anúncios
Chaves de
ads_filter_conditions: target_locations, publisher_platforms.Dicas de desempenho
Comece pelos filtros mais restritivos
Comece pelos filtros mais restritivos
Localizações, faixas de funcionários e
founded_dates reduzem o conjunto de candidatos mais rápido do que filtros de texto livre ou de vertical. Combine-os com um ou dois filtros precisos antes de recorrer à busca por similaridade.Não abuse do AND em arrays grandes
Não abuse do AND em arrays grandes
AND exige que todo valor esteja presente. Um AND com 10 tecnologias retorna quase nenhuma linha. Prefira 2-4 valores por filtro AND; mude para OR em consultas exploratórias.
Use is_enable_similarity_search para entrada em texto livre
Use is_enable_similarity_search para entrada em texto livre
Se você não pode fornecer IDs de slug (verticais, tecnologias, categorias) e só tem strings em texto livre, defina
is_enable_similarity_search: true e similarity_score: 0.7. O mecanismo resolve as correspondências antes de aplicar o filtro — muito mais barato do que varrer texto.Prefira faixas em vez de listas de enum para porte e receita
Prefira faixas em vez de listas de enum para porte e receita
employees: [[201, 500], [501, 1000]] (um array de faixas) e revenues: [1000000, 5000000] (uma única faixa mín/máx) são mais rápidos e mais idiomáticos do que listas longas de IDs.Filtros de atividade publicitária
/companies/search pode filtrar pela pegada publicitária de uma empresa — quantos anúncios ela veicula, se algum está ativo no momento, quais plataformas e formatos ela usa, e como ela se classifica em relação a outros anunciantes em um determinado país. POST /companies/advertisements/search também aceita cada um desses filtros (advertisement_active_ads, advertisement_running_ads, advertisement_total_ads, advertisement_platform_count, advertisement_format_count, advertisement_impressions_estimate, advertisement_formats, advertisement_country_activity) — um anúncio é incluído se a empresa proprietária atender ao limite.
Use
null para um limite aberto — [1, null] significa “pelo menos 1”, [null, 500] significa “500 ou menos”.
Classificação dentro de um país
advertisement_country_activity restringe a classificação, o percentil e a pontuação de volume a um país por vez — a classificação de anúncios de uma empresa nos EUA não diz nada sobre sua classificação na Alemanha, então country é obrigatório:
advertisement_country_activity com os filtros de todos os países acima na mesma requisição — por exemplo, “classificado entre os 500 primeiros nos EUA, e com pelo menos 100 anúncios ativos em toda a empresa”:
Ordenando os resultados
Filtrar poradvertisement_country_activity restringe quais empresas retornam; por si só, isso não define a ordem. Para obter primeiro os maiores anunciantes daquele mercado, peça sort_by: "advertisement_country_rank":
advertisement_country_activity estiver presente, cada empresa também traz sua posição naquele país, para que você possa exibir a classificação usada no filtro:
sort_by: "advertisement_country_rank" é ignorado quando advertisement_country_activity está ausente, já que uma classificação só existe dentro de um país. Passe is_ascending_order: false para listar primeiro os menores anunciantes do mercado.
Encontrando novos entrantes em um mercado
advertisement_country_activity também aceita duas janelas de data, então você pode perguntar quem começou a anunciar em um mercado, em vez de quem já é grande nele:
Empresas que entraram no Japão desde o início de julho:
null para uma janela aberta. As datas são interpretadas no fuso horário da requisição. Uma empresa cujos anúncios não têm data de início não tem valor de primeira aparição e é tratada como desconhecida — ela nunca é reportada como nova. Combine com as chaves de classificação no mesmo objeto para restringir ainda mais, por exemplo, novos entrantes que já gastam muito.
Próximos passos
filter_conditions
Página de referência — cada chave suportada, cada padrão, e receitas AND/OR copiáveis.
Filtros de Pessoas + Empresa
Use qualquer filtro de empresa dentro de
/people/search. O principal novo recurso do mecanismo unificado.Referência de Company Search
Esquema completo de requisição/resposta para
/companies/search.Referência de People Search
Esquema completo de requisição/resposta para
/people/search.Procurando o passo a passo de filtragem no painel? Veja Filtragem e Exportação de Contatos na Base de Conhecimento.