Code samples
Choose your favorite language, put in your customer API key and you got it!
#!/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)
API parameters
API is based on HTTP GET request.
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 API 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 percent-encoding is strongly recommended and http(s):// protocol prefix is optional.
|
dimension
|
Size of the web snapshot or webpage 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 - website thumbnail size 320x240 pixels800x600 - website snapshot size 800x600 pixels1024x768 - web screenshot size 1024x768 pixels1920x1080 - webpage screenshot size 1920x1080 pixels1024xfull - full page 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 pixelsdevice=phone and dimension=480x800 - mobile phone screenshot with size 480x800 pixelsdevice=tablet and dimension=800x1280 - tablet screenshot with size 800x1280 pixelsThere 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:
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 |
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 screenshotcacheLimit=1 : use image from cache only if is not older than 1 daycacheLimit=2 : use image from cache only if is not older than 2 daysetc... 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 immediatelydelay=200 : wait 200ms before capturingdelay=400 : wait 400ms before capturingetc... |
zoom
|
Allowed values are: (10 - 400 )Using zoom parameter, you can manage zoom scale of the webpage before screenshot is captured. Default value is 100 percent. This parameter is useful when you want to capture high resolution 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 sizezoom=200 : high resolution screenshot. Final image is 2x bigger than original (zoom=100) screenshot. zoom=50 : half-size screenshot, 50%Because of optimization, zoom parameter is ignored for screenshots smaller than typical device dimension mentioned in device parameter description.
|
click
|
Allowed values: Any valid CSS selector. More info about selectors can be found in CSS Selector Reference. Using click parameter you can trigger the "click" event on any HTML element before webpage is captured as screenshot. Useful for accepting annoying GDPR or cookie banners.Examples:
# character or any others reserved characters.
|
hide
|
Allowed values: Any valid CSS selectors separated by comma. More info about selectors can be found in CSS Selector Reference. Using hide parameter you can hide/remove any HTML element before webpage is captured as screenshot. Useful for hiding various GDPR/cookie banners, popup dialogs or any other web page elements.Examples:
Percent-encoding is strongly recommended, specially while using # character or any others reserved characters.
|
cookies
|
Allowed values: A semicolon [ ; ] separated list of cookies which should be used for screenshot capturing. Each cookie contains a name-value pair. Multiple pairs must be separated by a semicolon. Percent-encoding is required.Example: Cookies data name1=value1;name2=value2 must be encoded into format name1%3Dvalue1%3Bname2%3Dvalue2 .
|
accept-language
|
Sets the Accept-Language header on request to the web page you want to capture. Using this parameter you can capture screenshot of webpage with a specific language. Percent-encoding is required when using reserved characters.Example: en-US
|
user-agent
|
Sets the User-Agent header on request to the web page you want to capture. Using this parameter you can emulate a specific device. Percent-encoding is required when using reserved characters.Example: Mozilla/5.0 (Linux; Android 10; SM-G981B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Mobile Safari/537.36 will emulate Samsung Galaxy S20 mobile phone.
|
selector
|
Allowed values: Any valid CSS selector. More info about selectors can be found in CSS Selector Reference. Using selector parameter you can capture screenshot of single DOM element. Example: table.table:nth-child(3) > tbody:nth-child(2) > tr:nth-child(15)
|
crop
|
Allowed format:x,y,width,height in pixels(px)Using crop parameter you can capture screenshot of the selected region. Example: 100,0,800,300 captures a screenshot of rectangle with dimension width=800px, height=300px and with upper left corner started at position x=100px and y=0px of the viewport.
|
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_key |
Specified customer key is invalid. | |
invalid_url |
Specified URL is invalid or authorization is required (401 Unauthorized status code was sent). See Basic_access_authentication for more info. |
|
missing_key |
Customer key is missing in your request. | |
missing_url |
URL parameter is missing in your request. | |
no_credits |
Your account is exhausted, you need/should to buy more fresh screenshots. | |
invalid_selector |
Specified CSS selector is invalid. | |
invalid_crop |
Specified crop region is invalid. | |
system_error |
Generic system error. |