McAPI - Screenshot API Overview

An easy to use Screenshot capture REST API for fast and reliable website screenshots. The API features a database of over one hundred pre-defined devices and screen sizes and also supports user defined screen sizes. Up to five screenshots can be captured per REST call in batch mode for different screen sizes, very useful if you want to test website designs against a variety of devices.

The API comes with a built-in ad blocker, can automatically click Cookie consent banners (this features is experimental as of V1.0) and supports full-length screenshots with up to 32000px height. Screenshots are returned from the API as a downloadable web URL or as a base64-encoded JPEG or PNG. Extensive sample code illustrates screenshot creation in Node / JS, Python, Ruby, Swift, PHP, C# and other languages and environments.

McAPI Screenshot API - Plans and pricing

We provide a generous free plan with this API. See the RapidAPI listing for all plans and pricing.

McAPI Screenshot API - Specifications

Version:

V1.0

Protocol:

https

URL:

https://mcapi-screenshot.p.rapidapi.com

Endpoint:

/

Method:

POST

McAPI Screenshot API - Sample cURL call

Shown is a cURL request to capture and return a screenshot of the Indiehackers website. The device is set to "Default" which will create a screenshot of 1024x768px. The image is returned as a base64 encoded JPEG (replace YOUR_API_KEY with your RapidAPI key):
curl --request POST \
	--url https://mcapi-screenshot.p.rapidapi.com/ \
	--header 'content-type: application/json' \
	--header 'x-rapidapi-host: mcapi-screenshot.p.rapidapi.com' \
	--header 'x-rapidapi-key: YOUR_API_KEY' \
	--data '{
	  "url": "https://indiehackers.com",
	  "format": "jpeg",
	  "storeExternal": "false",
	  "devices": [ "Default" ]
}'

McAPI Screenshot API - Sample response

Shown is the response from the cURL request above (the returned JPEG is shortened):
{
  "service": "McAPI Screenshot, 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 screenshots

Shown is the returned JPEG from the cURL call above (all screenshots below can be enlarged by clicking, drop shadow and border are not part of the screenshot):

McAPI Screenshot API - Sample Screenshot

Sometimes you will want to see the full length page. To do so, set the fullPage-param to "true". The Indiehackers site again:

McAPI Screenshot API - Sample Screenshot Full Length

Custom sizes are easily specified with the viewPort-param, like so:


...

--data '{
  "url": "https://indiehackers.com",
  "format": "jpeg",
  "storeExternal": "false",
  "viewPort": {"width": 800, "height": 600}
}'

...

The Indiehackers site in 800x600:

McAPI Screenshot API - Sample Screenshot Custom Viewport

Storing screenshots on a cloud server

The storeExternal option controls the screenshot delivery. Set to "false" as above, the screenshots are returned immediately as base64 encoded images. Set it to "true" and the screenshots will be stored on one of our servers for 24 hours; the API call will then return the screenshots' URLs.


...

--data '{
  "url": "https://indiehackers.com",
  "format": "jpeg",
  "storeExternal": "true",
  "devices": [ "Default" ]
}'

...

Returns:

{
  "service": "McAPI Screenshot, https://mcapi.io"
  "version": "V1"
  "url": "https://indiehackers.com",
  "screenshots": [
    {
      "device": "Default",
      "screenshot": "https://...jpeg"
    }
  ]
}

Taking multiple screenshots in batch mode

Capturing batches of screenshots for multiple devices at a time is easy too. Simply list the the device names like so (see below for the listDevices-param which enumerates all known devices):


...

--data '{
  "url": "https://cnbc.com",
  "format": "jpeg",
  "storeExternal": "false",
  "devices": [ "iPhone 12", "iPhone 12 landscape" ]
}'

...

The call will then return two images in the screenshots-array, one rendered for the iPhone 12 in standard orientation, one for landscape, like so:

{
  "service": "McAPI Screenshot, https://mcapi.io"
  "version": "V1"
  "storeExternal": "true",
  "url": "https://cnbc.com",
  "screenshots": [
    {
      "device": "iPhone 12",
      "screenshot": "https://...jpeg"
    },
    {
      "device": "iPhone 12 landscape",
      "screenshot": "https://...jpeg"
    }    
  ]
}

Here's #1, iPhone 12 standard (i.e. portrait orientation):

Screenshot API - Website iPhone 12 Portrait

And this is #2, iPhone 12 landscape:

Screenshot API - Website iPhone 12 Landscape

Automatically accepting cookie consent banners and notices (experimental)

If so desired, the API can also automatically click the "Accept" button on GDPR cookie consent banners (Note that this feature is experimental as of V1.0 and will only work with sites in english.)

Consider this screenshot of the CNBC website with default API settings. The site displays a very prominent banner:

Screenshot API - Cookie Consent Banner

Set the cookie-param to "true" like so:


...

--data '{
  "url": "https://cnbc.com",
  "format": "jpeg",
  "storeExternal": "false",
  "cookie": "true",
  "devices": [ "Default" ]
}'

...

The screenshot now shows the site without the banner.

Screenshot API - Clicked Cookie Banner and Ad

Blocking ads in screenshots

It can be useful to take screenshots with all available ads rendered on the site, for example to check ad placement or ad rotation. For all other instances, the API comes with a built-in ad blocker. Activate it like so:


...

--data '{
  "url": "https://cnbc.com",
  "format": "jpeg",
  "storeExternal": "false",
  "cookie": "true",
  "adblock": "true",
  "devices": [ "Default" ]
}'

...

The website without cookie warning and without ads:

Screenshot API - Clicked Cookie Banner and Ad blocked

McAPI Screenshot API - Reference

Describes parameters for screenshot creation and delivery. All parameters are case-sensitive.

Parameters to control the screenshot creation

  • Name: url

    Description: Url from which to take the screenshot.

    Type: String

    Required: Yes

    Default: n/a

    Sample JSON:

    "url" : "https://mcapi.io"

    Must be a fully qualified url, i.e. including protocol specifiers http:// or https://.

  • Name: fullPage

    Description: Render full page.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "false"

    Sample JSON:

    "fullPage" : "true"

    If set to "false", the height of the returned screenshot will be as specified in the viewPort or devices-params. If set to "true", the height is undefined and depends on the target site.

  • Name: listDevices

    Description: Returns a list of all pre-defined devices and screen sizes.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "false"

    Sample JSON:

    "listDevices" : "true"

    If set to "true", all other parameters from the REST call will be ignored. The API will not create a screenshot, instead it returns an array of the devices like so:

    
    {
      "devices": [
        { "name": "Default", "width": 1024, "height": 768 },
    
        ...
      
        { "name": "iPhone 11", "width": 414, "height": 828 },
        { "name": "iPhone 11 landscape", "width": 828, "height": 414 },
        { "name": "iPhone 11 Pro", "width": 375, "height": 812 },
        { "name": "iPhone 11 Pro landscape", "width": 812, "height": 375 },
        { "name": "iPhone 11 Pro Max", "width": 414, "height": 896 },
        { "name": "iPhone 11 Pro Max landscape", "width": 896, "height": 414 },
        { "name": "iPhone SE II", "width": 375, "height": 667 },
        { "name": "iPhone SE II landscape", "width": 667, "height": 375 },
        { "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 the respective device. For example, for a recent iPhone 12 the string would be:

    Mozilla/5.0 (iPhone; CPU iPhone OS 14_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1 Mobile/15E148 Safari/604.1

  • Name: devices

    Description: Specify devices for which to take screenshots.

    Type: Array of Strings

    Required: No

    Values: One or more of the known devices, see listDevices-param.

    Default: [ "Default" ]

    Sample JSON:

    "devices" : [ "iPhone 11", "iPhone 12"]

    For each device, the API will pretend to the target site to be the respective device, load the page and then take a screenshot. Hence, specifying five devices (the maximum) involves the API loading the same URL five times, see below for discussion if you run into timeouts. If no devices are specified, the API will fall back to a default desktop computer with a resolution of 1024x768 px.

  • Name: viewPort

    Description: Specify screen size for which to take screenshots.

    Type: Dictionary

    Required: No

    Values: Must specify width and height of viewport, both numeric

    Default: n/a

    Sample JSON:

    "viewPort" : { "width": 800, "height": 600 }

    When viewport dimensions are specified, the API will fall back to a standard desktop User Agent. This parameter is ignored if the devices-param is also specified.

  • Name: cookie

    Description: Try to locate cookie consent banner (if any) and auto-click the "Accept"-button.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "false"

    Sample JSON:

    "cookie" : "true"

  • Name: adblock

    Description: Block ads and trackers.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "false"

    Sample JSON:

    "adblock" : "true"

    Based on the Clickz OSS ad blocker. Taking a screenshot takes more time if this feature is activated.

  • Name: stealth

    Description: Work in stealth mode.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "false"

    Sample JSON:

    "stealth" : "true"

    Prevent detection of headless browsing, i.e. without a human, by target site. Taking a screenshot takes more time if this feature is activated.

Parameters to control the screenshot delivery

  • Name: format

    Description: Output data format.

    Type: String

    Required: No

    Values: "png", "jpeg"

    Default: "jpeg"

    Sample JSON:

    "format" : "png"

    Raster formats PNG and JPEG are created with 72dpi resolution.

  • Name: storeExternal

    Description: Store screenshot on server.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "true"

    Sample JSON:

    "storeExternal" : "true"

    Stores the screenshot(s) on a cloud storage maintained by McAPI. When this parameter is set to "true", the API will return the respective URLs in the response instead of the base64-encoded images, e.g.:

    {
      "service":"McAPI Screenshot, https://mcapi.io"
      "version":"V1"
      "url": "https://indiehackers.com",
      "screenshots": [
        {
          "device": "iPhone 12",
          "screenshot": "https://..." 
        },
        {
          "device": "iPhone 12 landscape",
          "screenshot": "https://..." 
        }
      ]
    }
    

    Note: Stored screenshots will be purged automatically after 24 hours.

  • Name: header

    Description: Prepend MIME-type header to base64 string.

    Type: String

    Required: No

    Values: "true" or "false"

    Default: "true"

    Sample JSON:

    "header" : "false"

    Depending on the data format, the following headers will be used:

    • PNG: data:image/png;base64,
    • JPEG: data:image/jpeg;base64,

    As a rule, leave the header in if you plan to inject the returned screenshot image in an HTML DOM or write out img-tags. If you plan to write the screenshot image to a file, set the parameter to false. See the sample code for more on this. This parameter is ignored if storeExternal is set to "true" as downloadable images are always binary and directly usable.

McAPI Screenshot API - Error codes and messages

Upon success, the API returns a status code of 200. With any error, the API will instead return a status code of 400. Also provided is a status text with more information. The following example shows the response for a messed up data package (with the cURL from the introduction we changed the JSON block from "format": "jpeg" to "format: "jpeg"). This will cause the JSON parser in the API's event handler to raise an exception; the handler will then return:

Malformed event parameter

Other error messages:

  • No URL specified.

    url property absent or empty string

  • No known device specified or invalid viewPort argument.

    devices array contains unknown devices or viewPort property malformed

  • More than five devices specified.

    devices array contains more than five devices

  • Can't load page.

    Catch all error for browser-related issues

    This error will be returned if the target server didn't respond or was unreachable, for example if the URL was misspelled or incomplete. Another scenario is related to the cookie option when auto-clicking the "Accept"-button triggers navigation away from the loaded page. This message may contain additional information related to the error.

Timeout scenarios

V1 of the API runs synchronous, i.e. it will only return if all screenshots have been captured. For heavy sites, a single screenshot can take up to 10 seconds, longer if the cookie, stealth and adblock options are activated. Also, storing the screenshot on our cloud storage takes more time than simply returning the images as base64 because the API waits for the server to confirm the successful upload. Consider increasing the respective timeout-parameter on your side for your environment or programming language if you encounter timeouts or implement a simple retry pattern.

On our side, the API itself may simply timeout if an URL takes too long to load (this timeout is currently at 30s). This can be an issue if you have more than one device in the devices array. Consider splitting the calls and take one screenshot at a time.

V2 of the API will introduce an asynchronous mode where the API will return immediately, providing a URL for the caller to check the progress of the operation.

McAPI Screenshot API - Sample code and snippets