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

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

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

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

​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

Skyscanner plugins

Error handling

Raw HTTP (without the package)