ScraperFlyAPI веб-даних для AI

docs

Документація для вашого першого запиту ScraperFly

API навмисно простий: надішліть URL, виберіть необхідні параметри та обробіть повернений HTML або витягнуту відповідь у вашому додатку.

Документація

Документація ScraperFly

Швидкий старт: автентифікація за допомогою вашого API ключа, отримання HTML, увімкнення рендерингу JS, вибір форматів виводу та використання преміум-проксі. ScraperFly навмисно простий: надішліть URL, виберіть необхідні параметри та обробіть повернений HTML, чистий текст, Markdown, JSON, скріншот або PDF у вашій програмі.

Кінцева точка

/api/v1

Використовуйте GET параметри запиту або POST JSON. Обидва формати запиту повертають один і той же результат.

Авторизація

apikey заголовок

Зберігайте ключі на сервері та змінюйте їх з панелі керування за потреби.

Кредити

1 до 25 кредитів

Витрати залежать від преміум-маршрутизації, рендерингу браузера та візуального виводу файлів.

Витрати кредитів та невдалі запити

Кредити залежать від конфігурації запиту (преміум-проксі, рендеринг JS тощо) та остаточного результату. На практиці кожен запит коштує від 1 до 25 кредитів.

ПреміумРендерингВартість у кредитах
falsefalse1
falsetrue5
truefalse10
truetrue25
Поради для контролю витрат
  • Почніть з premium=false, render=false для простих цілей.
  • Увімкніть render=true лише для сторінок з великою кількістю JS (React/Vue/Next.js).
  • Використовуйте country, коли ціль змінюється в залежності від місця розташування.
  • Якщо ви натрапите на сторінки з викликами, спробуйте premium=true + render=true.

Основне використання

Отримайте HTML цільової сторінки. Для основного використання вам потрібні лише ваш apikey та url. Це зазвичай використовує стандартні проксі та коштує 1 кредит. Відповідь - це сирий HTML сторінки. Якщо вам потрібні структуровані дані, розпарсите HTML на вашій стороні (Cheerio/BeautifulSoup тощо).

8 прикладів
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.

Формати виводу

форматВідповідьКоли використовувати
htmlHTMLЗа замовчуванням. Використовуйте, коли вам потрібен сирий код або рендерений HTML для вашого парсера.
textчистий текстВикористовуйте, коли вам потрібен читабельний чистий текст без навігаційного/макетного шуму.
markdownMarkdownВикористовуйте для запитів LLM, RAG, документів, резюме та індексації.
jsonJSONВикористовуйте для метаданих, заголовків, заголовків, посилань, чистого тексту та Markdown в одній відповіді.
screenshotфайл зображенняЗавжди використовує Chromium. Використовуйте для візуального підтвердження, моніторингу, QA або відгуків клієнтів.
pdfPDF файлЗавжди використовує 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.
pixelscss або windowscss означає, що значення вікна перегляду є пікселями CSS браузера. windows означає, що ви передаєте пікселі налаштувань дисплея Windows, а ScraperFly перетворює їх за допомогою display_scale.
display_scaleчисло, за замовчуванням 150Використовується лише з pixels=windows. Приймає 125, 150, 200 або 1.25, 1.5, 2.

Візуальні параметри файлів

Ці параметри застосовуються лише до format=screenshot та format=pdf. Успішні відповіді також зберігаються як завантажувані артефакти в журналі запитів.

ПараметрТип / за замовчуваннямОпис
file_typejpg для скріншота, pdf для PDFСкріншот підтримує jpg, jpeg, png, webp. PDF підтримує лише pdf. BMP не підтримується.
downloadбулевийtrue повертає Content-Disposition: attachment. false повертає вбудований попередній перегляд, коли клієнт це підтримує.
filenameрядокНеобов'язкове ім'я файлу. Розширення нормалізується з file_type.

Приклади Postman

Вставте їх безпосередньо в Postman як приклади URL або посилання на тіло запиту. Параметри запиту GET та тіло JSON POST використовують ті ж назви опцій.

Готово до Postman

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
}

Розширений приклад (Преміум + Рендеринг + Заголовки + Країна)

Використовуйте цю конфігурацію, коли сайт блокує стандартний трафік. Це дозволяє преміум-проксі маршрутизацію, запускає безголовий браузер, зберігає вибрані заголовки та запитує проксі, специфічну для країни. Якщо сторінка все ще не вдається, спробуйте з експоненційним зворотним зв'язком, зменшіть паралельність або протестуйте іншу країну.

8 прикладів
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 повертає ваші залишкові кредити та інформацію про обліковий запис.

8 прикладів
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ТипЗначення
400missing_urlНе надано жодного дійсного параметра url.
400invalid_urlНедійсне значення в url.
401missing_api_keyНе надано API ключ.
403invalid_api_keyAPI ключ недійсний або відключений.
403forbiddenНедостатньо кредитів або немає доступу до функції.
429rate_limitedЗанадто багато одночасних запитів. Сповільніть або оновіть.
429usage_limit_reachedДосягнуто ліміту плану/місячного.
500internal_errorПомилка сервера. Повторіть запит з зворотним зв'язком.

Загальні випадки використання

Зберігайте загальні виробничі шаблони в одному вкладеному блоці: починайте просто, а потім додавайте маршрутизацію, рендеринг, заголовки або зворотний зв'язок лише тоді, коли ціль доведе, що їй це потрібно.

4 шаблони

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"