Документация ScraperFly
Быстрый старт: аутентификация с помощью вашего API-ключа, получение HTML, включение рендеринга JS, выбор форматов вывода и использование премиум-прокси. ScraperFly намеренно прямолинеен: отправьте URL, выберите необходимые параметры и обрабатывайте возвращаемый HTML, чистый текст, Markdown, JSON, скриншот или PDF в вашем приложении.
/api/v1
Используйте GET параметры запроса или POST JSON. Оба формата запроса возвращают один и тот же результат.
apikey заголовок
Храните ключи на стороне сервера и обновляйте их с панели управления по мере необходимости.
1 до 25 кредитов
Стоимость зависит от премиум-маршрутизации, рендеринга браузера и визуального вывода файлов.
Стоимость кредитов и неудачные запросы
Кредиты зависят от конфигурации запроса (премиум-прокси, рендеринг JS и т. д.) и конечного результата. На практике каждый запрос стоит от 1 до 25 кредитов.
| Премиум | Рендер | Стоимость в кредитах |
|---|---|---|
| false | false | 1 |
| false | true | 5 |
| true | false | 10 |
| true | true | 25 |
- Начните с
premium=false,render=falseдля простых целей. - Включайте
render=trueтолько для страниц с тяжелым JS (React/Vue/Next.js). - Используйте
country, когда цель меняется в зависимости от местоположения. - Если вы сталкиваетесь с проблемами, попробуйте
premium=true+render=true.
Основное использование
Получите HTML целевой страницы. Для основного использования вам нужен только ваш apikey и url. Обычно это использует стандартные прокси и стоит 1 кредит. Ответом является сырой HTML страницы. Если вам нужны структурированные данные, парсите HTML на своей стороне (Cheerio/BeautifulSoup и т. д.).
curl "https://scraperfly.com/api/v1?url=https://example.com" \
-H "apikey: YOUR_API_KEY_HERE"
// Node 18+ имеет встроенный fetch
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
Параметры запроса
Используйте каноническую конечную точку GET /api/v1 с параметрами запроса или POST /api/v1 с теми же полями в теле JSON. Начните с url + format, затем добавьте прокси, рендер, область просмотра или параметры файла только тогда, когда это необходимо для цели.
Основной запрос
| Параметр | Тип | Описание |
|---|---|---|
url | обязательный | URL целевого веб-сайта, который вы хотите скрапировать, например url=https://example.com. |
premium | необязательный, логический | Использует более качественные прокси для более сложных целей. Стоит больше кредитов. |
country | необязательный | Запрашиваемая страна прокси, например US. Журналы использования хранят фактическую страну и город прокси. |
render | необязательный, логический | Рендеринг безголового браузера для страниц, которые требуют JavaScript. Авто-включен для screenshot и pdf. |
keep_headers | необязательный, логический | Передайте свои собственные заголовки (куки, user-agent, accept-language и т. д.). |
format | необязательный | Формат вывода: html, text, markdown, json, screenshot или pdf. |
Форматы вывода
| формат | Ответ | Когда использовать |
|---|---|---|
html | HTML | По умолчанию. Используйте, когда хотите получить сырой источник или рендеренный HTML для вашего собственного парсера. |
text | обычный текст | Используйте, когда вам нужен читаемый чистый текст без навигационного/макетного шума. |
markdown | Markdown | Используйте для подсказок LLM, RAG, документации, резюме и индексации. |
json | JSON | Используйте для метаданных, заголовков, ссылок, чистого текста и Markdown в одном ответе. |
screenshot | файл изображения | Всегда использует Chromium. Используйте для визуального доказательства, мониторинга, QA или обзора клиентом. |
pdf | PDF файл | Всегда использует Chromium. Используйте для долговременных записей страниц, аудиторских следов, отчетов или оффлайн-обзора. |
Рендер браузера и область просмотра
Эти параметры имеют значение только когда render=true, format=screenshot или format=pdf. Если рендер отключен, а вывод - текст/html/markdown/json, параметры области просмотра игнорируются.
| Параметр | Тип / по умолчанию | Описание |
|---|---|---|
render_wait | мс, по умолчанию 0 | Дополнительная задержка после начальной загрузки страницы перед захватом/извлечением. Диапазон: 0..15000. Не включает время запуска Chromium или навигации. |
viewport_width | число, по умолчанию 1365 | Ширина области просмотра браузера. Режим CSS принимает 320..3840; режим Windows принимает физические пиксели дисплея до 7680. |
viewport_height | число, по умолчанию 768 | Высота области просмотра браузера. Режим CSS принимает 320..4000; режим Windows принимает физические пиксели дисплея до 8000. |
pixels | css или windows | css означает, что значения области просмотра являются пикселями CSS браузера. windows означает, что вы передаете пиксели настроек дисплея Windows, и ScraperFly преобразует их с помощью display_scale. |
display_scale | число, по умолчанию 150 | Используется только с pixels=windows. Принимает 125, 150, 200 или 1.25, 1.5, 2. |
Визуальные параметры файла
Эти параметры применяются только к format=screenshot и format=pdf. Успешные ответы также сохраняются как загружаемые артефакты в журнале запросов.
| Параметр | Тип / по умолчанию | Описание |
|---|---|---|
file_type | jpg для скриншота, pdf для PDF | Скриншот поддерживает jpg, jpeg, png, webp. PDF поддерживает только pdf. BMP не поддерживается. |
download | логический | true возвращает Content-Disposition: attachment. false возвращает встроенный предварительный просмотр, если клиент это поддерживает. |
filename | строка | Необязательное имя файла. Расширение нормализуется из file_type. |
Примеры Postman
Вставьте их прямо в Postman в качестве примеров URL или ссылок на тело запроса. Параметры запроса GET и тело JSON POST используют одни и те же имена опций.
Markdown с простой страницы
Используйте простой GET URL, когда хотите быстро проверить Postman для чистого вывода Markdown.
https://scraperfly.com/api/v1?url=https://example.com&format=markdown
PDF с областью просмотра размера Windows
Используйте параметры области просмотра, когда визуальный файл должен соответствовать реальному размеру дисплея рабочего стола.
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 тело с теми же опциями
Переключитесь на POST, когда запрос имеет много опций, и тело JSON легче просмотреть или сохранить.
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
}
Расширенный пример (Премиум + Рендер + Заголовки + Страна)
Используйте эту настройку, когда сайт блокирует стандартный трафик. Она включает маршрутизацию премиум-прокси, запускает безголовый браузер, сохраняет выбранные заголовки и запрашивает прокси, специфичный для страны. Если страница все еще не загружается, повторите попытку с экспоненциальным увеличением времени ожидания, уменьшите параллелизм или протестируйте другую страну.
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, like 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, like 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, как 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, как 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, как 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, как 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, как 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 (Быстрый пример)
Для страниц с тяжелым JavaScript установите render=true. Используйте это, когда исходный HTML не содержит данных, и странице необходимо сначала выполнить код в браузере.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
Аутентификация и оставшиеся кредиты
ScraperFly использует API-ключи для авторизации. Рекомендуется: отправлять ваш ключ через заголовок apikey. Конечная точка /status возвращает ваши оставшиеся кредиты и информацию об аккаунте.
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
Обработка ошибок
Ошибки возвращаются в формате JSON с устойчивой структурой. Всегда проверяйте HTTP статус + error.code, чтобы решить, стоит ли повторять попытку.
{
"error": {
"code": "validation_error",
"status": 422,
"context": [
{
"url": {
"type": "invalid_url",
"message": "отсутствует url"
}
}
]
}
}
Повторите при сетевых/429/временных 5xx. Не повторяйте при недействительном URL или недействительном API-ключе.
Общие коды ошибок
| HTTP | Тип | Значение |
|---|---|---|
| 400 | missing_url | Не предоставлен действительный параметр url. |
| 400 | invalid_url | Недействительное значение в url. |
| 401 | missing_api_key | Не предоставлен API-ключ. |
| 403 | invalid_api_key | API-ключ недействителен или отключен. |
| 403 | forbidden | Недостаточно кредитов или нет доступа к функции. |
| 429 | rate_limited | Слишком много одновременных запросов. Замедлитесь или обновите тариф. |
| 429 | usage_limit_reached | Достигнут лимит плана/месяца. |
| 500 | internal_error | Ошибка сервера. Повторите попытку с увеличением времени ожидания. |
Общие случаи использования
Сохраните общие производственные шаблоны в одном табличном блоке: начните с простого, затем добавьте маршрутизацию, рендеринг, заголовки или увеличение времени ожидания только тогда, когда цель докажет, что это необходимо.
1) Премиум-прокси
Включите premium=true для более сложных целей. Добавьте country, когда ответ меняется в зависимости от рынка или местоположения.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE"
2) Пользовательские заголовки (User-Agent / Cookies)
Используйте keep_headers=true, когда контекст цели имеет значение, и вам нужно передать выбранные заголовки запроса.
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 рендеринг
Для SPA, Next.js и страниц, созданных в браузере, установите render=true, чтобы ScraperFly дождался вывода JavaScript перед извлечением ответа.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
4) Анти-бот и страницы с вызовами
Если вы получаете контент с вызовами или заблокированным контентом, комбинируйте премиум-маршрутизацию, рендеринг браузера, реалистичные разрешенные заголовки, сниженный параллелизм и повторные попытки с увеличением времени ожидания.
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"