map_site
Enumere las páginas de un sitio empezando por la vía más económica: si el origen sirve un sitemap.xml se lee directamente, y solo cuando no hay uno utilizable la herramienta recurre al rastreo. La respuesta indica qué camino se tomó.
Casos de uso
Obtener una lista de URL antes de hacer scraping
Enumere primero y pase después la lista a batch_scrape: mucho más económico que rastrear con la extracción activada.
Comprobar qué publica un sitio a los buscadores
El modo sitemap informa exactamente de lo que el sitio anuncia, que a menudo no coincide con lo que es alcanzable siguiendo enlaces.
Encontrar páginas huérfanas o sin enlaces
Compare la lista del sitemap con una ejecución de crawl_deep: las páginas del sitemap que el rastreo nunca alcanzó no tienen enlaces entrantes.
Dimensionar un sitio antes de comprometer credits
total_pages le indica el tamaño del trabajo antes de empezar a pagar por página por la extracción.
Endpoint
/api/v1/tools/map_siteParameters
max_depth e include_external solo se aplican al rastreo alternativo. Cuando se encuentra un sitemap.xml utilizable se ignoran, porque no se realiza ningún rastreo.| Name | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Required | - | Cualquier URL del sitio. Su origen se usa para buscar `/sitemap.xml`, y es el punto de partida si se ejecuta el rastreo alternativo. Example: https://example.com |
max_depth | number | Optional | 2 | Profundidad de rastreo para la alternativa, 1-5. Se ignora cuando se encuentra un sitemap. Example: 2 |
include_external | boolean | Optional | false | Incluye enlaces externos en las listas de enlaces por página. Solo en modo rastreo: las páginas externas se cuentan pero nunca se visitan. Example: false |
timeout | number | Optional | 15000 | Presupuesto total en milisegundos, 1000-30000. En la práctica se limita cerca de 18000 para ajustarse al límite de ejecución serverless. Example: 15000 |
respect_robots | boolean | Optional | true | Respeta el robots.txt del sitio de destino. Con el valor `true`, una ruta que robots.txt no permita a `CrawlForge` se rechaza con un 403 antes de descargar nada y no se cobran credits. Póngalo en `false` solo para destinos con los que tenga su propio acuerdo: la respuesta incluye entonces una entrada `warnings` y la anulación queda registrada en su API key. Example: true |
Dos formas de mapear un sitio
source en la respuesta indica cuál se ejecutó: ambos modos devuelven las mismas claves, pero las rellenan de forma distinta.
{origin}/sitemap.xml, siguiendo hasta 3 sitemaps hijos y con un límite de 500 URL. Rápido y completo. max_depth_reached y sitemap vuelven como null porque no se rastreó nada.sitemap se rellena con los enlaces encontrados en cada página.sitemap no es un sitemap. En modo rastreo contiene un mapa de cada página rastreada con los enlaces encontrados en ella; en modo sitemap es null. Las URL enumeradas están siempre en pages./sitemap.xml con estado 200, se detecta y se descarta, de modo que se pasa al modo rastreo en lugar de informar de una única página falsa.Ejemplos de solicitud
curl -X POST https://crawlforge.dev/api/v1/tools/map_site \
-H "X-API-Key: cf_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"max_depth": 2,
"include_external": false,
"timeout": 15000
}'Ejemplo de respuesta
{ "success": true, "data": { "base_url": "https://example.com", "source": "sitemap", "total_pages": 128, "internal_links": 128, "external_links": 0, "pages": [ "https://example.com/", "https://example.com/pricing", "https://example.com/docs" ], "max_depth_reached": null, "sitemap": null }, "credits_used": 2, "credits_remaining": 998, "processing_time": 1240}data.sourceO bien "sitemap" o bien "crawl": qué estrategia produjo este resultado.data.total_pagesNúmero de URL en el arreglo pages.data.internal_linksEnlaces internos distintos encontrados. En modo sitemap coincide con el número de páginas.data.external_linksEnlaces externos distintos. Siempre 0 en modo sitemap, ya que no se lee el cuerpo de ninguna página.data.pagesLas URL enumeradas: esta es la lista que le interesa.data.max_depth_reachedNivel de rastreo más profundo alcanzado, o null en modo sitemap, donde no se rastreó nada.data.sitemapSolo en modo rastreo: cada página rastreada asociada a los enlaces encontrados en ella. Null en modo sitemap.Manejo de errores
No se pudo mapear nada (422 NO_PAGES_MAPPED)
No había un sitemap utilizable y la URL inicial no devolvió una página HTML que rastrear. Es habitual cuando la URL apunta a un PDF, una imagen o un endpoint de API. No se cobran credits.
El destino devolvió un error (502 TARGET_HTTP_ERROR)
El sitio respondió con un estado distinto de 2xx. Los sitios con protección antibots suelen acabar aquí: pruebe con stealth_mode.
URL inválida (400 VALIDATION_ERROR)
La url estaba mal formada, usaba un esquema distinto de http/https o resolvía a una dirección privada. max_depth debe estar entre 1 y 5, y timeout entre 1000 y 30000.
Destino demasiado lento (504 FETCH_TIMEOUT)
El sitio no respondió dentro del presupuesto. Aumente timeout, aunque está limitado cerca de 18000 ms.
Bloqueado por robots.txt (403 Forbidden)
El robots.txt del sitio de destino no permite esta ruta a CrawlForge. Establezca respect_robots: false para anularlo si tiene su propio acuerdo con el destino: la anulación queda registrada en su API key. La anulación no alcanza a un host incluido en la lista de exclusión permanente de CrawlForge, que se rechaza sea cual sea el valor de respect_robots. Solo la URL de entrada devuelve un 403: una URL descubierta durante el recorrido que robots.txt no permita se deja fuera del mapa y se indica en warnings.
crawl_deep y compare las dos listas.Costo en credits
Desglose de costos:
Cualquier mapeo, en modo sitemap o rastreo: 2 credits
Recomendaciones por plan:
Plan Free: 1.000 credits de prueba únicos = 500 mapeos de sitio
Plan Hobby: 5.000 credits/mes = 2.500 mapeos de sitio ($19/mes)
Plan Professional: 50.000 credits/mes = 25.000 mapeos de sitio ($99/mes)
Mapear es la forma más económica de dimensionar un trabajo: enumere primero y gaste credits por página solo en las URL que realmente quiera.