Search

API de resultados de buscadores (SERP) para consultar motores de búsqueda y obtener resultados estructurados.

Introducción

La API Search de AnyCrawl te permite acceder por programación a resultados de varios motores de búsqueda. Pensada para modelos de lenguaje grandes (LLM), devuelve datos limpios y estructurados, optimizados para análisis y procesamiento con IA.

La API devuelve datos de inmediato y de forma síncrona; no hace falta polling ni webhooks. Admite varios motores y varias páginas de resultados en una sola solicitud para recopilar datos de forma exhaustiva.

Funciones principales

Varios motores: ahora Google; previstos más motores
Optimizada para LLM: JSON estructurado adecuado para IA
Multidioma: búsqueda en distintos idiomas y regiones
Multipágina: varias páginas de resultados en una petición
Rendimiento: alta concurrencia nativa con procesamiento asíncrono
Respuesta inmediata: API síncrona; resultados al instante sin polling
Resultados completos: resultados de búsqueda y sugerencias

Endpoint de la API

POST https://api.anycrawl.dev/v1/search

Ejemplos de uso

Búsqueda básica (Google por defecto)

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "OpenAI ChatGPT"
  }'

Búsqueda multipágina

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "machine learning tutorials",
    "pages": 3,
    "limit": 10
  }'

Búsqueda con idioma/región

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "AnyCrawl",
    "lang": "zh",
    "pages": 2
  }'

Búsqueda con paginación

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "web scraping tools",
    "offset": 20,
    "limit": 10
  }'

Búsqueda con búsqueda segura

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "educational content",
    "safe_search": 0
  }'

Parámetros de la solicitud

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Consulta de búsqueda a ejecutar
`template_id`	string	No	-	ID de plantilla para esta búsqueda
`variables`	object	No	-	Variables de plantilla (solo si hay `template_id`)
`engine`	enum	No	`google`	Motor de búsqueda. Actualmente: `google`
`limit`	number	No	10	Máximo de resultados por página
`offset`	number	No	0	Resultados a omitir (paginación)
`pages`	number	No	1	Páginas de resultados a obtener (mín: 1, máx: 20)
`lang`	string	No	`en`	Locale de idioma (p. ej. 'en', 'zh', 'es', 'fr')
`country`	string	No	-	Locale de país (p. ej. 'US', 'GB', 'CN')
`timeRange`	enum	No	-	Filtro temporal: `day`, `week`, `month`, `year`
`sources`	enum	No	-	Orígenes: `web`, `images`, `news` (SearXNG)
`safe_search`	number \| null	No	null	Nivel de búsqueda segura en Google: `0` (off), `1` (medium), `2` (high) o null (predeterminado). Solo Google.

Opcional: `scrape_options` para URL de resultados

Si se indica, cada URL de resultado puede scrapearse con esas opciones (mismos campos que /v1/scrape salvo url de nivel superior). Las opciones solo de navegador se ignoran si no hay navegador.

| Field | Type | Default | Notes | | ------------------- | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | engine | enum | - | Motor de scrape para resultados: auto, cheerio, playwright, puppeteer | | formats | array of enum | ["markdown"] | Formatos: markdown, html, text, screenshot, screenshot@fullPage, rawHtml, json, summary, links | | timeout | number | 60000 | Tiempo de espera por solicitud (ms) | | wait_for | number | - | Retraso antes de extraer (ms); solo navegadores; menor prioridad que wait_for_selector | | wait_until | enum | - | Condición de espera de navegación: load, domcontentloaded, networkidle, commit | | wait_for_selector | string, object, or array | - | Wait for one or multiple selectors (browser engines only). Accepts a CSS selector string, an object { selector: string, state?: "attached" | "visible" | "hidden" | "detached", timeout?: number }, or an array mixing strings/objects. Each entry is awaited sequentially. Takes priority over wait_for. | | include_tags | array of string | - | Solo elementos que coincidan con selectores CSS | | exclude_tags | array of string | - | Excluir elementos que coincidan con selectores CSS | | only_main_content | boolean | true | Solo contenido principal, sin cabeceras, pies, navegación (include_tags tiene prioridad) | | proxy | string (URI) | - | URL de proxy opcional | | json_options | object | - | Extracción JSON estructurada (schema, user_prompt, schema_name, schema_description) | | extract_source | enum | markdown | Fuente para JSON: markdown (predeterminado) o html | | ocr_options | boolean | false | OCR solo para imágenes en markdown; no afecta a html/rawHtml. | | max_age | number | - | Antigüedad máxima de caché (ms). 0 omite lectura; omite para el valor predeterminado | | store_in_cache | boolean | true | Si escribir caché de página por resultado scrapeado |

Motores de búsqueda admitidos

`google` (predeterminado)

Caso de uso: búsqueda web general con resultados amplios
Ventajas: resultados completos; varios idiomas y regiones
Funciones: resultados y sugerencias; búsqueda segura (off/medium/high)
Recomendado para: búsqueda general, investigación, descubrimiento
Búsqueda segura: parámetro safe_search: 0, 1, 2 o null (predeterminado)

Formato de respuesta

Respuesta correcta (HTTP 200)

Búsqueda correcta

{
    "success": true,
    "data": [
        {
            "title": "AlsoAsked: People Also Ask keyword research tool",
            "url": "https://alsoasked.com/",
            "description": "Find the questions people also ask. Enter a question, brand or search query. e.g. 'keyword research'.",
            "source": "Google Search Result"
        },
        {
            "title": "OpenAI ChatGPT Features and Benefits",
            "url": "https://openai.com/chatgpt",
            "description": "ChatGPT is an AI assistant that can help with writing, research, and problem-solving.",
            "source": "Google Search Result"
        },
        {
            "title": "Keyword tool",
            "source": "Google Suggestions"
        }
    ]
}

Tipos de resultado

La API devuelve dos tipos:

Resultados de búsqueda: entradas con título, URL, descripción y origen
Sugerencias: consultas relacionadas del motor

Respuestas de error

400 - Error de validación

{
    "success": false,
    "error": "Validation error",
    "details": {
        "issues": [
            {
                "field": "engine",
                "message": "Invalid enum value. Expected 'google', received 'invalid'",
                "code": "invalid_enum_value"
            }
        ],
        "messages": ["Invalid enum value. Expected 'google', received 'invalid'"]
    }
}

401 - Error de autenticación

{
    "success": false,
    "error": "Invalid API key"
}

402 - Pago requerido

{
    "success": false,
    "error": "Insufficient credits. Please upgrade your plan or purchase more credits."
}

Buenas prácticas

Elección del motor

Búsqueda web general → google (único motor admitido por ahora)
Varios idiomas → indica lang adecuado
Investigación amplia → usa varias páginas de resultados

Rendimiento

Lotes: usa pages para varias páginas en una sola petición
Idioma: especifica idioma para resultados locales
Consulta: palabras clave concretas mejoran la calidad

Manejo de errores

try {
    const response = await fetch("/v1/search", {
        method: "POST",
        headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            query: "artificial intelligence",
            pages: 2,
        }),
    });

    const result = await response.json();

    if (result.success) {
        // Handle successful result
        console.log("Found results:", result.data.length);

        // Separate search results from suggestions
        const searchResults = result.data.filter((item) => item.url);
        const suggestions = result.data.filter((item) => !item.url);

        console.log("Search Results:", searchResults.length);
        console.log("Suggestions:", suggestions.length);
    } else {
        // Handle search failure
        console.error("Search failed:", result.error);
    }
} catch (error) {
    // Handle network error
    console.error("Request failed:", error);
}

Uso con alta concurrencia

La API admite alta concurrencia de forma nativa. Puedes lanzar muchas búsquedas simultáneas sin un límite de velocidad restrictivo:

// Concurrent searching example
const queries = ["machine learning", "artificial intelligence", "data science"];

const searchPromises = queries.map((query) =>
    fetch("/v1/search", {
        method: "POST",
        headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ query, engine: "google", pages: 2 }),
    }).then((res) => res.json())
);

// All requests execute concurrently and return immediately
const results = await Promise.all(searchPromises);
console.log(`Completed ${results.length} searches simultaneously`);

Límites de velocidad y créditos

Cada búsqueda consume créditos según el número de páginas solicitadas
Consumo = número de páginas (p. ej. pages: 3 = 3 créditos)
Sin límite de velocidad para solicitudes concurrentes: alta concurrencia nativa
Vigila el uso de créditos en las cabeceras de respuesta

Preguntas frecuentes

P: ¿Cuándo usar distintos idiomas?

Inglés (en): resultados globales e internacionales
Chino (zh): contenido en chino y China
Variantes regionales (p. ej. en-GB, fr-CA): resultados por país/región

P: ¿Por qué hay menos resultados de los esperados?

R: Por ejemplo:

Consulta demasiado específica o términos poco habituales
Desajuste entre la consulta y lang
Limitaciones del motor para ciertos temas o regiones
Problemas de red

P: ¿Cómo buscar en una región concreta?

R: La API ajusta regiones según lang. Consejos:

Usa códigos de idioma que coincidan con la región (p. ej. en-GB para Reino Unido)
Añade términos regionales en la consulta si hace falta

P: ¿Diferencia entre resultados y sugerencias?

Resultados: título, URL, descripción y origen
Sugerencias: consultas relacionadas sin URL, útiles para ampliar la búsqueda

all - Todos los idiomas

English 🌐

en - Global English
en-AU - English (Australia) 🇦🇺
en-CA - English (Canada) 🇨🇦
en-GB - English (United Kingdom) 🇬🇧
en-IE - English (Ireland) 🇮🇪
en-IN - English (India) 🇮🇳
en-NZ - English (New Zealand) 🇳🇿
en-PH - English (Philippines) 🇵🇭
en-PK - English (Pakistan) 🇵🇰
en-SG - English (Singapore) 🇸🇬
en-US - English (United States) 🇺🇸
en-ZA - English (South Africa) 🇿🇦

Chinese 🌐

zh - Global Chinese
zh-CN - Chinese (China) 🇨🇳
zh-HK - Chinese (Hong Kong) 🇭🇰
zh-TW - Chinese (Taiwan) 🇹🇼

Spanish 🌐

es - Global Spanish
es-AR - Spanish (Argentina) 🇦🇷
es-CL - Spanish (Chile) 🇨🇱
es-CO - Spanish (Colombia) 🇨🇴
es-ES - Spanish (Spain) 🇪🇸
es-MX - Spanish (Mexico) 🇲🇽
es-PE - Spanish (Peru) 🇵🇪

French 🌐

fr - Global French
fr-BE - French (Belgium) 🇧🇪
fr-CA - French (Canada) 🇨🇦
fr-CH - French (Switzerland) 🇨🇭
fr-FR - French (France) 🇫🇷

German 🌐

de - Global German
de-AT - German (Austria) 🇦🇹
de-BE - German (Belgium) 🇧🇪
de-CH - German (Switzerland) 🇨🇭
de-DE - German (Germany) 🇩🇪

Portuguese 🌐

pt - Global Portuguese
pt-BR - Portuguese (Brazil) 🇧🇷
pt-PT - Portuguese (Portugal) 🇵🇹

Italian 🌐

it - Global Italian
it-CH - Italian (Switzerland) 🇨🇭
it-IT - Italian (Italy) 🇮🇹

Japanese 🌐

ja - Global Japanese
ja-JP - Japanese (Japan) 🇯🇵

Korean 🌐

ko - Global Korean
ko-KR - Korean (South Korea) 🇰🇷

Russian 🌐

ru - Global Russian
ru-RU - Russian (Russia) 🇷🇺

Idiomas europeos

Dutch 🌐

nl - Global Dutch
nl-BE - Dutch (Belgium) 🇧🇪
nl-NL - Dutch (Netherlands) 🇳🇱

Polish 🌐

pl - Global Polish
pl-PL - Polish (Poland) 🇵🇱

Czech 🌐

cs - Global Czech
cs-CZ - Czech (Czech Republic) 🇨🇿

Hungarian 🌐

hu - Global Hungarian
hu-HU - Hungarian (Hungary) 🇭🇺

Romanian 🌐

ro - Global Romanian
ro-RO - Romanian (Romania) 🇷🇴

Greek 🌐

el - Global Greek
el-GR - Greek (Greece) 🇬🇷

Bulgarian 🌐

bg - Global Bulgarian
bg-BG - Bulgarian (Bulgaria) 🇧🇬

Croatian 🌐

hr - Global Croatian

Slovak 🌐

sk - Global Slovak

Slovenian 🌐

sl - Global Slovenian

Estonian 🌐

et - Global Estonian
et-EE - Estonian (Estonia) 🇪🇪

Latvian 🌐

lv - Global Latvian

Lithuanian 🌐

lt - Global Lithuanian

Finnish 🌐

fi - Global Finnish
fi-FI - Finnish (Finland) 🇫🇮

Swedish 🌐

sv - Global Swedish
sv-SE - Swedish (Sweden) 🇸🇪

Norwegian 🌐

nb - Norwegian Bokmål
nb-NO - Norwegian Bokmål (Norway) 🇳🇴

Danish 🌐

da - Global Danish
da-DK - Danish (Denmark) 🇩🇰

Icelandic 🌐

is - Global Icelandic

Otros idiomas

Arabic 🌐

ar - Global Arabic
ar-SA - Arabic (Saudi Arabia) 🇸🇦

Hebrew 🇮🇱

he - Hebrew

Turkish 🌐

tr - Global Turkish
tr-TR - Turkish (Turkey) 🇹🇷

Persian 🌐

fa - Persian

Hindi 🌐

hi - Hindi

Urdu 🌐

ur - Urdu

Thai 🌐

th - Global Thai
th-TH - Thai (Thailand) 🇹🇭

Vietnamese 🌐

vi - Global Vietnamese
vi-VN - Vietnamese (Vietnam) 🇻🇳

Indonesian 🌐

id - Global Indonesian
id-ID - Indonesian (Indonesia) 🇮🇩

Indian Languages

kn - Kannada 🌐
ml - Malayalam 🌐
mr - Marathi 🌐
ta - Tamil 🌐
te - Telugu 🌐

Other European Languages

af - Afrikaans 🌐
be - Belarusian 🌐
ca - Catalan 🌐
cy - Welsh 🌐
eu - Basque 🌐
ga - Irish 🌐
gd - Scottish Gaelic 🌐
gl - Galician 🌐
sq - Albanian 🌐
uk - Ukrainian 🌐

Notas de uso

Códigos globales (p. ej. en, zh, es) dan resultados más amplios sin restricción de país
Códigos por país (p. ej. en-US, zh-CN, es-MX) devuelven resultados localizados
La API elige el dominio de Google y el idioma según el locale
Para mejores resultados, alinea lang con el idioma de la consulta

Tabla de contenidos