McAPI - Screenshot API PHP

PHP sample code to capture website screenshots with the McAPI Screenshot REST API service. The sample uses PHP 7 but the code will also work with older versions. The samples use the modules curl and json which should all be available with a standard PHP installation. All samples will also work in Laravel.

Requirements: A free RapidAPI account. Replace YOUR_API_KEY in the snippets below with your RapidAPI key.

All samples below work with the free tier of the API, see RapidAPI McAPI Screenshot Listing for available plans.

See the overview page for a reference that lists all available parameters and error codes.

Take a screenshot using PHP

In the first PHP sample, we use curl to take a screenshot of the Indiehackers website. The device is set to Default, which will create a screenshot for a generic Desktop computer with a resolution of 1024x768 pixel. With the storeExternal option set to "false", the screenshot will be returned as a base64 encoded JPEG. See snippet at end of page on how to write base64 encoded images to file with PHP.

The source code:

// PHP

  
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcapi-screenshot.p.rapidapi.com/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{
    \"url\": \"https://indiehackers.com\",
    \"format\": \"jpeg\",
    \"storeExternal\": \"false\",
    \"devices\": [ \"Default\" ]
  }",
  CURLOPT_HTTPHEADER => [
    "content-type: application/json",
    "x-rapidapi-host: mcapi-screenshot.p.rapidapi.com",
    "x-rapidapi-key: YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

The response will be delivered as a JSON object in the $response variable:

{
  "service": "McAPI Screenshot Generator, https://mcapi.io",
  "version": "V1",
  "url": "https://indiehackers.com",
  "screenshots": [
    {
      "device": "Default",
      "screenshot": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB ... 9yXvZG0pSuhyP/9k="
    }
  ]
}

McAPI Screenshot API - Sample screenshot with PHP

The returned image from the PHP request:

Image of McAPI Screenshot API Sample Screenshot PHP

Specifying devices

The Screenshot API contains a built-in database of over one hundred predefined devices and screen sizes. To get a list of all devices use the listDevices option, like so:

// PHP
  
...

CURLOPT_POSTFIELDS => "{
  \"listDevices\": \"true\"
}"

...

The API will now return an array of all known devices:

{
  "devices": [

    ...
  
    { "name": "iPhone 12 mini", "width": 375, "height": 812 },
    { "name": "iPhone 12 mini landscape", "width": 812, "height": 375 },
    { "name": "iPhone 12", "width": 390, "height": 844 },
    { "name": "iPhone 12 landscape", "width": 844, "height": 390 },
    { "name": "iPhone 12 Pro", "width": 390, "height": 844 },
    { "name": "iPhone 12 Pro landscape", "width": 844, "height": 390 },
    { "name": "iPhone 12 Pro Max", "width": 428, "height": 926 },
    { "name": "iPhone 12 Pro Max landscape", "width": 926, "height": 428 },

    ...
  ]
}

Internally, the API also maintains proper User Agent-strings for all devices, those are not shown in the list.

Usinga predefined device is simple, just set the name in your call:

// PHP
  
...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"devices\": [ \"iPhone 12\" ]
}"

...

The devices option is an array; to create a batch of multiple screenshots at once, simply list additional devices (the current limit is five devices):

// PHP
  
...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"devices\": [ \"iPhone 12\", \"iPhone 12 landscape\" ]
}"

...

Note that specifying multiple devices will cause the API to load the target URL for each device and then take a screenshot; this can take some time with slow or "heavy" sites and may cause your PHP code (or the API) to timeout; see the discussion on timeouts.

Specifying viewports

If none of the predefined devices and screen sizes are suitable for use case, you can set your own viewport like so:

// PHP
  
...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"viewPort\": { \"width\": 800, \"height\": 600 }
}"

...

This will create a screenshot with 800x600px; if a viewport is specified, the API will use a generic desktop User agent-string when loading the target URL.

Note that the viewPort param is ignored if a devices array is also specified.

Taking a screenshot with PHP - Clicking cookie warnings, block ads

If so desired, the API can also automatically click the "Accept", "Accept all" or a similarly worded button on GDPR / DSGVO cookie warnings (Note that this feature is experimental for V1 of the, see this discussion.)

Consider this screenshot of CNBC.com with default API settings. This site presents a huge cookie warning to new visitors:

Screenshot API - Cookie Consent Banner PHP

Set the cookie option to "true", like so:

// PHP
  
...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"cookie\": \"true\",  
  \"devices\": [ \"Default\" ]
}"

...

We can now take a screenshot without the cookie warning removed:

Screenshot API - Clicked Cookie Banner and Ad with PHP

Blocking ads in screenshots

It can be useful to take screenshots with ads, for example if you want to check ad rotation or ad placement; however, in many cases you will simply want to block them. The screenshot API comes with a built-in ad blocker, you activate it using the adblock option like so:

// PHP
  
...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"cookie\": \"true\", 
  \"adblock\": \"true\",  
  \"devices\": [ \"Default\" ]
}"

...

Screenshot of the CNBC site without cookie warning and without ads:

Screenshot API - Clicked Cookie Banner and Ad blocked PHP

The header-parameter - taking screenshots with PHP and export them to file

With the storeExternal option set to "false", the screenshot image is returned as a base64 encoded string. With default settings, this string will preceded by a MIME header that describes the media type of the encoded image.

Sample data block for a screenshot, to be returned as a PNG:

// PHP

...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"storeExternal\": \"false\", 
  \"format\": \"png\"
}"

...

The result from this API call will look like this:

{
  "service": "McAPI Screenshot Generator, https://mcapi.io",
  "version": "V1",
  "url": "https://mcapi.io",
  "screenshots": [
    {
      "device": "Default",
      "screenshot": "data:image/png;base64,iVBORr/klmpqa2 ... 9yXvZG0pjjmSuhQmCC"
    }
  ]
}

After parsing the result with a JSON parser you can directly set the "screenshot"-string as the src property of an img tag, like so:

// PHP

...

if(curl_getinfo($curl, CURLINFO_HTTP_CODE) == 200){
    // In production code you would test the result of json_decode against null
    // and iterate over the screenshots array
    $screenshot = json_decode($response, true)["screenshots"][0]["screenshot"];
    echo "<img src=\"" . $screenshot . "\"/>"; 
  }
  else{
    echo "Error";
  }

...

The MIME header will make sure that the image data is interpreted correctly by the browser. However, when writing the image data to a file, including the header would result in an invalid JPEG or PNG. To create a screenshot image without the header, set the header option to "false", like so:

// PHP

...

CURLOPT_POSTFIELDS => "{
  \"url\": \"https://mcapi.io\",
  \"storeExternal\": \"false\", 
  \"header\": \"false\" 
}"

...

We now get the screenshot without header string:

{
  "service": "McAPI Screenshot Generator, https://mcapi.io",
  "version": "V1",
  "format": "png",
  "url": "https://mcapi.io",
  "screenshots": [
    {
      "device": "Default",
      "screenshot": "iVBORr/klmpqa2 ... 9yXvZG0pjjmSuhQmCC"
    }
  ]
}

Now, all we have to do is decode the base64 string and then write the screenshot to a file, listed here as a complete PHP example:

// PHP

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcapi-screenshot.p.rapidapi.com/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{
    \"url\": \"https://indiehackers.com\",
    \"storeExternal\": \"false\", 
    \"format\": \"png\",
    \"header\": \"false\"
}",
  CURLOPT_HTTPHEADER => [
    "content-type: application/json",
    "x-rapidapi-host: mcapi-screenshot.p.rapidapi.com",
    "x-rapidapi-key: YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

if ($err) {
  echo "Error: " . $err;
} else {
  if(curl_getinfo($curl, CURLINFO_HTTP_CODE) == 200){
    // In production code you would test the result of json_decode against null
    // and iterate over the screenshots array
    $screenshot = json_decode($response, true)["screenshots"][0]["screenshot"];
    $png = base64_decode($screenshot);
    $f = fopen("screenshot.png", "wb");
    fwrite($f, $png);
    fclose($f);
  }
  else{
    echo "Error";
  }
}
curl_close($curl);

Back to McAPI Screenshot API main page.