gtm) para la investigación de ventas y marketing,
con las seis capacidades que se indican a continuación.
Una Capability es un elemento de esa Solution, como company_intelligence
o people_search. Cada una tiene un conjunto fijo de acciones y entradas compatibles.
¿Por qué usar una Solution?
Por ejemplo, Company intelligence puede buscar una empresa por dominio. Envíasdomain; Glasser selecciona un proveedor de datos compatible, asigna la entrada a su endpoint
y puede probar otro proveedor de datos elegible si se producen errores compatibles.
Así, los formatos de entrada específicos de cada proveedor de datos quedan fuera de tu integración: envías
domain, independientemente de que el proveedor de datos seleccionado espere domain, website o
company_website.
Usa una Solution cuando sus entradas cubran tu tarea. Si necesitas un endpoint específico,
todas sus opciones de entrada o su Price exacto antes de la ejecución, usa
search, inspect
y run para seleccionarlo y llamarlo directamente.
Capacidades disponibles
Cada Capability tiene su propia ruta de solicitud en/v1/solutions/gtm/.
La referencia de cada Capability enumera sus acciones compatibles, proveedores de datos y
campos obligatorios. La mayoría usa
action para seleccionar qué hacer; Social research usa
platform y mode.
Ejemplo: obtener el perfil de una empresa
Configura tu Key como se describe en la descripción general de la API. Esta solicitud ejecuta una recuperación de datos de pago:domain es el único campo obligatorio del cuerpo. Si omites action
se usa enrich; si omites provider se usa auto. metadata es opcional y puede
omitirse. Conserva el mismo Idempotency-Key al reintentar esta solicitud; elige un valor nuevo para una
consulta nueva o una solicitud diferente.
Cómo funciona la selección del proveedor de datos
Con
auto, Glasser puede probar el siguiente proveedor de datos elegible después de un error del proveedor de datos,
un tiempo de espera o la indisponibilidad del endpoint. La búsqueda no cambia de proveedor de datos si el resultado está vacío.
Fetch (scrape) también puede cambiar de proveedor de datos si la salida está vacía o no es válida, o si faltan
formatos compatibles, dentro del presupuesto de la solicitud. El texto y la longitud del contenido no activan el cambio de proveedor.
Cada endpoint seleccionado debe admitir tus entradas y estar permitido por tu Key.
Resultados y cargos
Cada acción de Web research devuelveoutput normalizado. Scrape expone
text, markdown, html y raw_html; los formatos que faltan son null. Search expone
output.results[]; news, places, scholar, shopping, images, videos y similares exponen
output.items[] con campos fijos por fila; answer expone output.answer y citations[]. La salida nativa del proveedor de datos no se repite en output; permanece
en el Run y se puede leer con Get Run. Glasser no convierte HTML en texto ni combina capturas.
Lee result_status para conocer la entrega: success, partial, no_result, error o
pending. Los formatos solicitados que faltan aparecen en missing_formats. Los errores de entrega
tienen output: null y un error. La semántica del contenido no está verificada.
charge_usd es el total de los runs enumerados, incluidos los errores con cargo y
los resultados vacíos. Cada Run tiene su propio cargo y cláusula en runs[]. Un Run
no liquidado hace que el total sea null; varios Run no tienen un único charge_basis de nivel superior.
id, provider y status en mayúsculas siguen describiendo el Run final.
POST devuelve HTTP 200 para un Run terminado y 202 mientras está en curso. Consulta el
result_url devuelto en el origen de la API con tu Key para conservar la salida normalizada
y los cargos totales. Esta lectura devuelve HTTP 200 incluso mientras está pendiente; comprueba el cuerpo.
La consulta no crea Run y no reanuda el cambio de proveedor de datos. Get Run
conserva la salida nativa y el cargo individual. Los plugins antiguos que solo consultan Get Run
deben actualizar su ruta de consulta. COMPLETED por sí solo no demuestra que el contenido sea utilizable.
SEO research devuelve output normalizado para cada acción. Las acciones de lista exponen
output.items[] con campos fijos por fila (por ejemplo, ranked_keywords: keyword,
position, url, volume, cpc_usd, traffic); las acciones de resumen exponen
campos fijos de nivel superior (por ejemplo, backlinks_overview: backlinks, referring_domains,
semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks,
nofollow_backlinks). La salida nativa del proveedor de datos seleccionado
permanece en el Run, no en output. Un valor que el proveedor de datos no informa es null; el dinero siempre está en USD. Las puntuaciones de autoridad no se convierten entre proveedores de datos: cada uno conserva su propio nombre y escala, y solo se completa el campo del proveedor de datos que responde. volume, traffic y cpc_usd
son estimaciones propias de cada proveedor de datos; compáralas dentro de un mismo proveedor de datos. result_status es success, no_result, error o pending, y las reglas de cargos y consultas anteriores se aplican sin cambios. La lista de campos por acción está en la referencia de
SEO research.
Company intelligence devuelve output normalizado para cada acción: enrich y traffic
exponen campos fijos de nivel superior, tech_stack, competitors, news y jobs exponen output.items[],
funding expone total_funding_usd más items[], y ads expone total_ads más items[]. Los grupos de empleados e ingresos se
separan en *_range_min / *_range_max, y las puntuaciones de similitud incluyen el nombre del proveedor de datos
(predictleads_similarity_score, exa_similarity_score). La lista de campos por acción está en la referencia de
Company intelligence.
Market data devuelve output normalizado para cada acción con un conjunto de campos de propiedades
(address, property_type, bedrooms, bathrooms, living_area_sqft, lot_size_sqft,
year_built, latitude, longitude). La búsqueda de propiedades añade campos del propietario; los anuncios añaden
campos del anuncio, MLS, HOA, agente y oficina; los anuncios de venta usan price_usd y los anuncios de alquiler
monthly_rent_usd; las estimaciones informan comparables_count. Las cotizaciones bursátiles incluyen currency,
price de la sesión ordinaria, change, change_percent (puntos porcentuales), la
cotización extended_hours_* y as_of_text. Consulta la referencia de Market data
para ver los campos de cada acción.
Social research devuelve output normalizado por modo, compartido por las seis plataformas: una
cuenta para profile, output.items[] de publicaciones para search y feed, una publicación para post y
output.profiles[] para find. Las publicaciones incluyen title, text (solo el cuerpo) y
published_at; consulta la referencia de Social research.
People search devuelve output normalizado para cada acción: search expone total_matches
y output.items[], una fila por persona, y enrich y find_email exponen una persona con
los mismos campos en el nivel superior. Los nombres, cargos, seniority y department son los que
informa el proveedor de datos. email_status es la etiqueta de verificación propia del proveedor de datos; léela con
email_catch_all y email_source (Hunter generated significa que la dirección se creó a partir del
patrón del dominio). find_email sin correo electrónico es no_result. Consulta la referencia de
People search para ver los campos.
Convenciones de campos
Cadaoutput normalizado sigue las mismas reglas de nomenclatura:
Los controles de Fetch son
formats, timeout_ms (predeterminado: 90000), max_charge_usd
(opcional) y cache_max_age_seconds (opcional). Los formatos orientan la selección y el cambio de proveedor de datos;
los formatos disponibles aparecen en los campos de salida fijos. El límite de cargos incluye
todos los Run de esta solicitud, incluidos los Run repetidos. Un Run no liquidado detiene el cambio de proveedor de datos.
Reintentar con la misma clave reutiliza los Run e inicia una nueva ventana de tiempo de solicitud.
Auto usa Serper y después Firecrawl. Las solicitudes de HTML o de antigüedad de caché explícita van
directamente a Firecrawl. Las rutas de enriquecimiento de X/Twitter y LinkedIn están excluidas de Firecrawl.
Las solicitudes explícitas de solo texto usan Serper. Exa está disponible mediante selección explícita.
Cada llamada al proveedor de datos comienza con la ventana de su Endpoint; cuando esa ventana
excedería el presupuesto de la solicitud, Serper, Firecrawl y Exa usan la ventana de llamadas
restante real y reservan tiempo para la liquidación y la respuesta; si queda menos de un segundo
de tiempo de llamada, se omite ese paso.
Si no se puede admitir ningún Run, la API devuelve el error de admisión. Si el presupuesto
impide continuar con el cambio de proveedor de datos, informa de la entrega del último Run admitido y de todos los cargos admitidos.
Las Firecrawl Data Sources usan la misma salida nativa del Run y no
cambian de proveedor de datos. Fetch Solution añade enrutamiento, comprobaciones estructurales,
comprobaciones de formato y un presupuesto de solicitud compartido. Su respuesta de search/scrape sigue el contrato normalizado anterior.
El metadata opcional almacena tus valores de seguimiento y no afecta a la selección del proveedor de datos ni al Price.