gtm) para pesquisa de vendas e marketing,
com as seis capacidades listadas abaixo.
Uma Capability é um membro dessa Solution, como company_intelligence
ou people_search. Cada uma tem um conjunto fixo de ações e entradas compatíveis.
Por que usar uma Solution?
Por exemplo, Company intelligence pode buscar uma empresa por domínio. Você enviadomain; o Glasser seleciona um provedor de dados compatível, mapeia a entrada para o endpoint
correspondente e pode tentar outro provedor de dados elegível em caso de falhas compatíveis.
Isso mantém os formatos de entrada específicos de cada provedor de dados fora da sua integração: você envia
domain independentemente de o provedor de dados selecionado esperar domain, website ou
company_website.
Use uma Solution quando suas entradas abrangerem sua tarefa. Se precisar de um endpoint específico,
de todas as opções de entrada ou do Price exato antes da execução, use
search, inspect e
run para selecioná-lo e chamá-lo diretamente.
Capacidades disponíveis
Cada Capability tem seu próprio caminho de requisição em/v1/solutions/gtm/.
A referência de cada Capability lista suas ações compatíveis, provedores de dados e
campos obrigatórios. A maioria usa
action para selecionar o que fazer; Social research usa
platform e mode.
Exemplo: obter um perfil de empresa
Configure sua Key conforme descrito na visão geral da API. Esta requisição executa uma recuperação de dados paga:domain é o único campo obrigatório do corpo. Omitir action
usa enrich; omitir provider usa auto. metadata é opcional e pode ser
omitido. Mantenha o mesmo Idempotency-Key ao repetir esta requisição; escolha um novo
valor para uma nova consulta ou uma requisição diferente.
Como funciona a seleção do provedor de dados
Com
auto, o Glasser pode tentar o próximo provedor de dados elegível após um erro do provedor de dados,
timeout ou indisponibilidade do endpoint. A pesquisa não faz fallback quando o resultado está vazio.
Fetch (scrape) também pode fazer fallback em caso de saída vazia ou inválida e de formatos compatíveis ausentes,
dentro do orçamento da requisição. O texto e o comprimento do conteúdo não acionam o fallback.
Cada endpoint selecionado deve ser compatível com suas entradas e permitido pela sua Key.
Resultados e cobranças
Toda ação de Web research retornaoutput normalizado. Scrape expõe
text, markdown, html e raw_html; formatos ausentes são nulos. Search expõe
output.results[]; news, places, scholar, shopping, images, videos e similares expõem
output.items[] com campos fixos por linha; answer expõe output.answer e citations[]. A saída nativa do provedor de dados não é repetida em output; ela permanece
no Run e pode ser lida com Get Run. O Glasser não converte HTML em texto nem combina capturas.
Leia result_status para a entrega: success, partial, no_result, error ou
pending. Os formatos solicitados ausentes aparecem em missing_formats. Erros de entrega
têm output: null e um error. A semântica do conteúdo permanece não verificada.
charge_usd é o total dos runs listados, incluindo falhas cobradas e
resultados vazios. Cada Run tem sua própria cobrança e cláusula em runs[]. Um Run
não liquidado torna o total nulo; vários Runs não têm um único charge_basis no nível superior.
id, provider e status em maiúsculas ainda descrevem o Run final.
POST retorna HTTP 200 para um Run terminal e 202 enquanto está em andamento. Consulte o
result_url retornado na origem da API com sua Key para manter a saída normalizada
e o total das cobranças. Essa leitura retorna HTTP 200 mesmo enquanto estiver pendente; verifique o corpo.
A consulta não cria Runs nem retoma o fallback. Get Run
mantém a saída nativa e a cobrança individual. Plugins mais antigos que consultam apenas Get Run
devem atualizar seu caminho de consulta. COMPLETED sozinho não comprova que o conteúdo é utilizável.
SEO research retorna output normalizado para cada ação. Ações de lista expõem
output.items[] com campos fixos por linha (por exemplo, ranked_keywords: keyword,
position, url, volume, cpc_usd, traffic); ações de visão geral expõem campos fixos
no nível superior (por exemplo, backlinks_overview: backlinks, referring_domains,
semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks,
nofollow_backlinks). A saída nativa do provedor de dados selecionado
permanece no Run, não em output. Um valor que o provedor de dados não informa é null; valores monetários são
sempre USD. As pontuações de autoridade não são convertidas entre provedores de dados: cada um mantém seu próprio
nome e escala, e somente o campo do provedor de dados que respondeu é preenchido. volume, traffic e cpc_usd
são estimativas próprias de cada provedor de dados; compare-as dentro de um único provedor de dados. result_status é success, no_result, error ou pending, e as
regras de cobrança e consulta acima se aplicam sem alteração. A lista de campos por ação está na referência de
SEO research.
Company intelligence retorna output normalizado para cada ação: enrich e traffic
expõem campos fixos no nível superior, tech_stack, competitors, news e jobs expõem output.items[],
funding expõe total_funding_usd mais items[], e ads expõe total_ads mais items[]. As faixas de funcionários e receita são
separadas em *_range_min / *_range_max, e as pontuações de similaridade contêm o nome do provedor de dados
(predictleads_similarity_score, exa_similarity_score). A lista de campos por ação está na referência de
Company intelligence.
Market data retorna output normalizado para cada ação com um conjunto de campos imobiliários
(address, property_type, bedrooms, bathrooms, living_area_sqft, lot_size_sqft,
year_built, latitude, longitude). A pesquisa de imóveis adiciona campos do proprietário, os anúncios adicionam
campos de anúncio, MLS, HOA, agente e escritório, os anúncios de venda usam price_usd e os anúncios de aluguel
monthly_rent_usd, e as estimativas informam comparables_count. As cotações de ações incluem currency,
o price da sessão regular, change, change_percent (pontos percentuais), a
cotação extended_hours_* e as_of_text. Consulte a referência de Market data
para ver os campos de cada ação.
Social research retorna output normalizado por modo, compartilhado pelas seis plataformas: uma
conta para profile, output.items[] de publicações para search e feed, uma publicação para post
e output.profiles[] para find. As publicações contêm title, text (somente o corpo) e
published_at; consulte a referência de Social research.
People search retorna output normalizado para cada ação: search expõe total_matches
e output.items[], uma linha por pessoa, e enrich e find_email expõem uma pessoa com
os mesmos campos no nível superior. Nomes, cargos, seniority e department são informados conforme o
provedor de dados os retorna. email_status é o rótulo de verificação próprio do provedor de dados; leia-o com
email_catch_all e email_source (generated do Hunter significa que o endereço foi construído a partir do
padrão do domínio). find_email sem um e-mail é no_result. Consulte a referência de
People search para ver os campos.
Convenções de campos
Todooutput normalizado segue as mesmas regras de nomenclatura:
Os controles de Fetch são
formats, timeout_ms (padrão 90000), max_charge_usd
(opcional) e cache_max_age_seconds (opcional). Os formatos orientam a seleção e
o fallback; os formatos disponíveis aparecem nos campos de saída fixos. O limite de cobrança inclui
todos os Runs desta requisição, incluindo Runs reproduzidos. Um Run não liquidado interrompe o fallback.
Repetir a mesma chave reutiliza Runs e inicia uma nova janela de tempo da requisição.
O modo Auto usa Serper e depois Firecrawl. Solicitações de HTML ou de idade de cache explícita vão diretamente
para o Firecrawl. As rotas de enriquecimento do X/Twitter e do LinkedIn são excluídas do Firecrawl.
Solicitações explícitas somente de texto usam o Serper. O Exa está disponível por seleção explícita.
Cada chamada ao provedor de dados começa com a janela de seu Endpoint; quando essa janela
excederia o orçamento da solicitação, Serper, Firecrawl e Exa usam a janela real de chamadas
restante, reservando tempo para liquidação e resposta; se restar menos de um segundo
de tempo de chamada, a etapa será ignorada.
Se nenhum Run puder ser admitido, a API retornará o erro de admissão. Se o orçamento
impedir novos fallbacks, ela informará a entrega do último Run admitido e todas as cobranças admitidas.
As Firecrawl Data Sources usam a mesma saída nativa do Run e não
alternam entre provedores de dados. A Fetch Solution adiciona roteamento, verificações estruturais,
verificações de formato e um orçamento compartilhado de requisições. A resposta de search/scrape segue o contrato normalizado acima.
O metadata opcional armazena seus valores de acompanhamento e não afeta a seleção do provedor de dados nem o Price.