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 parsed JSON instead of HTML

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

echo $product->pageType;   // "product"
echo $product->source;     // how it was extracted
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']);

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']);

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 three below
`QuotaExceededException`	402	The plan’s requests for this period are used up
`CreditLimitExceededException`	402	Unpaid balance is past the account’s credit limit
`PaymentFailedException`	402	A card payment was declined three times
`BlockedException`	403	Blocked by bot protection on every path
`NotFoundException`	404	Page loaded but held no image (`getImage` only)
`BrowserTimeoutException`	408	Our browser run timed out before the page was ready
`UnsupportedContentException`	415	The URL serves something other than HTML
`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 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

Error handling

Raw HTTP (without the package)

​Quickstart

​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

​Error handling

​Raw HTTP (without the package)

Quickstart

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

Error handling

Raw HTTP (without the package)