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 | | template_id | string | - | ID de plantilla scrape para seguimientos (como /v1/scrape). Se omiten URL fuera de allowedDomains. | | variables | object | - | Variables de esa plantilla scrape (con template_id). |

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."
}

403 - Función no disponible en tu plan

Solo en el servicio alojado. Se devuelve cuando scrape_options solicita una función que tu plan no incluye; actualmente proxy: "stealth", que requiere el plan Hobby o superior.

{
    "success": false,
    "error": "stealth_proxy_not_allowed",
    "message": "Stealth proxy is not available on your plan. Upgrade to Hobby or above to use proxy: stealth."
}

429 - Límite de concurrencia alcanzado

Solo en el servicio alojado. Se devuelve cuando la API key ya tiene en ejecución tantas solicitudes como permite su plan. No se inició nada ni se cobraron créditos: reintenta cuando termine alguna de tus solicitudes en curso.

{
    "success": false,
    "error": "Concurrency limit reached",
    "message": "Your plan allows 2 concurrent requests. Retry when an in-flight request finishes, or upgrade your plan.",
    "limit": 2
}

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 procesa en paralelo las búsquedas concurrentes.

Servicio alojado (anycrawl.dev): cada API key puede ejecutar un número limitado de solicitudes a la vez, según tu plan. Una solicitud que supere ese límite se rechaza de inmediato con 429; reinténtala cuando termine alguna de tus solicitudes en curso.
Autoalojado: sin límite de concurrencia por defecto.

Mantén el número de solicitudes en paralelo dentro del límite de tu plan:

// 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

Concurrencia: en el servicio alojado, el número de solicitudes que una API key puede ejecutar a la vez depende de tu plan; las que lo superan devuelven 429. Las instalaciones autoalojadas no tienen límite por defecto.
Revisa el consumo en cabeceras y BillingChargeDetails.

Modelo de créditos (búsqueda + scrapes de seguimiento opcionales)

search_pages — equivale a pages (a menudo 1 crédito por página por defecto).
template_per_call — con template_id de nivel superior (plantilla search): pricing.perCall una vez por solicitud.
Con scrape_options y seguimientos exitosos:
- search_result_scrape — completed_scrape_count × unidad de motor (calculateScrapeCredits).
- search_result_scrape_template — con scrape_options.template_id: pricing.perCall de la plantilla scrape por éxito. Solo plantillas search: metadata.charge_scrape_template_credits: false desactiva esta línea (la línea de motor sigue aplicando).

Especificación completa: repositorio docs/api/search-scrape-credits-and-templates.md.

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

P: ¿Hay límite de velocidad en búsquedas concurrentes?

R: En el servicio alojado, sí: cada API key puede ejecutar un número limitado de solicitudes a la vez, según tu plan. Las solicitudes que superan el límite devuelven 429 Concurrency limit reached de inmediato; reintenta cuando termine una solicitud en curso. Las instalaciones autoalojadas no tienen límite de concurrencia por defecto.

Idiomas y regiones

La API Search admite varios idiomas y regiones mediante lang. Locales admitidos:

Idiomas principales

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