ScrapeUnblocker Documentation

The official PHP client wraps the ScrapeUnblocker API in a small, dependency-free package (built-in cURL) with typed exceptions and automatic retries.

composer require scrapeunblocker/client

Requires PHP 8.1+ with the curl and json extensions. Store your API key in an environment variable so the client picks it up automatically:

export SCRAPEUNBLOCKER_KEY="YOUR_API_KEY"

Quickstart

<?php
require 'vendor/autoload.php';

use ScrapeUnblocker\Client;

$su = new Client(); // reads SCRAPEUNBLOCKER_KEY, or new Client('YOUR_API_KEY')

$html = $su->getPageSource('https://example.com');

Get Markdown for LLMs

getMarkdown() (0.13.0+) returns the page as clean Markdown for LLMs, agents and RAG pipelines: headings, lists, tables, absolute links and images with alt text, without scripts, styles, navigation or footer. By default you get the main content only. It takes the same options as getPageSource() except list_elements, and is billed the same.

$md = $su->getMarkdown('https://en.wikipedia.org/wiki/Web_scraping');

// The whole page, not only the main content
$full = $su->getMarkdown($url, ['main_content_only' => false]);

See Markdown for LLMs for what is kept and what is dropped.

Get parsed JSON instead of HTML

$product = $su->getParsed('https://www.amazon.com/dp/B08N5WRWNW');

echo $product->pageType;   // "product"
print_r($product->data);   // the fields

// If a parse ever comes back wrong, force a fresh set of rules:
$fresh = $su->getParsed($url, ['refresh_rules' => true, 'rules_hint' => 'price is missing']);

When the page loads but nothing can be extracted from it, getParsed() does not raise: it returns a result with page type unknown and empty data, together with the rendered HTML (the API’s data_extracted: false and html fields). The call is billed like a page-source call. See when nothing can be extracted. See the parsed data guide for response shapes.

Scrape a Google SERP

$serp = $su->serp('best running shoes', ['pages_to_check' => 2]);

foreach ($serp['organic'] as $result) {
    echo $result['position'], ' ', $result['title'], ' ', $result['url'], "\n";
}

Force a country

$result = $su->getParsed('https://www.amazon.de/dp/B08N5WRWNW', ['proxy_country' => 'de']);

Capture cookies and the proxy used

$page = $su->getPageWithCookies('https://example.com');
echo $page->html;
print_r($page->cookies);
echo $page->proxy;

Fetch an image

$bytes = $su->getImage('https://example.com/photo.jpg');
file_put_contents('photo.jpg', $bytes);

Drive the browser with steps

Pass a native array of actions to run in a real browser after the page loads. You get back the HTML of the resulting state.

$html = $su->getPageSource('https://example.com', [
    'steps' => [
        ['action' => 'type', 'selector' => 'input[name=q]', 'value' => 'wireless headphones'],
        ['action' => 'press_key', 'value' => 'Enter'],
        ['action' => 'wait_for', 'selector' => '.search-results', 'timeout_ms' => 10000],
    ],
]);

Discover the selectors first with listElements(), which returns the page’s interactive elements as an array:

$page = $su->listElements('https://example.com');

foreach ($page['elements'] as $el) {
    echo $el['tag'], ' ', $el['selector'], ' ', $el['text'], PHP_EOL;
}

Each element’s selector drops straight into a steps action. Full action reference in the browser steps guide.

Amazon

Product and search data as an array, priced in the marketplace’s own currency:

// One product by ASIN (or ['url' => 'https://www.amazon.de/dp/B0BSHF7WHW'])
$product = $su->amazonProduct(['asin' => 'B0BSHF7WHW', 'marketplace' => 'amazon.com']);
echo $product['title'], ' ', $product['price'], ' ', $product['currency'], PHP_EOL;

// Keyword search
$results = $su->amazonSearch('wireless headphones', ['sort' => 'price_asc']);
foreach ($results['results'] as $item) {
    echo $item['title'], ' ', $item['price'], ' ', $item['currency'], ' ', $item['asin'], PHP_EOL;
}

proxy_country defaults to the marketplace’s home country (amazon.com -> US, amazon.de -> DE), so prices come back in the right currency with no configuration. Full field list on the Amazon plugin page.

eBay search

Listings from any of the 19 regional eBay marketplaces as JSON:

$items = $su->ebaySearch('iphone 13', [
    'marketplace' => 'ebay.com',
    'condition' => 'used',
    'sort' => 'newly_listed',
]);

if ($items['exactMatches']) {
    foreach ($items['results'] as $item) {
        echo $item['title'], ' ', $item['price'], ' ', $item['currency'], PHP_EOL;
    }
}

exactMatches is false when eBay found nothing for the keyword and answered with its own loosely-related suggestions instead. Full field list on the eBay Search plugin page.

Skyscanner plugins

$locations = $su->skyscanner->flightLocations('London');

$flights = $su->skyscanner->flights([
    'origin' => 'London', 'dest' => 'New York',
    'depart_date' => '2026-09-01', 'adults' => 1, 'currency' => 'USD',
]);

$hotels = $su->skyscanner->hotels(['destination' => 'Madrid', 'checkin' => '2026-09-01', 'checkout' => '2026-09-03']);
$cars = $su->skyscanner->carhire(['pickup' => 'Madrid', 'pickup_datetime' => '2026-09-01T10:00', 'dropoff_datetime' => '2026-09-03T10:00']);

Every other plugin

The client has a method for every plugin (0.10.0 and later) - the plugin’s main input goes in as the first argument(s), everything else in an options array keyed by the API’s parameter names, and options you leave out are not sent, so the API’s defaults apply. Each plugin page shows its method next to cURL. Methods for newer plugins come with newer releases: the Google Hotels, Google News, Google Ads Transparency, Shopee, Taobao, Upwork, Smyths Toys and Wish methods need 0.14.0 or later.

$products = $su->targetSearch('coffee maker', ['sort' => 'price_low', 'max_results' => 48]);
$milk = $su->woolworthsProduct('888137');                         // one product, with nutrition
$trends = $su->googleTrends(['coffee', 'tea'], ['geo' => 'US']);  // a list is sent comma-separated
$reviews = $su->trustpilotReviews('www.nike.com', ['stars' => [4, 5]]);
$hotels = $su->googleHotels('Lisbon', ['check_in' => '2026-11-20', 'check_out' => '2026-11-22']); // 0.14.0+

// Any plugin endpoint by path
$data = $su->plugin('/marketplace/target-search', ['query' => 'tv', 'max_results' => 24]);

Error handling

Non-2xx responses throw typed exceptions, all subclasses of ScrapeUnblockerException. Transient failures (429, 502, 503, 504 and network errors) are retried automatically; a 401 or 402 is never retried, because it clears when the key or the billing state changes.

use ScrapeUnblocker\Exception\BlockedException;
use ScrapeUnblocker\Exception\PaymentRequiredException;
use ScrapeUnblocker\Exception\RateLimitException;
use ScrapeUnblocker\Exception\UpstreamOutageException;

try {
    $html = $su->getPageSource('https://example.com');
} catch (BlockedException $e) {
    // 403: the target blocked every bypass path (not billed)
} catch (PaymentRequiredException $e) {
    // 402: quota, credit limit, or a failed payment - fix billing
} catch (RateLimitException $e) {
    // 429: slow down
} catch (UpstreamOutageException $e) {
    // 503: the target site itself is down - retry later
}

Exception	Status	Meaning
`InvalidRequestException`	400	Bad URL, unsupported scheme, or the API key header was not sent
`AuthenticationException`	401	Key not recognised - typo, stray whitespace, or a rotated key
`NoSubscriptionException`	401	Key is fine, but the account has no active plan
`PaymentRequiredException`	402	Billing block - base class for the four below
`QuotaExceededException`	402	The plan’s requests for this period are used up
`CreditLimitExceededException`	402	Unpaid balance is past the account’s credit limit
`BudgetExceededException`	402	This period’s spend reached the monthly budget limit you set in your profile (from SDK 0.9.0)
`PaymentFailedException`	402	A card payment was declined three times
`BlockedException`	403	Blocked by bot protection on every path
`NotFoundException`	404	A plugin lookup found nothing
`TargetNotFoundException`	404 / 410	The target site says the page does not exist (`X-Origin-Status` set). Billed; carries the origin status, the target’s page and the destination URL. Subclass of `NotFoundException`, never retried
`BrowserTimeoutException`	408	Our browser run timed out before the page was ready
`UnsupportedContentException`	415	The URL serves something other than HTML (page methods) or other than an image (`getImage`)
`ValidationException`	422	Missing or wrong-typed parameter; `$body` holds the `detail` array
`RateLimitException`	429	Too many requests
`UpstreamOutageException`	503	The target origin is down
`ServerException`	5xx	Unexpected server error, including a 504 upstream timeout
`TimeoutException`	-	This client gave up locally before the API answered
`ConnectionException`	-	Could not reach the API

The 402 and 404-422 exceptions were added in 0.1.6; before that they arrived as a bare ApiException. Nothing was removed, so catch (ApiException) written against earlier versions keeps working. See all status codes in Errors.

Tune the retry count and timeout on the client:

new Client('YOUR_API_KEY', ['timeout' => 180, 'max_retries' => 2]);

Raw HTTP (without the package)

The API is plain HTTP, so you can call it with cURL directly - no package required.

$ch = curl_init('https://api.scrapeunblocker.com/getPageSource?url=https://example.com&parsed_data=true');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['x-scrapeunblocker-key: ' . getenv('SCRAPEUNBLOCKER_KEY')],
]);
$payload = json_decode(curl_exec($ch), true);
echo $payload['data']['page_type'];

The endpoints are getPageSource, serpApi, and getImage; every parameter shown above maps to a query parameter of the same name.

Get Started

No-code area

Spider Cloud

Plugins

AI Assistants

Guides

Code Examples

PHP

Quickstart

Get Markdown for LLMs

Get parsed JSON instead of HTML

Scrape a Google SERP

Force a country

Capture cookies and the proxy used

Fetch an image

Drive the browser with steps

Amazon

eBay search

Skyscanner plugins

Every other plugin

Error handling

Raw HTTP (without the package)

​Quickstart

​Get Markdown for LLMs

​Get parsed JSON instead of HTML

​Scrape a Google SERP

​Force a country

​Capture cookies and the proxy used

​Fetch an image

​Drive the browser with steps

​Amazon

​eBay search

​Skyscanner plugins

​Every other plugin

​Error handling

​Raw HTTP (without the package)

Quickstart

Get Markdown for LLMs

Get parsed JSON instead of HTML

Scrape a Google SERP

Force a country

Capture cookies and the proxy used

Fetch an image

Drive the browser with steps

Amazon

eBay search

Skyscanner plugins

Every other plugin

Error handling

Raw HTTP (without the package)