ScraperFlyAPI de datos web lista para IA

docs

Documentación para tu primera solicitud de ScraperFly

La API es intencionalmente directa: envía una URL, elige los controles que necesitas y maneja el HTML devuelto o la respuesta extraída en tu aplicación.

Documentación

Documentación de ScraperFly

Inicio rápido: autentíquese con su clave API, obtenga HTML, habilite la renderización de JS, elija formatos de salida y use proxies premium. ScraperFly es intencionalmente directo: envíe una URL, elija los controles que necesita y maneje el HTML devuelto, texto limpio, Markdown, JSON, captura de pantalla o PDF en su aplicación.

Punto final

/api/v1

Utilice parámetros de consulta GET o POST JSON. Ambas formas de solicitud devuelven el mismo resultado.

Autenticación

apikey encabezado

Mantenga las claves del lado del servidor y gírelas desde el panel de control siempre que sea necesario.

Créditos

1 a 25 créditos

Los costos dependen del enrutamiento premium, la renderización del navegador y la salida de archivos visuales.

Costos de Créditos & Solicitudes Fallidas

Los créditos dependen de la configuración de la solicitud (proxies premium, renderización de JS, etc.) y del resultado final. En la práctica, cada solicitud cuesta entre 1 y 25 créditos.

PremiumRenderizarCosto en créditos
falsefalse1
falsetrue5
truefalse10
truetrue25
Consejos para controlar costos
  • Comience con premium=false, render=false para objetivos fáciles.
  • Habilite render=true solo para páginas con mucho JS (React/Vue/Next.js).
  • Utilice country cuando el objetivo cambie por ubicación.
  • Si se encuentra con páginas de desafío, intente premium=true + render=true.

Uso Básico

Obtenga el HTML de una página objetivo. Para un uso básico, solo necesita su apikey y una url. Esto generalmente utiliza proxies estándar y cuesta 1 crédito. La respuesta es el HTML sin procesar de la página. Si necesita datos estructurados, analice el HTML en su lado (Cheerio/BeautifulSoup/etc.).

8 ejemplos
curl "https://scraperfly.com/api/v1?url=https://example.com" \
  -H "apikey: YOUR_API_KEY_HERE"
// Node 18+ tiene fetch incorporado
const res = await fetch("https://scraperfly.com/api/v1?url=https://example.com", {
  headers: { apikey: "YOUR_API_KEY_HERE" }
});
const html = await res.text();
console.log(html);
import requests

res = requests.get(
  "https://scraperfly.com/api/v1",
  params={"url": "https://example.com"},
  headers={"apikey": "YOUR_API_KEY_HERE"}
)

print(res.text)
<?php
$endpoint = "https://scraperfly.com/api/v1";
$url = "https://example.com";
$ch = curl_init($endpoint . "?url=" . urlencode($url));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["apikey: YOUR_API_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$html = curl_exec($ch);
curl_close($ch);
echo $html;
package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
)

func main() {
  endpoint := "https://scraperfly.com/api/v1?url=" + url.QueryEscape("https://example.com")
  req, _ := http.NewRequest("GET", endpoint, nil)
  req.Header.Set("apikey", "YOUR_API_KEY_HERE")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}
using System.Net.Http;

var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");

var endpoint = "https://scraperfly.com/api/v1?url=https://example.com";
var html = await http.GetStringAsync(endpoint);

Console.WriteLine(html);
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://scraperfly.com/api/v1?url=https://example.com"))
  .header("apikey", "YOUR_API_KEY_HERE")
  .GET()
  .build();

HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"

endpoint = URI("https://scraperfly.com/api/v1?url=https://example.com")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"

res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
  http.request(req)
end

puts res.body

Parámetros de Solicitud

Utilice el punto final canónico GET /api/v1 con parámetros de consulta, o POST /api/v1 con los mismos campos en un cuerpo JSON. Comience con url + format, luego agregue opciones de proxy, renderizar, viewport o archivo solo cuando el objetivo las necesite.

Solicitud principal

ParámetroTipoDescripción
urlrequeridoURL del sitio web objetivo que desea raspar, por ejemplo, url=https://example.com.
premiumopcional, booleanoUtiliza grupos de proxies de mayor calidad para objetivos más difíciles. Cuesta más créditos.
countryopcionalPaís del proxy solicitado, por ejemplo US. Los registros de uso almacenan el país y la ciudad del proxy real.
renderopcional, booleanoRenderización de navegador sin cabeza para páginas que requieren JavaScript. Se habilita automáticamente para screenshot y pdf.
keep_headersopcional, booleanoTransmita sus propios encabezados (cookies, user-agent, accept-language, etc.).
formatopcionalFormato de salida: html, text, markdown, json, screenshot, o pdf.

Formatos de salida

formatoRespuestaCuándo usar
htmlHTMLPor defecto. Úselo cuando desee la fuente sin procesar o HTML renderizado para su propio analizador.
texttexto planoÚselo cuando necesite texto limpio y legible sin ruido de navegación/disposición.
markdownMarkdownÚselo para indicaciones de LLM, RAG, documentos, resúmenes e indexación.
jsonJSONÚselo para metadatos, título, encabezados, enlaces, texto limpio y Markdown en una respuesta.
screenshotarchivo de imagenSiempre utiliza Chromium. Úselo para prueba visual, monitoreo, QA o revisión del cliente.
pdfarchivo PDFSiempre utiliza Chromium. Úselo para registros de página duraderos, auditorías, informes o revisión fuera de línea.

Renderizado de navegador y viewport

Estas opciones solo importan cuando render=true, format=screenshot, o format=pdf. Si la renderización está desactivada y la salida es texto/html/markdown/json, se ignoran las opciones de viewport.

ParámetroTipo / predeterminadoDescripción
render_waitms, predeterminado 0Espera adicional después de la carga inicial de la página antes de la captura/extracción. Rango: 0..15000. No incluye el tiempo de inicio de Chromium o de navegación.
viewport_widthnúmero, predeterminado 1365Ancho del viewport del navegador. El modo CSS acepta 320..3840; el modo Windows acepta píxeles de pantalla física hasta 7680.
viewport_heightnúmero, predeterminado 768Altura del viewport del navegador. El modo CSS acepta 320..4000; el modo Windows acepta píxeles de pantalla física hasta 8000.
pixelscss o windowscss significa que los valores del viewport son píxeles CSS del navegador. windows significa que pasa los píxeles de la configuración de pantalla de Windows y ScraperFly los convierte usando display_scale.
display_scalenúmero, predeterminado 150Usado solo con pixels=windows. Acepta 125, 150, 200 o 1.25, 1.5, 2.

Opciones de archivo visual

Estas opciones se aplican solo a format=screenshot y format=pdf. Las respuestas exitosas también se guardan como artefactos descargables en el registro de solicitudes.

ParámetroTipo / predeterminadoDescripción
file_typejpg para captura de pantalla, pdf para PDFLa captura de pantalla admite jpg, jpeg, png, webp. PDF admite solo pdf. BMP no es compatible.
downloadbooleanotrue devuelve Content-Disposition: attachment. false devuelve una vista previa en línea cuando el cliente lo admite.
filenamecadenaNombre de archivo opcional. La extensión se normaliza a partir de file_type.

Ejemplos de Postman

Pegue estos directamente en Postman como ejemplos de URL o referencias de cuerpo de solicitud. Los parámetros de consulta GET y el cuerpo JSON de POST utilizan los mismos nombres de opción.

Listo para Postman

Markdown de una página simple

Utilice una URL GET simple cuando desee una verificación rápida de Postman para una salida de Markdown limpia.

https://scraperfly.com/api/v1?url=https://example.com&format=markdown

PDF con viewport de tamaño Windows

Utilice controles de viewport cuando un archivo visual deba coincidir con un tamaño de pantalla de escritorio real.

https://scraperfly.com/api/v1?url=https://example.com&format=pdf&premium=true&render_wait=10000&viewport_width=2560&viewport_height=1600&pixels=windows&display_scale=150&file_type=pdf&download=true

Cuerpo JSON de POST con las mismas opciones

Cambie a POST cuando la solicitud tenga muchas opciones y un cuerpo JSON sea más fácil de revisar o almacenar.

POST https://scraperfly.com/api/v1
apikey: YOUR_API_KEY_HERE
content-type: application/json

{
  "url": "https://example.com",
  "format": "screenshot",
  "premium": true,
  "render_wait": 10000,
  "viewport_width": 1280,
  "viewport_height": 720,
  "pixels": "css",
  "file_type": "jpg",
  "download": true
}

Ejemplo Avanzado (Premium + Render + Encabezados + País)

Utilice esta configuración cuando un sitio bloquee el tráfico estándar. Habilita el enrutamiento de proxy premium, ejecuta un navegador sin cabeza, mantiene encabezados seleccionados y solicita un proxy específico del país. Si una página aún falla, intente nuevamente con retroceso exponencial, reduzca la concurrencia o pruebe otro país.

8 ejemplos
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US" \
  -H "apikey: YOUR_API_KEY_HERE" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36" \
  -H "Cookie: SESSIONID=27382738"
const params = new URLSearchParams({
  url: "https://example.com",
  premium: "true",
  render: "true",
  keep_headers: "true",
  country: "US"
});

const res = await fetch("https://scraperfly.com/api/v1?" + params.toString(), {
  headers: {
    apikey: "YOUR_API_KEY_HERE",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36",
    "Cookie": "SESSIONID=27382738"
  }
});

const html = await res.text();
console.log(html);
import requests

params = {
  "url": "https://example.com",
  "premium": "true",
  "render": "true",
  "keep_headers": "true",
  "country": "US"
}

headers = {
  "apikey": "YOUR_API_KEY_HERE",
  "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36",
  "Cookie": "SESSIONID=27382738"
}

res = requests.get("https://scraperfly.com/api/v1", params=params, headers=headers, timeout=30)
print(res.text)
<?php
$endpoint = "https://scraperfly.com/api/v1";
$params = http_build_query([
  "url" => "https://example.com",
  "premium" => "true",
  "render" => "true",
  "keep_headers" => "true",
  "country" => "US",
]);

$ch = curl_init($endpoint . "?" . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "apikey: YOUR_API_KEY_HERE",
  "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36",
  "Cookie: SESSIONID=27382738",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$html = curl_exec($ch);
curl_close($ch);
echo $html;
package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "time"
)

func main() {
  q := url.Values{}
  q.Set("url", "https://example.com")
  q.Set("premium", "true")
  q.Set("render", "true")
  q.Set("keep_headers", "true")
  q.Set("country", "US")

  endpoint := "https://scraperfly.com/api/v1?" + q.Encode()
  req, _ := http.NewRequest("GET", endpoint, nil)
  req.Header.Set("apikey", "YOUR_API_KEY_HERE")
  req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36")
  req.Header.Set("Cookie", "SESSIONID=27382738")

  client := &http.Client{ Timeout: 30 * time.Second }
  resp, err := client.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}
using System.Net.Http;
using System.Net.Http.Headers;

var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
http.DefaultRequestHeaders.Add("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36");
http.DefaultRequestHeaders.Add("Cookie", "SESSIONID=27382738");

var endpoint = "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US";
var html = await http.GetStringAsync(endpoint);

Console.WriteLine(html);
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newBuilder()
  .followRedirects(HttpClient.Redirect.NORMAL)
  .build();

HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US"))
  .header("apikey", "YOUR_API_KEY_HERE")
  .header("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36")
  .header("Cookie", "SESSIONID=27382738")
  .GET()
  .build();

HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"

endpoint = URI("https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
req["User-Agent"] = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36"
req["Cookie"] = "SESSIONID=27382738"

res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
  http.read_timeout = 30
  http.request(req)
end

puts res.body

Renderización de JS (Ejemplo Rápido)

Para páginas con mucho JavaScript, establezca render=true. Use esto cuando el HTML fuente no contenga los datos y la página necesite ejecución del navegador primero.

curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
  -H "apikey: YOUR_API_KEY_HERE"

Autenticación & Créditos Restantes

ScraperFly utiliza claves API para autorización. Recomendado: envíe su clave a través del encabezado apikey. El punto final /status devuelve sus créditos restantes e información de la cuenta.

8 ejemplos
curl "https://scraperfly.com/api/v1/status" \
  -H "apikey: YOUR_API_KEY_HERE"
const res = await fetch("https://scraperfly.com/api/v1/status", {
  headers: { apikey: "YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);
import requests

res = requests.get("https://scraperfly.com/api/v1/status", headers={"apikey": "YOUR_API_KEY_HERE"})
print(res.json())
<?php
$ch = curl_init("https://scraperfly.com/api/v1/status");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["apikey: YOUR_API_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$out = curl_exec($ch);
curl_close($ch);
echo $out;
package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://scraperfly.com/api/v1/status", nil)
  req.Header.Set("apikey", "YOUR_API_KEY_HERE")
  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}
using System.Net.Http;

var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");

var json = await http.GetStringAsync("https://scraperfly.com/api/v1/status");
Console.WriteLine(json);
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://scraperfly.com/api/v1/status"))
  .header("apikey", "YOUR_API_KEY_HERE")
  .GET()
  .build();

HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"

endpoint = URI("https://scraperfly.com/api/v1/status")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"

res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
  http.request(req)
end

puts res.body

Manejo de Errores

Los errores se devuelven como JSON con una forma estable. Siempre inspeccione el estado HTTP + error.code para decidir si volver a intentar.

{
  "error": {
    "code": "validation_error",
    "status": 422,
    "context": [
      {
        "url": {
          "type": "invalid_url",
          "message": "missing url"
        }
      }
    ]
  }
}
Reglas de reintento

Reintentar en red/429/temporal 5xx. No reintentar en URL inválida o clave API inválida.

Códigos de Error Comunes

HTTPTipoSignificado
400missing_urlNo se proporcionó un parámetro url válido.
400invalid_urlValor inválido en url.
401missing_api_keyNo se suministró clave API.
403invalid_api_keyLa clave API es inválida o está deshabilitada.
403forbiddenNo hay suficientes créditos o no hay acceso a la función.
429rate_limitedDemasiadas solicitudes concurrentes. Reduzca la velocidad o actualice.
429usage_limit_reachedLímite de plan/mensual alcanzado.
500internal_errorError del servidor. Vuelva a intentar con retroceso.

Casos de Uso Comunes

Mantenga los patrones de producción comunes en un bloque tabulado: comience simple, luego agregue enrutamiento, renderización, encabezados o retroceso solo cuando el objetivo demuestre que los necesita.

4 patrones

1) Proxies Premium

Habilite premium=true para objetivos más difíciles. Agregue country cuando la respuesta cambie por mercado o ubicación.

curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&country=US" \
  -H "apikey: YOUR_API_KEY_HERE"

2) Encabezados Personalizados (User-Agent / Cookies)

Utilice keep_headers=true cuando el contexto del objetivo sea importante y necesite pasar encabezados de solicitud seleccionados.

curl "https://scraperfly.com/api/v1?url=https://example.com&keep_headers=true" \
  -H "apikey: YOUR_API_KEY_HERE" \
  -H "User-Agent: Mozilla/5.0" \
  -H "Accept-Language: en-US,en;q=0.9" \
  -H "Cookie: SESSIONID=27382738"

3) Renderización de JS

Para SPA, Next.js y páginas construidas en el navegador, establezca render=true para que ScraperFly espere la salida de JavaScript antes de extraer la respuesta.

curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
  -H "apikey: YOUR_API_KEY_HERE"

4) Anti-bot & Páginas de Desafío

Si recibe contenido de desafío o bloqueado, combine enrutamiento premium, renderización de navegador, encabezados permitidos realistas, menor concurrencia y retroceso de reintento.

curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US" \
  -H "apikey: YOUR_API_KEY_HERE" \
  -H "User-Agent: Mozilla/5.0" \
  -H "Accept-Language: en-US,en;q=0.9"