Website screenshot API code samples


Choose your favorite language, put in your customer key and you got it!

Complete source code is available on GitHub

#!/bin/bash

CUSTOMER_KEY="PUT_YOUR_CUSTOMER_KEY_HERE"
SECRET_PHRASE="" #leave secret phrase empty, if not needed

URL="https://www.google.com"
DIMENSION="1366x768" # or "1366xfull" for full length screenshot
DEVICE="desktop"
FORMAT="png"
CACHE_LIMIT="0"
DELAY="2000"
ZOOM="100"

ARGS=(
--data-urlencode "key=$CUSTOMER_KEY" \
--data-urlencode "dimension=$DIMENSION" \
--data-urlencode "device=$DEVICE" \
--data-urlencode "format=$FORMAT" \
--data-urlencode "cacheLimit=$CACHE_LIMIT" \
--data-urlencode "delay=$DELAY" \
--data-urlencode "zoom=$ZOOM" \
--data-urlencode "url=$URL"
)

if [[ -n "$SECRET_PHRASE" ]]; then
  HASH=$(echo -n $URL$SECRET_PHRASE | md5sum | cut -d ' ' -f 1)
  ARGS+=(--data-urlencode "hash=$HASH")
fi

curl -Gs "https://api.screenshotmachine.com" "${ARGS[@]}" > output.png

Complete source code is available on GitHub


string customerKey = "PUT_YOUR_CUSTOMER_KEY_HERE";
string secretPhrase = ""; //leave secret phrase empty, if not needed

var options = new Dictionary();
// mandatory parameter
options.Add("url", "https://www.google.com");
// all next parameters are optional, see our webtite screenshot API guide for more details
options.Add("dimension", "1366x768"); // or "1366xfull" for full length screenshot
options.Add("device", "desktop");
options.Add("format", "png");
options.Add("cacheLimit", "0");
options.Add("delay", "200");
options.Add("zoom", "100");

ScreenshotMachine sm = new ScreenshotMachine(customerKey, secretPhrase);

string apiUrl = sm.GenerateScreenshotApiUrl(options);
//use final apiUrl where needed
Console.WriteLine(apiUrl);

//or save screenshot directly
string output = "output.png";
new WebClient().DownloadFile(apiUrl, output);
Console.WriteLine("Screenshot saved as " + output);

Complete source code is available on GitHub


String customerKey = "PUT_YOUR_CUSTOMER_KEY_HERE";
String secretPhrase = "";//leave secret phrase empty, if not needed

ScreenshoMachine sm = new ScreenshoMachine(customerKey, secretPhrase);

Map options = new HashMap();
// mandatory parameter
options.put("url", "https://www.google.com");
// all next parameters are optional, see our website screenshot API guide for more details
options.put("dimension", "1366x768"); // or "1366xfull" for full length screenshot
options.put("device", "desktop");
options.put("format", "png");
options.put("cacheLimit", "0");
options.put("delay", "200");
options.put("zoom", "100");

String apiUrl = sm.generateScreenshotApiUrl(options);
// put link to your html code
System.out.println(apiUrl);

// or save screenshot as an image
URLConnection openConnection = new URL(apiUrl).openConnection();
openConnection.addRequestProperty("User-Agent", "Mozilla/4.0");
InputStream in = openConnection.getInputStream();
String output = "out.png";
Files.copy(in, Paths.get(output), StandardCopyOption.REPLACE_EXISTING);
System.out.println("Screenshot saved as " + output);

See our official npm package. Complete source code is available on GitHub.


// npm install screenshotmachine --save

var screenshotmachine = require('screenshotmachine');

var customerKey = 'PUT_YOUR_CUSTOMER_KEY_HERE';
    secretPhrase = ''; //leave secret phrase empty, if not needed
    options = {
      //mandatory parameter
      url : 'https://www.google.com',
      // all next parameters are optional, see our website screenshot API guide for more details
      dimension : '1366xfull', // or "1366xfull" for full length screenshot
      device : 'desktop',
      format: 'png',
      cacheLimit: '0',
      delay: '200',
      zoom: '100'
    }

var apiUrl = screenshotmachine.generateScreenshotApiUrl(customerKey, secretPhrase, options);

//put link to your html code
console.log('<img src="' + apiUrl + '">');

//or save screenshot as an image
var fs = require('fs');
var output = 'output.png';
screenshotmachine.readScreenshot(apiUrl).pipe(fs.createWriteStream(output).on('close', function() {
  console.log('Screenshot saved as ' + output);
}));

Complete source code is available on GitHub


#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use URI::Escape qw(uri_escape);
use Digest::MD5 qw(md5_hex);

my $base_api_url = 'https://api.screenshotmachine.com/?';

my $customer_key = 'PUT_YOUR_CUSTOMER_KEY_HERE';
my $secret_phrase = ''; # leave secret phrase empty, if not needed

my %options;
# mandatory parameter
$options{'url'} = 'https://www.google.com';
# all next parameters are optional, see our website screenshot API guide for more details
$options{'dimension'} = '1366x768'; # or "1366xfull" for full length screenshot
$options{'device'} = 'desktop';
$options{'format'} = 'png';
$options{'cacheLimit'} = '0';
$options{'delay'} = '200';
$options{'zoom'} = '100';

my $api_url = $base_api_url . 'key=' . $customer_key;
if ($secret_phrase ne "")
{
  $api_url .= '&hash=' . md5_hex($options{'url'} . $secret_phrase);
}
foreach my $key (keys %options)
{
  $api_url .= '&' . $key . '=' . uri_escape($options{$key});
}
# put link to your html code
print "<img src=\"" . $api_url . "\">\n";

# or save screenshot as an image
my $lwp = LWP::UserAgent->new(agent=>'perl-client', cookie_jar=>{});
my $output = 'output.png';
my $resp = $lwp->mirror($api_url, $output);
unless($resp->is_success) {
    print $resp->status_line;
}
print "Screenshot saved as " . $output . "\n";

See our official Composer package. Complete source code is available on GitHub


<?php
$customer_key = "PUT_YOUR_CUSTOMER_KEY_HERE";
$secret_phrase = ""; //leave secret phrase empty, if not needed

$machine = new ScreenshotMachine($customer_key, $secret_phrase);

//mandatory parameter
$options['url'] = "https://www.google.com";

// all next parameters are optional, see our website screenshot API guide for more details
$options['dimension'] = "1366x768";  // or "1366xfull" for full length screenshot
$options['device'] = "desktop";
$options['format'] = "png";
$options['cacheLimit'] = "0";
$options['delay'] = "200";
$options['zoom'] = "100";

$api_url = $machine->generate_screenshot_api_url($options);

//put link to your html code
echo '<img src="' . $api_url . '">' . PHP_EOL;

//or save screenshot as an image
$output_file = 'output.png';
file_put_contents($output_file, file_get_contents($api_url));
echo 'Screenshot saved as ' . $output_file . PHP_EOL;

Complete source code is available on GitHub


customer_key = 'PUT_YOUR_CUSTOMER_KEY_HERE'
secret_phrase = '' # leave secret phrase empty, if not needed
options = {
  'url': 'https://www.google.com', # mandatory parameter
  # all next parameters are optional, see our website screenshot API guide for more details
  'dimension': '1366x768', # or "1366xfull" for full length screenshot
  'device': 'desktop',
  'cacheLimit' : '0',
  'delay' : '200',
  'zoom' : '100'
  }

api_url = generate_screenshot_api_url(customer_key, secret_phrase, options)

#put link to your html code
print('<img src="'  + api_url + '">')

#or save screenshot as an image
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', '-')]
urllib.request.install_opener(opener)
output = 'output.png'
urllib.request.urlretrieve(api_url, output)
print('Screenshot saved as ' + output);

Complete source code is available on GitHub, brought to you by Tupalo.com guys. Please see also Gem home page


require 'screenshot_machine'

ScreenshotMachine.configure do |config|
  config.key = '012345abcdefg'
end

website_url = "http://google.com/?q=great+gem"
sm = ScreenshotMachine.new(website_url)
# Returns a binary stream of the file
sm.screenshot

Complete source code is available on GitHub


Dim customerKey As String = "PUT_YOUR_CUSTOMER_KEY_HERE"
Dim secretPhrase As String = "" REM leave secret phrase empty, If Not needed

Dim options As New Dictionary(Of String, String)
REM mandatory parameter
options.Add("url", "https://www.google.com")
REM  all next parameters are optional, see our website screenshot API guide for more details
options.Add("dimension", "1366x768") REM or "1366xfull" for full length screenshot
options.Add("device", "desktop")
options.Add("format", "png")
options.Add("cacheLimit", "0")
options.Add("delay", "200")
options.Add("zoom", "100")

Dim sm As ScreenshotMachine = New ScreenshotMachine(customerKey, secretPhrase)
Dim apiUrl As String = sm.GenerateScreenshotApiUrl(options)

REM use final apiUrl where needed
Console.WriteLine(apiUrl)

REM or save screenshot directly
Dim client As New WebClient()
Dim output As String = "output.png"
client.DownloadFile(apiUrl, output)
Console.WriteLine("Screenshot saved as " + output)

Detailed website screenshot API description


Our website screenshot API is based on HTTP GET requests.

All API calls must start with https://api.screenshotmachine.com/? followed by query parameters (field-value pairs) described in the table below. Parameters are separated by an ampersand (&).

Parameter Description
key Unique customer key is required for using our service. You will get your key after sign up.
url The web page URL you want to capture. Url encoding is recommended and http(s):// protocol prefix is optional.
dimension Size of the thumbnail or screenshot in format [width]x[height]. Default value is 120x90.
width can be any natural number greater than or equals to 100 and smaller or equals to 1920.
height can be any natural number greater than or equals to 100 and smaller or equals to 9999. Also full value is accepted if you want to capture full length webpage screenshot.

Examples:
320x240 - screenshot size 320x240 pixels
800x600 - screenshot size 800x600 pixels
1024x768 - screenshot size 1024x768 pixels
1920x1080 - screenshot size 1920x1080 pixels
1024xfull - full page webpage screenshot with width equals to 1024 pixels (can be pretty long)

Hint
For capturing full length webpage screenshots consider using delay parameter with greater value, for example delay=2000 or more, because some long pages contains more images or fancy animations.
device You can capture the web page using various devices.There are three options available: desktop, phone, tablet. Default value is desktop.

Hint
For capturing screenshots using typical dimensions on the device you can use these combinations of dimension and device parameters:
device=desktop and dimension=1024x768 - desktop screenshot with size 1024x768 pixels
device=phone and dimension=480x800 - mobile phone screenshot with size 480x800 pixels
device=tablet and dimension=800x1280 - tablet screenshot with size 800x1280 pixels

There are a lot of other combinations here. Just choose one, which is best for you.
format Format of the thumbnail or screenshot. Default value is jpg. Available values are: jpg, png, gif
hash If you are calling our service directly from the public HTML pages, we suggest you to safeguard your account with hash parameter. The hash parameter value is calculated using MD5 algorithm from url parameter value and secret phrase.

PHP code example:

$url = "http://www.google.com";
$secret = "TOP SECRET";
$hash = md5($url.$secret);
Result is: ac502de622959ae5f59a6bdc2346771e

Note: Your secret phrase can be set in your account settings and when you set your secret phrase, all requests with missing or incorrect hash parameter will be ignored.

cacheLimit Allowed values are: (0 - 14)

Using cacheLimit parameter, you can manage how old (in days) cached images do you accept. Default value is 14.

Examples:
cacheLimit=0 : never use cache, always download fresh screenshot
cacheLimit=1 : use image from cache only if is not older than 1 day
cacheLimit=2 : use image from cache only if is not older than 2 days
etc...

Hint
If you need shorter interval than one day, you can use decimal numbers as parameter, e.g. cacheLimit=0.041666 means: use image from cache only if is not older than 1 HOUR. (1/24=0.041666)
delay Allowed values are: (0, 200,400, 600, 800, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000)

Using delay parameter, you can manage how long capturing engine should wait before the screenshot is created. Default value is 200. This parameter is useful when you want to capture a webpage with some fancy animation and you want to wait until the animation finish.

Examples:
delay=0 : capture website immediately
delay=200 : wait 200ms before capturing
delay=400 : wait 400ms before capturing
etc...
zoom Allowed values are: (10 - 400)

Using zoom parameter, you can manage zoom scale of the webpage before website screenshot is captured. Default value is 100 percent. This parameter is useful when you want to capture high resolution website screenshot. For example, if you want to capture "retina" website screenshot, set value to 200 or higher.

Examples:
zoom=100 : default zoom factor, original website size
zoom=200 : high resolution website screenshot. Final image is 2x bigger than original (zoom=100) website screenshot.
zoom=50 : half-size website screenshot, 50%

Note
Because of optimization, zoom parameter is ignored for screenshots smaller than typical device dimension mentioned in device parameter description.

Error Handling


Oops, sometimes bad things happens in the universe.

If your API call is invalid or incomplete, you got an error image with text error message. All these error responses also contains our custom HTTP response header field, named X-Screenshotmachine-Response which contains specific error code.

Example:
X-Screenshotmachine-Response: invalid_url

Customers with premium account can upload their custom error images in profile settings.

Error code Description Error image
invalid_hash Provided hash is invalid. invalid hash
invalid_key Specified customer key is invalid. invalid key
invalid_url Specified URL is invalid or authorization is required (401 Unauthorized status code was sent).
See Basic_access_authentication for more info.
invalid url
missing_key Customer key is missing in your request. missing key
missing_url URL parameter is missing in your request. missing url
no_credits Your account is exhausted, you need/should to buy more fresh screenshots. no credits
system_error Generic system error. system error