Map

Introducción

La API Map de AnyCrawl extrae URLs de un sitio combinando varias fuentes de descubrimiento: análisis de sitemap, resultados de motor de búsqueda y extracción de enlaces HTML. Ofrece un descubrimiento de URLs completo para mapas del sitio, indexación de contenido y planificación de rastreos.

Características clave: la API devuelve datos de inmediato y de forma síncrona — sin sondeo ni webhooks. Combina tres fuentes de URL para máxima cobertura.

Características principales

• Descubrimiento multisource: combina análisis de sitemap, resultados de búsqueda y extracción de enlaces de página
• Soporte de sitemap: analiza robots.txt y sitemap.xml (incluidos índices de sitemap y gzip)
• Integración con búsqueda: usa automáticamente motores de búsqueda con el operador site: para descubrir URLs
• Extracción de enlaces: extrae todos los enlaces <a href> de la página objetivo
• Filtrado por dominio: filtra por dominio exacto o incluye subdominios
• Respuesta inmediata: API síncrona — obtén resultados al instante sin sondeo

Endpoint de la API

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

Ejemplos de uso

cURL

Mapeo básico de URL

curl -X POST "https://api.anycrawl.dev/v1/map" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

Incluir subdominios

curl -X POST "https://api.anycrawl.dev/v1/map" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "include_subdomains": true,
    "limit": 1000
  }'

Omitir el análisis del sitemap

Para resultados más rápidos cuando solo necesitas enlaces de página y resultados de búsqueda:

curl -X POST "https://api.anycrawl.dev/v1/map" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "ignore_sitemap": true
  }'

Parámetros de la petición

Comportamiento de caché

• max_age controla las lecturas de Map Cache. 0 fuerza actualización.
• use_index=false desactiva la fuente del índice de Page Cache (requiere que Page Cache esté activado para tener efecto).
• /v1/map no devuelve fromCache en la respuesta (el uso de caché es interno).

Fuentes de descubrimiento de URL

La API Map combina tres fuentes para descubrir URLs:

1. Análisis de sitemap

• Analiza robots.txt para localizar sitemaps
• Prueba rutas habituales: /sitemap.xml, /sitemap.xml.gz
• Admite índices de sitemap (sitemaps que contienen otros sitemaps)
• Admite sitemaps comprimidos con gzip

2. Resultados de motor de búsqueda

• Usa automáticamente el operador site:dominio.com para descubrir páginas indexadas
• Proporciona metadatos de título y descripción para las URLs descubiertas

3. Extracción de enlaces de página

• Extrae todos los enlaces <a href> del HTML de la página objetivo
• Captura el texto del enlace como metadato de título
• Captura el atributo title y aria-label como descripción

Fuentes de metadatos

Formato de respuesta

Respuesta correcta (HTTP 200)

{
    "success": true,
    "data": [
        {
            "url": "https://example.com/page1",
            "title": "Page Title",
            "description": "Page description from search results"
        },
        {
            "url": "https://example.com/page2",
            "title": "Another Page"
        },
        {
            "url": "https://example.com/page3"
        }
    ]
}

Respuestas de error

400 - Error de validación

{
    "success": false,
    "error": "Validation error",
    "message": "Invalid url",
    "details": {
        "issues": [
            {
                "field": "url",
                "message": "Invalid url",
                "code": "invalid_string"
            }
        ]
    }
}

402 - Créditos insuficientes

{
    "success": false,
    "error": "Insufficient credits",
    "message": "Estimated credits required (1) exceeds available credits (0).",
    "details": {
        "estimated_total": 1,
        "available_credits": 0
    }
}

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
}

500 - Error interno del servidor

{
    "success": false,
    "error": "Internal server error",
    "message": "Error message details"
}

Buenas prácticas

Casos de uso

1. Planificación de rastreo: usa Map para descubrir todas las URLs antes de un rastreo completo
2. Indexación de contenido: construye un índice completo de las páginas de un sitio
3. Auditoría del sitio: encuentra todas las páginas para auditorías SEO o de accesibilidad
4. Análisis de enlaces: analiza la estructura de enlaces internos

Consejos de rendimiento

• Usa ignore_sitemap: true para resultados más rápidos cuando el sitemap no haga falta
• Ajusta limit para no procesar URLs innecesarias
• Usa include_subdomains: false (predeterminado) salvo que necesites descubrimiento entre subdominios

Combinar con Crawl

Map es ideal para planificar operaciones de rastreo:

// Paso 1: Descubrir URLs con Map
const mapResponse = await fetch("/v1/map", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://docs.example.com",
        limit: 100,
    }),
});
const { data: urls } = await mapResponse.json();

// Paso 2: Usar las URLs descubiertas para planificar el rastreo
const crawlResponse = await fetch("/v1/crawl", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://docs.example.com",
        include_paths: urls.map((u) => new URL(u.url).pathname),
        limit: 100,
    }),
});

Créditos

Total: 1 crédito por petición.

Preguntas frecuentes

P: ¿En qué se diferencia Map de Crawl?

R: Map descubre URLs sin obtener el contenido de las páginas: es rápido y ligero. Crawl obtiene y procesa el contenido real de cada página. Usa Map para descubrimiento y planificación; Crawl para extracción de contenido.

P: ¿Por qué faltan algunas URLs en los resultados?

R: Posibles causas:

• Las URLs están en otro dominio/subdominio (usa include_subdomains: true)
• El sitio no tiene sitemap
• Las URLs se generan dinámicamente con JavaScript
• Las URLs superan el parámetro limit

P: ¿Cómo funciona el descubrimiento por motor de búsqueda?

R: La API Map consulta automáticamente motores de búsqueda con site:dominio.com para descubrir páginas indexadas. Ayuda a encontrar URLs que pueden no estar en el sitemap ni enlazadas desde la página principal.

P: ¿Map sigue redirecciones?

R: Map extrae las URLs tal como aparecen en sitemaps y enlaces de página. No sigue redirecciones para descubrir URLs adicionales.

P: ¿Hay límite de velocidad?

R: En el servicio alojado, 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.