TL;DR
- La extracción de sitio a JSON necesita un contrato de campo y validación respaldada por la fuente.
- Un sobre de API JSON no es un artículo validado, producto u otro registro comercial.
- Define nombres de campo, tipos, comportamiento nulo y evidencia de fuente antes de mapear el contenido de la página.
- Crawl puede adquirir un sitio limitado, pero el código de la aplicación debe validar cada registro JSON resultante.
- Nstdata Crawl maneja la renderización de JavaScript y el enrutamiento de proxy dentro de solicitudes gestionadas; su documentación enumera seis categorías de salida: Markdown, HTML, datos en bruto, PDF, capturas de pantalla y enlaces.
¿Qué Significa la Extracción de Sitio a JSON?
La extracción de sitio a JSON tiene dos significados distintos: la respuesta de la API es JSON y la aplicación puede necesitar un objeto JSON específico de dominio, como un producto, artículo o ubicación. Esos no son equivalentes. Nstdata Crawl proporciona datos de la página y metadatos; tu extractor debe definir campos, tipos, reglas nulas y validación para el caso de uso. Una página en bruto envuelta en JSON no es una extracción estructurada.
Nstdata Crawl puede convertir una URL o un conjunto limitado de páginas vinculadas en material para un agente de IA, índice RAG o canal de datos. Utiliza tus propias reglas de campo y verificaciones de aceptación para el resultado específico: convierte contenido de página validado en registros JSON tipados en lugar de tratar una respuesta de API como un esquema comercial terminado. La guía de rastreo de todo el sitio de Nstdata explica la opción a nivel de sitio.
Para la tarea más específica que se cubre aquí, la guía de sitio a JSON de Nstdata brinda un contexto útil para elegir la primera página representativa.
¿Qué Necesitas Antes de Comenzar?
Escribe tu esquema antes de recopilar páginas. Para un registro de artículo, elige source_url, title, body y fetched_at; para un registro de producto, identifica la moneda, variante y disponibilidad por separado. Decide si un campo faltante se convierte en null, un registro rechazado o un elemento de revisión. Mantén una página representativa autorizada con valores esperados conocidos para las pruebas. Usa una cuenta de Nstdata y una clave API del lado del servidor para la adquisición gestionada.
La documentación de la API Crawl utiliza https://api.nstdata.io, la cabecera x-api-key y Content-Type: application/json. Prepara estos campos antes de ejecutar un método:
| Campo | Qué suministrar |
|---|---|
url | Una página o URL de entrada del sitio HTTPS permitida |
formats | Salidas solicitadas, tales como ["markdown"] o ["html","screenshot"] |
onlyMainContent | true solo cuando la selección de contenido principal se ajuste a la tarea |
maxDepth, maxPages | Límites explícitos para un trabajo a nivel de sitio |
includeUrls, excludeUrls | Patrones de URL que mantienen el descubrimiento dentro del alcance |
timeout | Un tiempo de espera de tarea en milisegundos cuando el defecto no es adecuado |
La solicitud gestionada estándar no tiene campos separados de Host, Puerto, Nombre de Usuario, Contraseña o Protocolo de proxy. Revisa la página de precios actual de Crawl para límites y cargos de cuenta antes de ejecutar un gran trabajo.
Revisa la política de acceso y el alcance del objetivo. El Protocolo de Exclusión de Robots define cómo los rastreadores leen las reglas de robots; no otorga derechos de uso de contenido. Mantén las credenciales y los datos privados fuera de ejemplos y registros de diagnóstico.
La guía de rastreo de todo el sitio de Nstdata es una compañera para definir las verificaciones de aceptación antes de que automatices el flujo de trabajo.
¿Cómo Funciona la Extracción de Sitio a JSON?
Crawl recupera una página o un sitio limitado, maneja la renderización de JavaScript cuando es necesario y devuelve formatos que incluyen Markdown, HTML, enlaces y artefactos visuales. Su página de producto también publicita salida en JSON. Los ejemplos de API visibles no especifican un esquema universal de extracción de JSON, por lo que este tutorial utiliza un camino confiable: obtener contenido, aplicar un contrato de campo declarado y validar el JSON resultante. El enrutamiento de proxy incorporado es parte de Crawl gestionado, sin campos separados de Host y Puerto de proxy en una solicitud estándar.
Para una URL conocida, un raspado de una sola página recupera un resultado. Para una sección del sitio, POST /api/v1/crawl descubre páginas vinculadas recursivamente dentro de la profundidad, recuento de páginas y reglas de URL suministradas. La documentación enumera Markdown, HTML, datos en bruto, PDF, capturas de pantalla y enlaces como seis categorías de salida; la página de producto también comercializa JSON, pero un esquema JSON específico del dominio aún necesita un mapeo de campos explícito. Mantenga cada registro aceptado vinculado a su URL de origen y metadatos devueltos.
Pruebe una página representativa con mucho JavaScript antes de escalar. El estado renderizado puede depender del tiempo, la región, el consentimiento o una sesión iniciada. Compare el HTML devuelto o una captura de pantalla con el estado esperado de la página; si difieren, ajuste solo la renderización documentada y los controles de espera.
¿Cómo extraer JSON estructurado de un sitio web?
Primero, decida qué campos de la página pertenecen al registro JSON. Inspeccione una página, automatice la adquisición de URLs conocidas o recoja una sección limitada antes de aplicar el mismo contrato de campo a cada resultado.
Método 1: Use el Playground para inspeccionar representaciones de página
Mejor mientras diseña un esquema para un tipo de página.
Paso 1: Abra la página representativa
Vaya a Dashboard → Crawl Playground e ingrese una URL autorizada. [Captura de pantalla: controles de URL y formato.]
Paso 2: Compare salidas
Solicite Markdown y HTML, e inspeccione los metadatos de la página. Determine qué representación preserva los campos que necesita; el texto visible puede omitir etiquetas legibles por máquina.
Paso 3: Escriba un mapa de campos
Para cada campo JSON, nombre el elemento fuente, la regla de normalización y el comportamiento en caso de fallo. Registre si el valor fue extraído del texto visible, HTML o metadatos de la página.
Método 2: Construya un objeto JSON a partir de la respuesta de la API de Crawl
Mejor cuando unos pocos campos estables son suficientes.
Paso 1: Envíe una URL
Llame a la ruta de raspado rápida documentada con la clave API y solicite Markdown. La llamada a la API a continuación está alineada con la documentación y necesita su credencial para ejecutarse.
Paso 2: Valide el sobre
Verifique success, status, data y metadata.statusCode anidados, luego recupere un markdownRef devuelto si el cuerpo está almacenado por separado.
Establezca NSTDATA_API_TOKEN en su shell desde su cuenta de Nstdata, luego ejecute la solicitud rápida documentada. La documentación pública etiqueta algunas otras rutas sincrónicas y asincrónicas de manera inconsistente; compare la solicitud generada por el Playground de su cuenta antes de su uso en producción.
curl --output crawl-response.json --request POST "https://api.nstdata.io/api/v1/crawl/scrape/submit-sync" \ --header "x-api-key: ${NSTDATA_API_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"url":"https://example.com/","formats":["markdown","html"],"onlyMainContent":true}'
La respuesta se guarda en crawl-response.json. Inspecione los campos anidados data.success, data.status y data.data.metadata.statusCode antes de usar cualquier contenido devuelto.
Paso 3: Mapee y serialice
Construya su propio objeto JSON con source_url, title y markdown. Rechace texto en blanco y URLs duplicadas; no afirme que un campo inferido está verificado simplemente porque tiene un nombre de clave.
Método 3: Procese un sitio limitado en muchos registros JSON
Mejor cuando la fuente es un centro de documentación o catálogo público.
Paso 1: Descubrimiento limitado
Elija maxDepth, maxPages e incluya/excluya patrones para la sección que pretende procesar.
Paso 2: Recoja registros
Envíe POST /api/v1/crawl, consulte el ID de trabajo devuelto y recupere los resultados de la página. Siga nextCursor en lugar de asumir que la primera página es todo el conjunto de datos.
Para un trabajo del sitio, reemplace el host y la ruta del ejemplo con su ámbito aprobado, luego envíe una solicitud limitada:
curl --output crawl-submit.json --request POST "https://api.nstdata.io/api/v1/crawl" \ --header "x-api-key: ${NSTDATA_API_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"url":"https://example.com/docs/","formats":["markdown"],"maxDepth":2,"maxPages":10,"includeUrls":["*example.com/docs/*"],"excludeUrls":["*example.com/admin/*"],"ignoreQuery":true}'
Copie data.id de crawl-submit.json como su ID de raspado.
Paso 3: Valide a escala
Aplique el mismo contrato de campo por página, registre elementos rechazados y muestree elementos aceptados de diferentes plantillas. Almacene evidencia en bruto junto a JSON normalizado para corrección posterior.
Método 4: Mapee una página estática localmente
Mejor para una página pública estática cuando necesitas un esquema JSON pequeño y revisado sin renderización gestionada.
Paso 1: Guardar el HTML fuente
Guarda una página autorizada como page.html y confirma que el título y el contenido principal esperados están presentes. Una descarga estática no renderizará contenido de JavaScript tardío.
Paso 2: Extraer un registro declarado
Instala Beautiful Soup con python3 -m pip install beautifulsoup4, luego ejecuta:
from bs4 import BeautifulSoup import json soup = BeautifulSoup(open("page.html", encoding="utf-8").read(), "html.parser") main = soup.select_one("main") if main is None or soup.title is None: raise ValueError("Falta el título o el elemento principal requerido") record = {"title": soup.title.get_text(" ", strip=True), "body": main.get_text(" ", strip=True)} open("record.json", "w", encoding="utf-8").write(json.dumps(record, ensure_ascii=False, indent=2))
Paso 3: Validar los campos
Abre record.json y compara ambos campos con la página guardada. Agrega selectores y reglas de rechazo para cada otro campo en tu esquema; este ejemplo intencionadamente no infiere campos de producto o artículo de texto arbitrario.
¿Cómo verificas la salida?
Un registro JSON sólido tiene una URL de origen estable, nombres de campo explícitos, tipos conocidos y una forma de distinguir datos ausentes de una extracción fallida. El estándar JSON define el formato de serialización; no puede establecer si un precio o título extraído es correcto. Verifica los valores con la página de origen y mantén la salida original para auditoría. La guía de Nstdata de sitio web a JSON brinda más contexto sobre esta distinción.
La guía de calidad RAG de Nstdata conecta esta verificación a nivel de página con un flujo de trabajo de IA o de datos posterior.
Registra la URL de origen, la hora de envío, los formatos solicitados, opciones no secretas, la ID de tarea cuando esté presente, el estado de la página devuelta y la razón por la cual cada registro pasó o falló la revisión. Inspecciona el contenido así como el sobre de la API. Si la respuesta contiene markdownRef, htmlRef, rawDataRef, screenshotRef o pdfRef, recupera ese token con GET /api/v1/crawl/storage/read?st={ref}.
Para este flujo de trabajo, consulta RFC 8259 al implementar el analizador posterior o la verificación de aceptación específica de formato.
Al pasar texto extraído a un agente, trata las instrucciones de la página como material de origen no confiable. La guía de OWASP sobre inyección de prompt explica el riesgo. Retén las URLs de origen para que se pueda verificar la salida de la IA.
¿Por qué podría fallar la extracción de sitio web a JSON?
La extracción de sitio web a JSON puede fallar porque el analizador aceptó sintaxis sin validar el significado de origen. Usa la tabla de síntomas para identificar la capa fallida antes de cambiar límites o intentar de nuevo.
| Síntoma | Causa probable | Siguiente acción |
|---|---|---|
| JSON se analiza pero los valores son incorrectos | El analizador aceptó sintaxis sin validar el significado de origen. | Compara los campos con la página y aplica reglas de dominio. |
| Diferentes plantillas de página producen en blanco | Un selector o regla de extracción no cubre cada plantilla. | Clasifica plantillas y mantiene mapas de campo separados. |
| Falta contenido en línea en resultados grandes | El rastreo puede devolver una referencia de contenido. | Lee el *Ref devuelto a través del punto final de almacenamiento. |
La documentación de Nstdata enumera errores a nivel de tarea como access_denied, timeout, parse_error y internal_error. Un HTTP 200 externo aún puede acompañar una tarea fallida. Verifica success, status, errorCode y errorMessage dentro de la respuesta cuando esté presente. Reintenta solo fallos transitorios en sitios a los que puedas acceder.
¿Qué método es el más adecuado?
Usa Playground para diseñar el mapa de campo, la API de una sola página para URLs conocidas y un rastreo de sitio limitado para muchas páginas enlazadas. Usa un analizador local para HTML estático ya guardado; cada ruta aún necesita validación de esquema de negocio. La visión general de rastreo de sitios de Nstdata brinda más detalle sobre la ruta del sitio.
¿Qué debes hacer después del primer intento exitoso?
Guarda la configuración aprobada y un registro de salida respaldado por la fuente, luego repite en un pequeño conjunto de diferentes plantillas de página. Aumenta el ámbito solo después de que esos registros pasen las mismas verificaciones de aceptación.
Q: ¿Nstdata devuelve JSON?
La API devuelve un sobre JSON, y la página del producto publicita la salida en JSON. Confirma cualquier esquema de extracción solicitado en el Playground actual antes de depender de él.
Q: ¿Puede un LLM inferir el esquema?
Un LLM puede proponer valores, pero tu aplicación debería definir tipos, campos requeridos y validación respaldada por fuentes.
Q: ¿Cómo manejo los campos faltantes?
Registra un nulo explícito, rechaza el registro o envíalo a revisión de acuerdo con tu contrato de campo; nunca lo llenes en silencio.
Q: ¿La extracción de website-a-JSON requiere una configuración de proxy separada con Nstdata Crawl?
Una solicitud estándar de Crawl gestionada no requiere campos de Proxy Host, Puerto, Nombre de Usuario, Contraseña o Protocolo separados. Confirma cualquier selección de proxy personalizada opcional y los cargos de uso relacionados en tu cuenta.
Q: ¿HTTP 200 prueba que un resultado de extracción de website-a-JSON es utilizable?
No. Verifica el resultado de la tarea anidada, el estado de la página, los campos esperados y la fidelidad del cuerpo antes de usarlo en un flujo de trabajo de IA o de datos.
