ScraperFly Dokumentation
Quickstart: Authentifizieren Sie sich mit Ihrem API-Schlüssel, holen Sie HTML ab, aktivieren Sie die JS-Rendering, wählen Sie Ausgabeformate und verwenden Sie Premium-Proxys. ScraperFly ist absichtlich direkt: Senden Sie eine URL, wählen Sie die benötigten Steuerungen aus und verarbeiten Sie das zurückgegebene HTML, sauberen Text, Markdown, JSON, Screenshot oder PDF in Ihrer Anwendung.
/api/v1
Verwenden Sie GET Abfrageparameter oder POST JSON. Beide Anforderungsformen liefern dasselbe Ergebnis.
apikey Header
Bewahren Sie Schlüssel serverseitig auf und rotieren Sie sie bei Bedarf über das Dashboard.
1 bis 25 Credits
Die Kosten hängen von der Premium-Routing, Browser-Rendering und visuellen Dateiausgabe ab.
Credit-Kosten & Fehlgeschlagene Anfragen
Credits hängen von der Anforderungs-Konfiguration (Premium-Proxys, JS-Rendering usw.) und dem endgültigen Ergebnis ab. In der Praxis kostet jede Anfrage zwischen 1 und 25 Credits.
| Premium | Render | Kosten in Credits |
|---|---|---|
| false | false | 1 |
| false | true | 5 |
| true | false | 10 |
| true | true | 25 |
- Beginnen Sie mit
premium=false,render=falsefür einfache Ziele. - Aktivieren Sie
render=truenur für JS-intensive Seiten (React/Vue/Next.js). - Verwenden Sie
country, wenn sich das Ziel je nach Standort ändert. - Wenn Sie auf Challenge-Seiten stoßen, versuchen Sie
premium=true+render=true.
Grundlegende Nutzung
Holen Sie sich das HTML einer Zielseite. Für die grundlegende Nutzung benötigen Sie nur Ihren apikey und eine url. Dies verwendet typischerweise Standard-Proxys und kostet 1 Credit. Die Antwort ist das rohe HTML der Seite. Wenn Sie strukturierte Daten benötigen, parsen Sie das HTML auf Ihrer Seite (Cheerio/BeautifulSoup/etc.).
curl "https://scraperfly.com/api/v1?url=https://example.com" \
-H "apikey: YOUR_API_KEY_HERE"
// Node 18+ hat fetch eingebaut
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
Anforderungsparameter
Verwenden Sie den kanonischen Endpoint GET /api/v1 mit Abfrageparametern oder POST /api/v1 mit denselben Feldern in einem JSON-Body. Beginnen Sie mit url + format, und fügen Sie dann Proxy-, Render-, Viewport- oder Dateioptionen nur hinzu, wenn das Ziel sie benötigt.
Kernanforderung
| Parameter | Typ | Beschreibung |
|---|---|---|
url | erforderlich | URL der Zielwebsite, die Sie scrapen möchten, z.B. url=https://example.com. |
premium | optional, boolean | Verwendet hochwertigere Proxy-Pools für schwierigere Ziele. Kostet mehr Credits. |
country | optional | Gewünschtes Proxy-Land, z.B. US. Nutzungsprotokolle speichern das tatsächliche Proxy-Land und die Stadt. |
render | optional, boolean | Headless-Browser-Rendering für Seiten, die JavaScript benötigen. Automatisch aktiviert für screenshot und pdf. |
keep_headers | optional, boolean | Geben Sie Ihre eigenen Header (Cookies, User-Agent, Accept-Language usw.) weiter. |
format | optional | Ausgabeformat: html, text, markdown, json, screenshot oder pdf. |
Ausgabeformate
| format | Antwort | Wann zu verwenden |
|---|---|---|
html | HTML | Standard. Verwenden Sie, wenn Sie den rohen Quellcode oder gerendertes HTML für Ihren eigenen Parser möchten. |
text | reiner Text | Verwenden Sie, wenn Sie lesbaren sauberen Text ohne Navigations-/Layoutgeräusche benötigen. |
markdown | Markdown | Verwenden Sie für LLM-Prompts, RAG, Dokumente, Zusammenfassungen und Indizierung. |
json | JSON | Verwenden Sie für Metadaten, Titel, Überschriften, Links, sauberen Text und Markdown in einer Antwort. |
screenshot | Bilddatei | Verwendet immer Chromium. Verwenden Sie für visuelle Beweise, Überwachung, QA oder Kundenbewertungen. |
pdf | PDF-Datei | Verwendet immer Chromium. Verwenden Sie für dauerhafte Seitenaufzeichnungen, Prüfpfade, Berichte oder Offline-Überprüfungen. |
Browser-Rendering und Viewport
Diese Optionen sind nur relevant, wenn render=true, format=screenshot oder format=pdf. Wenn das Rendering deaktiviert ist und die Ausgabe text/html/markdown/json ist, werden die Viewport-Optionen ignoriert.
| Parameter | Typ / Standard | Beschreibung |
|---|---|---|
render_wait | ms, Standard 0 | Zusätzliche Wartezeit nach dem initialen Seitenladen vor der Erfassung/Extraktion. Bereich: 0..15000. Es umfasst nicht die Start- oder Navigationszeit von Chromium. |
viewport_width | Nummer, Standard 1365 | Breite des Browser-Viewports. Der CSS-Modus akzeptiert 320..3840; Der Windows-Modus akzeptiert physische Anzeigepixel bis zu 7680. |
viewport_height | Nummer, Standard 768 | Höhe des Browser-Viewports. Der CSS-Modus akzeptiert 320..4000; Der Windows-Modus akzeptiert physische Anzeigepixel bis zu 8000. |
pixels | css oder windows | css bedeutet, dass die Viewport-Werte Browser-CSS-Pixel sind. windows bedeutet, dass Sie Windows-Anzeigeeinstellungen-Pixel übergeben und ScraperFly sie mit display_scale konvertiert. |
display_scale | Nummer, Standard 150 | Wird nur mit pixels=windows verwendet. Akzeptiert 125, 150, 200 oder 1.25, 1.5, 2. |
Visuelle Dateioptionen
Diese Optionen gelten nur für format=screenshot und format=pdf. Erfolgreiche Antworten werden auch als herunterladbare Artefakte im Anforderungsprotokoll gespeichert.
| Parameter | Typ / Standard | Beschreibung |
|---|---|---|
file_type | jpg für Screenshot, pdf für PDF | Screenshot unterstützt jpg, jpeg, png, webp. PDF unterstützt nur pdf. BMP wird nicht unterstützt. |
download | boolean | true gibt Content-Disposition: attachment zurück. false gibt eine Inline-Vorschau zurück, wenn der Client dies unterstützt. |
filename | string | Optionaler Dateiname. Die Erweiterung wird aus file_type normalisiert. |
Postman-Beispiele
Fügen Sie diese direkt in Postman als URL-Beispiele oder Referenzen für den Anfrage-Body ein. GET-Abfrageparameter und POST-JSON-Body verwenden dieselben Optionsnamen.
Markdown von einer einfachen Seite
Verwenden Sie eine einfache GET-URL, wenn Sie einen schnellen Postman-Sanity-Check für saubere Markdown-Ausgaben wünschen.
https://scraperfly.com/api/v1?url=https://example.com&format=markdown
PDF mit Windows-Größe Viewport
Verwenden Sie Viewport-Steuerungen, wenn eine visuelle Datei mit einer echten Desktop-Anzeigengröße übereinstimmen muss.
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
POST JSON-Body mit denselben Optionen
Wechseln Sie zu POST, wenn die Anfrage viele Optionen hat und ein JSON-Body einfacher zu überprüfen oder zu speichern ist.
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
}
Erweitertes Beispiel (Premium + Render + Header + Land)
Verwenden Sie dieses Setup, wenn eine Seite den Standardverkehr blockiert. Es ermöglicht Premium-Proxy-Routing, führt einen Headless-Browser aus, behält ausgewählte Header bei und fordert einen länderspezifischen Proxy an. Wenn eine Seite weiterhin fehlschlägt, versuchen Sie es mit exponentiellem Backoff, reduzieren Sie die Parallelität oder testen Sie ein anderes Land.
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, wie 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, wie 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, wie 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, wie 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, wie 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, wie 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, wie 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
JS-Rendering (Schnelles Beispiel)
Für JavaScript-intensive Seiten setzen Sie render=true. Verwenden Sie dies, wenn das Quell-HTML nicht die Daten enthält und die Seite zuerst eine Browserausführung benötigt.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
Authentifizierung & Verbleibende Credits
ScraperFly verwendet API-Schlüssel zur Autorisierung. Empfohlen: Senden Sie Ihren Schlüssel über den apikey Header. Der /status Endpoint gibt Ihre verbleibenden Credits und Kontoinformationen zurück.
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
Fehlerbehandlung
Fehler werden als JSON mit einer stabilen Struktur zurückgegeben. Überprüfen Sie immer den HTTP-Status + error.code, um zu entscheiden, ob Sie es erneut versuchen sollten.
{
"error": {
"code": "validation_error",
"status": 422,
"context": [
{
"url": {
"type": "invalid_url",
"message": "fehlende URL"
}
}
]
}
}
Wiederholen Sie bei Netzwerk-/429/temporären 5xx. Nicht wiederholen bei ungültiger URL oder ungültigem API-Schlüssel.
Häufige Fehlercodes
| HTTP | Typ | Bedeutung |
|---|---|---|
| 400 | missing_url | Kein gültiger url Parameter angegeben. |
| 400 | invalid_url | Ungültiger Wert in url. |
| 401 | missing_api_key | Kein API-Schlüssel angegeben. |
| 403 | invalid_api_key | API-Schlüssel ist ungültig oder deaktiviert. |
| 403 | forbidden | Nicht genügend Credits oder kein Zugriff auf die Funktion. |
| 429 | rate_limited | Zu viele gleichzeitige Anfragen. Verlangsamen Sie oder upgraden Sie. |
| 429 | usage_limit_reached | Plan/monatliches Limit erreicht. |
| 500 | internal_error | Serverfehler. Wiederholen Sie mit Backoff. |
Häufige Anwendungsfälle
Halten Sie die gängigen Produktionsmuster in einem tabbed Block: Beginnen Sie einfach und fügen Sie Routing, Rendering, Header oder Backoff nur hinzu, wenn das Ziel nachweist, dass es sie benötigt.
1) Premium-Proxys
Aktivieren Sie premium=true für schwierigere Ziele. Fügen Sie country hinzu, wenn die Antwort je nach Markt oder Standort variiert.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE"
2) Benutzerdefinierte Header (User-Agent / Cookies)
Verwenden Sie keep_headers=true, wenn der Kontext des Ziels wichtig ist und Sie ausgewählte Anforderungsheader weitergeben müssen.
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) JS-Rendering
Für SPA, Next.js und browserbasierte Seiten setzen Sie render=true, damit ScraperFly auf die JavaScript-Ausgabe wartet, bevor die Antwort extrahiert wird.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
4) Anti-Bot & Challenge-Seiten
Wenn Sie auf Challenge- oder blockierte Inhalte stoßen, kombinieren Sie Premium-Routing, Browser-Rendering, realistische erlaubte Header, niedrigere Parallelität und Wiederholungs-Backoff.
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"