Документація 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, like 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, like 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, like 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, like 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, like 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"