API Documentation

Not a developer?

We can write custom code for you. Send us an e-mail detailing your needs for a quote.

Current API version: 1.31

Use of the API requires authentication with your API key. Your key is displayed in the right column in your dashboard. If you do not yet have an account, please register for a free account.

Add key=<my_api_key> to all requests.

Browshot uses a REST API. Requests can be made with GET or POST commands to https://api.browshot.com/. All server replies are in JSON format.

Valid requests get a 200 OK server response. If the request is malformed, the server replies with a 403 error.

All API updates, library updates, and maintenance windows are announced on our blog, Browshot Service. We recommend that you subscribe to the blog RSS feed to get the latest news.

Libraries

Several open-source libraries are available to interact with the Browshot API in Perl, PHP, Python, Ruby, C#, etc.

You can download the Browshot API specifications in Swagger format.

Command line

You can request screenshots and retrieve thumbnails from the command line on Linux, Mac OS X or BSD using wget, curl, fetch, etc.

Simple API

The simple API is easier to use than the complete API, but it is also slower.

Request

Retrieve real-time screenshots with one request.


Example

Retrieve a screenshot for the page http://mobilito.net/:

https://api.browshot.com/api/v1/simple?url=http://mobilito.net/&instance_id=12&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 1, # print more debug information
);

my ($code, $png) = $browshot->simple(url => 'http://mobilito.net/', cache => 60 * 60 * 24 * 365, instance_id => 12); # 1 year cache, free screenshot
# code above is blocking, it will return when the screenshot finished or failed

if ($code == 200) { # success
	open PNG, "> screenshot.png" or croak "Could not open screenshot.png: $!\n";
	binmode PNG;
	print PNG $png;
	close PNG;
	
	print "Screenshot saved to screenshot.png\n";
}
else {
	print "Screenshot failed!\n";
	# the reason for the error is sent as part of the HTTP response in the X-Error header but it is not exposed by this library
}

# quicker way to save a screenshot
my ($new_code, $file) = $browshot->simple_file(url => 'http://mobilito.net/', file => "mobilito.png", cache => 0, instance_id => 65, screen_width => 1280, screen_height => 1024); # no cache, premium browser
if ($file ne '') {
	print "Screenshot saved to $file\n";
}
else {
	print "The screenshot failed\n";
}

# use the default cache. The previous screenshto will be returned (same parameters) except if the previous failed
($code, $file) = $browshot->simple_file(url => 'http://mobilito.net/', file => "/tmp/mobilito-2.png", instance_id => 65, instance_id => 65, screen_width => 1280, screen_height => 1024, width => 200); # thumbnail
if ($file ne '') {
	print "Screenshot saved to $file\n";
}
else {
	print "The screenshot failed\n";
}

# host a screenshot on S3

($code, $file) = $browshot->simple_file(
	url => 'http://mobilito.net/', 
	file => "/tmp/mobilito-2.png", 
	instance_id => 65, 
	screen_width => 1280,
	screen_height => 1024,
	hosting => 's3',
	hosting_bucket => 'my_bucket',
	hosting_file => 'youtube.png',
	hosting_width => 200 # thumbnail
);

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$data = $browshot->simple(array('url' => 'http://mobilito.net/', 'instance_id' => 12)); # default cache, free screenshot
# code above is blocking, it will return when the screenshot finished or failed

if ($data['code'] == "200") { # success
	$fp = fopen("screenshot.png", 'w');
	fwrite($fp, $data['image']);
	fclose($fp);

	echo "Screenshot saved to screenshot.png\n";
}
else {
	echo "Screenshot failed!\n";
	# the reason for the error is sent as part of the HTTP response in the X-Error header but it is not exposed by this library
}



# quicker way to save a screenshot
$info = $browshot->simple_file('mobilito.png', array('url' => 'http://mobilito.net/', 'cache' => 0, 'instance_id' => 65, 'screen_width' => 1280, 'screen_height' => 1024)); # no cache, premium browser

if ($info['file'] != "") {
  echo sprintf("Screenshot saved to %s\n", $info['file']);
}
else {
  echo "The screenshot failed\n";
}


# use the default cache. The previous screenshto will be returned (same parameters) except if the previous failed
$info = $browshot->simple_file('mobilito-2.png', array('url' => 'http://mobilito.net/', 'instance_id' => 65, 'instance_id' => 65, 'screen_width' => 1280, 'screen_height' => 1024, 'width' => 200)); # thumbnail
if ($info['file'] != "") {
	 echo sprintf("Screenshot saved to %s\n", $info['file']);
}
else {
	echo "The screenshot failed\n";
}

# host a screenshot on S3
$info = $browshot->simple_file('mobilito-2.png', array(
	'url' => 'http://mobilito.net/',  
	'instance_id' => 65, 
	'screen_width' => 1280,
	'screen_height' => 1024,
	'hosting' => 's3',
	'hosting_bucket' => 'my_bucket',
	'hosting_file' => 'youtube.png',
	'hosting_width' => 200 # thumbnail
));


?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')

data = browshot.simple('http://mobilito.net/', {'instance_id': 12}) # default cache, free screenshot
# code above is blocking, it will return when the screenshot finished or failed

if data['code'] == "200": # success
  image = open("screenshot.png", mode='wb')
  image.write(data['png'])
  image.close()
  
  print "Screenshot saved to screenshot.png\n"
else:
  print "Screenshot failed!\n"
  # the reason for the error is sent as part of the HTTP response in the X-Error header but it is not exposed by this library


# quicker way to save a screenshot
info = browshot.simple_file('http://mobilito.net/', 'mobilito.png', { 'cache': 0, 'instance_id': 65, 'screen_width': 1280, 'screen_height': 1024 }) # no cache, premium browser

if info['file'] != "":
  print "Screenshot saved to %s\n" % info['file'];
else:
  print "The screenshot failed\n"


# use the default cache. The previous screenshto will be returned (same parameters) except if the previous failed
info = browshot.simple_file('http://mobilito.net/', 'mobilito-2.png', { 'instance_id': 65, 'instance_id': 65, 'screen_width': 1280, 'screen_height': 1024, 'width': 200 }) # thumbnail
if info['file'] != "":
  print "Screenshot saved to %s\n" % info['file']
else:
  print "The screenshot failed\n"

# host a screenshot on S3
info = browshot.simple_file('http://mobilito.net/','mobilito-3.png',  
{
	'instance_id': 65, 
	'screen_width': 1280,
	'screen_height': 1024,
	'hosting': 's3',
	'hosting_bucket': 'my_bucket',
	'hosting_file': 'mobilito.png',
	'hosting_width': 200 # thumbnail
})

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

data = browshot.simple({ 'url' => 'http://mobilito.net/', 'instance_id' => 12 }) # default cache, free screenshot
# code above is blocking, it will return when the screenshot finished or failed

if (data[:code].to_i == 200)
	File.open("screenshot.png", 'w') {|f| f.write(data[:png]) }

	puts "Screenshot saved to screenshot.png\n"
else
	puts "Screenshot failed!\n"
	# the reason for the error is sent as part of the HTTP response in the X-Error header but it is not exposed by this library
end

# quicker way to save a screenshot
info = browshot.simple_file('mobilito.png', { 'url' => 'http://mobilito.net/', 'cache' => 0, 'instance_id' => 65, 'screen_width' => 1280, 'screen_height' => 1024 }) # no cache, premium browser

if (info[:file] != "")
  print "Screenshot saved to #{info[:file]}\n"
else
  print "The screenshot failed\n"
end

# use the default cache. The previous screenshto will be returned (same parameters) except if the previous failed
info = browshot.simple_file('mobilito-2.png', { 'url' => 'http://mobilito.net/', 'instance_id' => 65, 'instance_id' => 65, 'screen_width' => 1280, 'screen_height' => 1024, 'width' => 200 }) # thumbnail
if (info[:file] != "")
  puts "Screenshot saved to #{info[:file]}\n"
else
  puts "The screenshot failed\n"
end

# host a screenshot on S3
info = browshot.simple_file('mobilito-3.png',  
{
	'url' => 'http://mobilito.net/',
	'instance_id' => 65, 
	'screen_width' => 1280,
	'screen_height' => 1024,
	'hosting' => 's3',
	'hosting_bucket' => 'my_bucket',
	'hosting_file' => 'mobilito.png',
	'hosting_width' => 200 # thumbnail
})

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/
'use strict';

const browshot = require('browshot');
const fs = require("fs");

var client = new browshot('my_api_key');


// default cache, free screenshot
client.simple({ url: 'http://mobilito.net/', instance_id: 12 }, function(result) {
	// it will return when the screenshot finished or failed
	if (result.code == 200) {
		fs.writeFile("screenshot.png", result.data, (err) => {
			if (err) {
				console.log(`Failed to write image to screenshot.png: ${err}`);
			}
			else {
				console.log("Image saved to screenshot.png");
			}
		});
	}
	else {
		console.log("Screenshot failed!");
		// The reason for the error is sent as part of the HTTP response in the X-Error header but it is not exposed by this library.
	}
});

// quicker way to save a screenshot
client.simpleFile('mobilito.png', 
	{ url: 'http://mobilito.net/', cache: 0, instance_id: 65, screen_width: 1280, screen_height: 1024 }, //no cache, premium browser
	function(data) {
		if (data.file != '')
			console.log(`Screenshot saved to ${data.file}`);
		else
			console.log("The screenshot failed");
	}
);

// use the default cache. The previous screenshto will be returned (same parameters) except if the previous failed
client.simpleFile('mobilito-2.png', 
	{ url: 'http://mobilito.net/', instance_id: 65, instance_id: 65, screen_width: 1280, screen_height: 1024, width: 200 }, // thumbnail
	function(data) {
		if (data.file != '')
			console.log(`Screenshot saved to ${data.file}`);
		else
			console.log("The screenshot failed");
	}
);

// host a screenshot on S3
client.simpleFile('mobilito-3.png',  
	{
		url: 'http://mobilito.net/',
		instance_id: 65, 
		screen_width: 1280,
		screen_height: 1024,
		hosting: 's3',
		hosting_bucket: 'my_bucket',
		hosting_file: 'mobilito.png',
		hosting_width: 200 // thumbnail
	}, function(data) {
		if (data.file != '')
			console.log(`Screenshot saved to ${data.file}`);
		else
			console.log("The screenshot failed");
	}
);

Download code sample

Note: make sure you follow all 302/307 HTTP redirections. Since some pages may take 2 minutes to load, Browshot will send redirections to avoid HTTP timeouts.

IMPORTANT: if no instance_id is specified, the free instance #12 is used by default. Remember that you can only do 100 free screenshots per month. To use a premium instance, use instance_id=65 for example.


You can add any of the arguments that are supported by /api/v1/screenshot/create and Thumbnails. For example, to get a 640x480 thumbnail, use:

https://api.browshot.com/api/v1/simple?url=http://mobilito.net/&instance_id=12&width=640&height=480&key=my_api_key

Response

The status of the screenshot is described by the HTTP response code:

  • 200: successful, the response body contains the screenshot or thumbnail (PNG).

  • 404 Not Found: the screenshot could not be performed (page did not load, domain is not reachable, etc.). The response body contains the default image not-found.png. The description of the error is included in the X-Error HTTP response header.

  • 400: the request is invalid. You may have an invalid key, or invalid URL, etc. The description of the error is included in the X-Error HTTP response header.

  • 302: the screenshot is in progress, follow the redirection.

Complete API

Screenshot API

You can request screenshots from a specific instance, query their status and download the screenshots and/or thumbnails.

/api/v1/screenshot/create

Screenshot requests to private and shared instances require a positive balance.



Request

Required parameters:

  • url: URL of the page to get a screenshot for

  • instance_id: instance ID to use



Common parameters:

  • size: screenshot size: "screen" (default) or "page"

  • cache: use a previous screenshot (same URL, same instance) if it was done within <cache_value> seconds. The default value is 24 hours. Specify cache=0 if you want a new screenshot.

  • delay=0-60 (default: 5): number of seconds to wait after the page has loaded. This is used to let JavaScript run longer before taking the screenshot. Use delay=0 to take screenshots faster.

  • screen_width (1-5000): width of the browser window. For desktop browsers only.

  • screen_height (1-10000): height of the browser window. For desktop browsers only. (Note: full-page screenshots can have a height of up to 15,000px)



Optional parameters:

  • hide_popups: hide popups (ads, cookie warning, etc.) on the page

  • dark: run the browser in dark mode - Chrome and Mobile only

  • strict_ssl (default: 0): enable detection of expired certificate, blocked mixed content - Chrome and Mobile only

  • referer ( paid screenshots only): use a custom referrer (see Custom POST Data, Referrer and Cookie)

  • post_data (paid screenshots only): send a POST request with post_data, useful for filling out forms (see Custom POST Data, Referrer and Cookie)

  • cookie (paid screenshots only): set a cookie for the URL requested (see Custom POST Data, Referrer and Cookie) Cookies should be separated by a ;

  • script: URL of javascript file to execute after the page load event.

  • script_inline: Javascript content to execute after the page load event.

  • details=0-3 (default: 0): level of information available with screenshot/info.

  • html=0,1 (default: 0): save the HTML of the rendered page which can be retrieved by the API call screenshot/html, and classify the content of the page. This feature costs 1 credit per screenshot.

  • max_wait=1-60 (default: 0 = disabled): maximum number of seconds to wait before triggering the PageLoad event. Note that delay will still be used.

  • headers: any custom HTTP headers. (Not supported with Internet Explorer)

  • target: a CSS selector. Take a screenshot of an element on the page identified by its CSS selector

  • priority=1-3 (for private instances only): assign priority to the screenshot



Hooks:
You can receive a notification to your own URL when a screenshot is finished or failed. Add this parameter:

  • hook: your URL to receive the notification


When the screenshot is ready (status: finished or error), A POST request is sent to your URL. The body contains the JSON data returned by the API call screenshot/info. In case your URL takes too long to respond or does not return a 20X status code, the request can be retried up to 2 times.


Automation steps
You can create reach interactions with the browser and take multiple screenshots. See our blog post for more information and examples.

  • steps: list of steps in JSON format. See our blog post for more information.


Trackers
You can extract information from the web page such as search rank, prices, delivery dates, page titles, and more. See our blog post for more information and examples.

  • trackers (new 1.28): list of trackers in JSON format. See our blog post for more information.


Hosting:
You can get your screenshots and thumbnails hosted automatically on S3/Browshot/CDN with these additional parameters:

  • hosting: hosting option: s3 or browshot

  • hosting_height (optional): maximum height of the thumbnail to host

  • hosting_width (optional): maximum width of the thumbnail to host

  • hosting_scale (optional): scale of the thumbnail to host

  • hosting_bucket (required for S3): S3 bucket to upload the screenshot or thumbnail

  • hosting_file (optional, for S3 only): file name to use

  • hosting_headers (optional, for S3 only): list of headers to add to the S3 object

  • hosting_private (optional, for S3 only): set the ACL to bucket-owner-full-control instead of public-read


If the screenshot is successful, the thumbnail or screenshot will be automatically hosted, there is no need to call screenshot/host.


The priority is assigned automatically for public and shared instances: 1 for highest, 3 for lowest. Priority is given to accounts with fewer screenshots in the processing state. The ratio of screenshots processed is about 4 priority 1, 2 priority 2, and 1 priority 3 (this may change in the future).


IMPORTANT: Remember that you can only do 100 free screenshots per month. To used a premium instance, use instance_id=65 for example.



Examples

Request

https://api.browshot.com/api/v1/screenshot/create?url=http://www.google.com/&instance_id=12&size=screen&cache=0&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits.
#######################



my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $screenshot = $browshot->screenshot_create(url => 'http://www.google.com/', instance_id => 12, size => 'page'); # all default parameters, instance_id = 12 (free)
# If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
while ($screenshot->{status} ne 'finished' &&  $screenshot->{status} ne 'error') {
	print "Wait...\n";
	sleep 10;
	$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
}

# screenshot is done: finished (sucessful) or error (failed)
if ($screenshot->{status} eq 'error') {
	print "Screenshot failed: ", $screenshot->{error}, "\n"; # display the reason for the error
}
else { # request the thumbnail
	my $image = $browshot->screenshot_thumbnail(id => $screenshot->{id});
	
	# save the screenshot
	open PNG, "> browshot.png" or croak "Cannot open browshot.png: $!\n";
	binmode PNG;
	print PNG $image;
	close PNG;
}


# you can combine several calls into 1: screenshot_create + screenshot_host
$screenshot = $browshot->screenshot_create(
	url 			=> 'https://browshot.com/', 
	instance_id 	=> 24, # premium
	screen_width => 1600, # wide screen
	screen_height => 1200, 
	size => 'page', # full page
	delay => 25, # greater delay if the page si very longer
	hosting => 's3', # make sure you have set up your S3 bucket with the right ACL
	hosting_bucket => 'my_bucket',
	hosting_file => 'myfile.png', # can be omitted
	hosting_width => 400, # thumbnail 400px wide
);


# Make multiple screenshots of the same page (loaded once)
$screenshot = $browshot->screenshot_create(
	url 			=> 'https://youtube.com/', 
	instance_id 	=> 24, # premium
	shots => 5 ,          # 5 screenshots
	shot_interval => 10, # every 10 seconds
	screen_width => 1280,
	screen_height => 1024,
);

sleep 60;

$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
if ($screenshot->{status} eq 'finished') {
	# download the 5 screenshots
	for (my $i = 1; $i <= 5; $i++) {
		$browshot->screenshot_thumbnail_file(id => $screenshot->{id}, height => 600, shot => $i, file => "$i.png");
	}
}


# Host the screenshot on S3
$screenshot = $browshot->screenshot_create(
	url => 'https://youtube.com/', 
	instance_id => 24, # premium
	screen_width => 1280,
	screen_height => 1024,
	hosting => 's3',
	hosting_bucket => 'my_bucket',
	hosting_file => 'youtube.png',
	hosting_width => 600 # thumbnail
);

sleep 60;

$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
if ($screenshot->{status} eq 'finished') {
	# The screenshot may not be hosted yet
	if (exists($screenshot->{hosted_url}) && $screenshot->{hosted_url} ne '') {
		print "\nScreenshot hosted at ", $screenshot->{hosted_url}, "\n";
	}
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$screenshot = $browshot->screenshot_create(array('url' => 'http://www.google.com/', 'instance_id' => 12, 'size' => 'page')); # all default parameters, instance_id = 12 (free)
# If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
while ($screenshot->{'status'} != 'finished' &&  $screenshot->{'status'} != 'error') {
	echo "Wait...\n";
	sleep(10);
	$screenshot = $browshot->screenshot_info($screenshot->{'id'});
}

# screenshot is done: finished (sucessful) or error (failed)
if ($screenshot->{'status'} == 'error') {
	echo sprintf("Screenshot failed: %s\n", $screenshot->{'error'}); # display the reason for the error
}
else { # request the thumbnail
	$image = $browshot->screenshot_thumbnail($screenshot->{'id'});
	
	# save the screenshot
	$fp = fopen("browshot.png", 'w');
	fwrite($fp, $image);
	fclose($fp);
	
	echo "Screenshot saved to browshot.png\n";
}


# you can combine several calls into 1: screenshot_create + screenshot_host
$screenshot = $browshot->screenshot_create(array(
	'url' 			=> 'https://browshot.com/', 
	'instance_id' 	=> 24, # premium
	'screen_width' => 1600, # wide screen
	'screen_height' => 1200, 
	'size' => 'page', # full page
	'delay' => 25, # greater delay if the page si very longer
	'hosting' => 's3', # make sure you have set up your S3 bucket with the right ACL
	'hosting_bucket' => 'my_bucket',
	'hosting_file' => 'myfile.png', # can be omitted
	'hosting_width' => 400, # thumbnail 400px wide
));


# Make multiple screenshots of the same page (loaded once)
$screenshot = $browshot->screenshot_create(array(
	'url' 			=> 'https://youtube.com/', 
	'instance_id' 	=> 24, # premium
	'shots' => 5 ,          # 5 screenshots
	'shot_interval' => 10, # every 10 seconds
	'screen_width' => 1280,
	'screen_height' => 1024,
));

sleep(60);

$screenshot = $browshot->screenshot_info($screenshot->{'id'});
if ($screenshot->{'status'} == 'finished') {
	# download the 5 screenshots
	for ($i = 1; $i <= 5; $i++) {
		$browshot->screenshot_thumbnail_file($screenshot->{'id'}, "$i.png", array('height' => 600, 'shot' => $i));
	}
}


# Host the screenshot on S3
$screenshot = $browshot->screenshot_create(array(
	'url' => 'https://youtube.com/', 
	'instance_id' => 24, # premium
	'screen_width' => 1280,
	'screen_height' => 1024,
	'hosting' => 's3',
	'hosting_bucket' => 'my_bucket',
	'hosting_file' => 'youtube.png',
	'hosting_width' => 600 # thumbnail
));

sleep(60);

$screenshot = $browshot->screenshot_info($screenshot->{'id'});
if ($screenshot->{'status'} == 'finished') {
	# The screenshot may not be hosted yet
	if (array_key_exists('hosted_url', $screenshot) && $screenshot->{'hosted_url'} != '') {
		echo sprintf("\nScreenshot hosted at %s\n", $screenshot->{'hosted_url'});
	}
}
?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')

screenshot = browshot.screenshot_create('http://www.google.com/', { 'instance_id': 12, 'size': 'page' }) # all default parameters, instance_id = 12 (free)

# If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
while screenshot['status'] != 'finished' and  screenshot['status'] != 'error':
  print "Wait...\n"
  time.sleep(10)
  screenshot = browshot.screenshot_info(screenshot['id'])


# screenshot is done: finished (sucessful) or error (failed)
if screenshot['status'] == 'error':
  print "Screenshot failed: %s\n" % screenshot['error'] # display the reason for the error
else: # request the thumbnail
  image = browshot.screenshot_thumbnail(screenshot['id'])
  
  # save the screenshot
  fp = open("browshot.png", mode='wb')
  fp.write(image)
  fp.close()


# you can combine several calls into 1: screenshot_create + screenshot_host
screenshot = browshot.screenshot_create('https://browshot.com/',
{
	'instance_id': 24, # premium
	'screen_width': 1600, # wide screen
	'screen_height': 1200, 
	'size': 'page', # full page
	'delay': 25, # greater delay if the page si very longer
	'hosting': 's3', # make sure you have set up your S3 bucket with the right ACL
	'hosting_bucket': 'my_bucket',
	'hosting_file': 'myfile.png', # can be omitted
	'hosting_width': 400, # thumbnail 400px wide
})


# Make multiple screenshots of the same page (loaded once)
screenshot = browshot.screenshot_create('https://youtube.com/', 
{
	'instance_id': 24, # premium
	'shots': 5 ,          # 5 screenshots
	'shot_interval': 10, # every 10 seconds
	'screen_width': 1280,
	'screen_height': 1024,
})

time.sleep(60)

screenshot = browshot.screenshot_info(screenshot['id'])
if screenshot['status'] == 'finished':
  # download the 5 screenshots
  for i in range (1, 5):
    browshot.screenshot_thumbnail_file(screenshot['id'], "%d.png" % i, { 'height': 600, 'shot': i })


# Host the screenshot on S3
screenshot = browshot.screenshot_create('https://youtube.com/',
{
	'instance_id': 24, # premium
	'screen_width': 1280,
	'screen_height': 1024,
	'hosting': 's3',
	'hosting_bucket': 'my_bucket',
	'hosting_file': 'youtube.png',
	'hosting_width': 600 # thumbnail
})

time.sleep(60)

screenshot = browshot.screenshot_info(screenshot['id'])
if screenshot['status'] == 'finished':
  # The screenshot may not be hosted yet
  if 'hosted_url' in screenshot and screenshot['hosted_url'] != '':
    print "\nScreenshot hosted at %s\n" % screenshot['hosted_url']

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

screenshot = browshot.screenshot_create('http://www.google.com/', { 'instance_id' => 12, 'size' => 'page' }) # all default parameters, instance_id = 12 (free)

# If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
while (screenshot['status'] != 'finished' &&  screenshot['status'] != 'error')
  puts "Wait (#{screenshot['status']})...\n"
  sleep(10)
  screenshot = browshot.screenshot_info(screenshot['id'])
end


# screenshot is done: finished (sucessful) or error (failed)
if (screenshot['status'] == 'error')
  puts "Screenshot failed: #{screenshot['error']}\n"  # display the reason for the error
else # request the thumbnail
  image = browshot.screenshot_thumbnail(screenshot['id'])
  
  # save the screenshot
  File.open("browshot.png", 'w') {|f| f.write(image) }
end

# you can combine several calls into 1: screenshot_create + screenshot_host
screenshot = browshot.screenshot_create('https://browshot.com/',
{
	'instance_id' => 24, # premium
	'screen_width' => 1600, # wide screen
	'screen_height' => 1200, 
	'size' => 'page', # full page
	'delay' => 25, # greater delay if the page si very longer
	'hosting' => 's3', # make sure you have set up your S3 bucket with the right ACL
	'hosting_bucket' => 'my_bucket',
	'hosting_file' => 'myfile.png', # can be omitted
	'hosting_width' => 400, # thumbnail 400px wide
})


# Make multiple screenshots of the same page (loaded once)
screenshot = browshot.screenshot_create('https://youtube.com/',
{
	'instance_id' => 24, # premium
	'shots' => 5 ,          # 5 screenshots
	'shot_interval' => 10, # every 10 seconds
	'screen_width' => 1280,
	'screen_height' => 1024,
})

sleep(60)

screenshot = browshot.screenshot_info(screenshot['id'])
if (screenshot['status'] == 'finished')
  # download the 5 screenshots
  for i in 1..5
    browshot.screenshot_thumbnail_file(screenshot['id'], "#{i}.png" , { 'height' => 600, 'shot' => i })
   end
end


# Host the screenshot on S3
screenshot = browshot.screenshot_create('https://youtube.com/',
{
	'instance_id' => 24, # premium
	'screen_width' => 1280,
	'screen_height' => 1024,
	'hosting' => 's3',
	'hosting_bucket' => 'my_bucket',
	'hosting_file' => 'youtube.png',
	'hosting_width' => 600 # thumbnail
})

sleep(60)

screenshot = browshot.screenshot_info(screenshot['id'])
if (screenshot['status'] == 'finished')
  # The screenshot may not be hosted yet
  if (screenshot.key?('hosted_url') && screenshot['hosted_url'] != '')
    puts "\nScreenshot hosted at #{screenshot['hosted_url']}\n"
  end
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/

const browshot = require('browshot');
const fs = require("fs");

var client = new browshot('my_api_key');

var interval;

// all default parameters, instance_id = 12 (free)
client.screenshotCreate(
	{url: 'http://www.google.com/', instance_id: 12, size: 'page' }, 
	function(screenshot) {
		// If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
		if (screenshot.status == 'error') {
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			screenshotFinished(screenshot);
		}
		else {
			interval = setInterval(checkScreenshot, 1000 * 10, screenshot.id);
		}
	}
);


function checkScreenshot(id) {
	client.screenshotInfo(id, { }, function(screenshot) {
		if (screenshot.status == 'error') {
			clearInterval(interval);
			
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			clearInterval(interval);
			
			screenshotFinished(screenshot);
		}
		else {
			console.log(`Waiting for screenshot #${screenshot.id} to finish...`);
		}
	});
}

function screenshotFinished(screenshot) {
	// request the thumbnail
	client.screenshotThumbnail(screenshot.id, { }, function(image) {
		fs.writeFile("browshot.png", image, (err) => {
			if (err) {
				console.log(`Failed to write image to browshot.png: ${err}`);
			}
			else {
				console.log("Image saved to browshot.png");
			}
		});
	});
}

// you can combine several calls into 1: screenshot_create + screenshot_host
client.screenshotCreate({
		url: 'https://browshot.com/',
		instance_id: 24, // premium
		screen_width: 1600, // wide screen
		screen_height: 1200, 
		size: 'page', // full page
		delay: 25, // greater delay if the page si very longer
		hosting: 's3', // make sure you have set up your S3 bucket with the right ACL
		hosting_bucket: 'my_bucket',
		hosting_file: 'myfile.png', // can be omitted
		hosting_width: 400, // thumbnail 400px wide
	}, function() {});


// Make multiple screenshots of the same page (loaded once)
client.screenshotCreate({
		url: 'https://youtube.com/',
		instance_id: 24, 		// premium
		shots: 5 ,          // 5 screenshots
		shot_interval: 10, // every 10 seconds
		screen_width: 1280,
		screen_height: 1024,
	}, function() { });

Download code sample


Response:
{
  "error": "Wrong URL format",
  "status": "error",
  "priority": 1,
  "cost": 0
}
{
  "error": "No free screenshots available",
  "status": "error",
  "priority": 1,
  "cost": 0
}
{
  "id": 12589,
  "status": "in_queue",
  "priority": 2
 }
{
  "id": 12589,
  "status": "finished",
  "screenshot_url": "https://www.browshot.com/screenshot/image/12589?scale=1&key=my_api_key",
  "priority": 3,
  "url": "http://www.google.com/",
  "size": "screen",
  "width": 1024,
  "height": 768,
  "request_time": 1312106111,
  "started": 1312258803994,
  "load": 1312258829461,
  "content": 1312258829661,
  "finished": 1312258829681,
  "instance_id": 12,
  "response_code": 200,
  "final_url": "http://www.google.com/",
  "content_type":"text/html",
  "scale": "1",
  "cost": 0,
  "referer": "http://www.google.com/",
  "post_data": "",
  "cookie": "",
  "delay": 5,
  "script": "",
  "shared_url": "",
  "details": 2,
  "shots": 1,
  "shot_interval": 5
}


  • id: screenshot ID

  • status: status of the request: "in_queue", "processing", "finished", "error"

  • screenshot_url: URL to download the screenshot

  • priority: priority given to the screenshot: high (1) to low (3)

  • url: original URL requested

  • size: screenshot size requested

  • instance_id instance ID used for the screenshot

  • cost: number of credits spent for the screenshot

  • delay: number of seconds to wait after page load

  • details=0-3 (optional, default: 0): level of details about the screenshot and the page



If details=1, additional information is sent:


  • error: description of the problem that occurred

  • final_url: URL of the screenshot (redirections can occur)

  • width: screenshot width

  • height: screenshot height

  • scale: image scale. Always 1 for desktop browsers; mobiles may change the scale (zoom in or zoom out) to fit the page on the screen

  • response_code: HTTP response code for the main page (200, 404, 403, etc.)

  • content_type: content-type sent by the server (text/html, text/plain, image/jpeg, etc.)

  • referer: custom referrer used (see Custom POST Data, Referrer and Cookie)

  • post_data: POST data sent (see Custom POST Data, Referrer and Cookie)

  • cookie: custom cookie used (see Custom POST Data, Referrer and Cookie)

  • script: URL of optional javascript file executed after the page load event

  • hosting: optional S3 and webhook details

  • shared_url: if the screenshot was shared, show the public URL



If details=2, additional information is sent:


  • started: time of processing (UNIX timestamp)

  • finished: time of screenshot completed (UNIX timestamp)

  • load: time the page was loaded (UNIX timestamp, 0 if unknown)

  • request_time: time of request (UNIX timestamp) for the time of request

  • content: time the content was loaded (UNIX timestamp, 0 if unknown)



If details=3, and screenshot/create included details=3, additional information is sent:


  • images: list of absolute URLs of images included on the page

  • scripts: list of absolute URLs of external scripts included on the page

  • stylesheets: list of absolute URLs of external style sheets included on the page

  • embeds: list of absolute URLs of embed included on the page

  • applets: list of absolute URLs of applets included on the page

  • iframes: list of absolute URLs of frames included on the page

  • links: list of absolute URLs of links (a tag) included on the page



/api/v1/screenshot/multiple

Request multiple screenshots in one API call.



Request

Parameters:

  • url: URL of the page to get a screenshot for. You can specify multiple url parameters (up to 10).

  • instance_id (optional, default: 12): instance ID to use. You can specify multiple instance_id parameters (up to 10).



The API call accepts all the parameters supported by screenshot/create.

You can specify up to 10 URLs and 10 instances for a total of 100 screenshots in one API call.



Examples

Request screenshots for 2 URLs with one instance:

https://api.browshot.com/api/v1/screenshot/multiple?url=http://www.google.com/&url=http://www.google.com/&instance_id=65&key=my_api_key

Request screenshots for 2 URLs with 2 instances (4 screenshots in total):

https://api.browshot.com/api/v1/screenshot/multiple?url=http://www.google.com/&url=http://www.google.com/&instance_id=65&instance_id=22&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 1, # print more debug information
);

my $list = $browshot->screenshot_multiple(
	urls => ['http://www.google.com/', 'https://browshot.com/', 'http://mobilito.net/'], # up to 5 URLs
	instances => [12, 24, 72], # up to 10
	size => 'page', # all options of screenshot/create are valid
);


my @ids = (); # will hold all screenshot IDs

foreach my $id (keys %$list) {
	push(@ids, $id);
}

sleep 20;


while (scalar @ids > 0) { # go through each screenshot
	my $i = 0;
	while ($i < scalar @ids) {
		my $id = $ids[$i];

		my $info = $browshot->screenshot_info(id => $id);
		if ($info->{status} eq 'finished') {
			$browshot->screenshot_thumbnail_file(id => $id, file => "$id.png");
			splice(@ids, $i, 1); # remove ID from the list
		}
		elsif ($info->{status} eq 'error') {
			print "Screenshot failed: ", $info->{error}, "\n";
			print "\tURL: ", $info->{url}, "\n";
			print "\tinstance_id: ", $info->{instance_id}, "\n";
			print "\n";
			
			splice(@ids, $i, 1); # remove ID from the list
		}
		else {
			# wait
			$i++;
		}
	}
	
	sleep 10 if (scalar @ids > 0);
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################


require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key', 1); # more debug information


$list = $browshot->screenshot_multiple(array('http://www.google.com/', 'https://browshot.com/', 'http://mobilito.net/'), # up to 5 URLs
	array(12, 24, 72), # up to 10
	array('size' => 'page') # all options of screenshot/create are valid
);


$ids = array(); # will hold all screenshot IDs

foreach ($list as $id => $screenshot) {
	array_push($ids, $id);
}

sleep(20);


while (count($ids) > 0) { # go through each screenshot
	$i = 0;
	while ($i < count($ids)) {
		$id = $ids[$i];

		$info = $browshot->screenshot_info($id);
		if ($info->{'status'} == 'finished') {
			$browshot->screenshot_thumbnail_file($id, "$id.png");
			array_splice($ids, $i, 1); # remove ID from the list
		}
		elseif ($info->{'status'} == 'error') {
			echo sprintf("Screenshot failed: %s\n", $info->{'error'});
			echo printf("\tURL: %s\n", $info->{'url'});
			echo printf("\tinstance_id: %s\n", $info->{'instance_id'});
			echo "\n";
			
			array_splice($ids, $i, 1); # remove ID from the list
		}
		else {
			# wait
			$i++;
		}
	}
	
	if (count($ids) > 0)
		sleep(10);
}

?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key', 1) # more debug information


list = browshot.screenshot_multiple({ 'urls': ['http://www.google.com/', 'https://browshot.com/', 'http://mobilito.net/'], 'instances': [12, 24, 72], 'size': 'page' }) # up to 5 URLs

time.sleep(20)
ids = list.keys() #  hold all screenshot IDs


while len(ids) > 0: # go through each screenshot
  i = 0
  while i < len(ids):
    id = ids[i]
    
    info = browshot.screenshot_info(id)
    if info['status'] == 'finished':
      browshot.screenshot_thumbnail_file(id, "%s.png" % id)
      del ids[i] # remove ID from the list
    elif info['status'] == 'error':
      print "Screenshot failed: %s\n" % info['error']
      print "\tURL: %s\n", info['url']
      print "\tinstance_id: %s\n" % info['instance_id']
      print "\n"
      
      del ids[i] # remove ID from the list
    else:
      # wait
      i += 1
  
  
  if len(ids) > 0:
    time.sleep(10)

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key', true) # more debug information


list = browshot.screenshot_multiple({ 'urls' => ['http://www.google.com/', 'https://browshot.com/', 'http://mobilito.net/'], 'instances' => [12, 24, 72], 'size' => 'page' }) # up to 5 URLs

sleep(20)
ids = list.keys() #  hold all screenshot IDs


while (ids.count() > 0) # go through each screenshot
  i = 0
  while (i < ids.count())
    id = ids[i]
    
    info = browshot.screenshot_info(id)
    if (info['status'] == 'finished')
      browshot.screenshot_thumbnail_file(id, "#{id}.png")
      ids.delete_at(i) # remove ID from the list
    elsif (info['status'] == 'error')
      puts "Screenshot failed: #{info['error']}\n"
      puts "\tURL: #{info['url']}\n"
      puts "\tinstance_id: #{info['instance_id']}\n"
      puts "\n"
      
      ids.delete_at(i) # remove ID from the list
    else
      # wait
      i += 1
    end
  end
  
  if (ids.count() > 0)
    sleep(10)
  end
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/
'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

// up to 5 URLs
client.screenshotMultiple(
	{ urls: ['http://www.google.com/', 'https://browshot.com/', 'http://mobilito.net/'], instances: [12, 24, 72], size: 'page' },
	function(list) {
		for(var i in list) {
			console.log(`Screenshot ID: ${list[i].id}: ${list[i].status}`);
		}
	}
);

Download code sample


Response

The response format is the same as returned by screenshot/list.




/api/v1/screenshot/info (updated 1.31)

Once a screenshot has been requested, its status must be checked until it is either "error" or "finished".



Request

Parameters:

  • id: screenshot ID received from /api/v1/screenshot/create

  • details=0-3 (optional, default: 0): level of details about the screenshot and the page.



Example

https://api.browshot.com/api/v1/screenshot/info?id=12589&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $screenshot = $browshot->screenshot_create(url => 'https://browshot.com/', details => 3, instance => 24, screen_width => 1280, screen_height => 1024); # extra details
# the call to screenshot/create sends the same response as screenshot/information
# so screenshot/create and screenshot/info can be interchanged as long as the cache value is long enough
while ($screenshot->{status} ne 'finished' &&  $screenshot->{status} ne 'error') {
	print "Wait...\n";
	sleep 10;
	$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
	# or $screenshot = $browshot->screenshot_create(url => 'https://browshot.com/', details => 3, instance => 24, screen_width => 1280, screen_height => 1024);
}

# screenshot is done: finished (sucessful) or error (failed)
if ($screenshot->{status} eq 'error') {
	print "Screenshot failed: ", $screenshot->{error}, "\n"; # display the reason for the error
	
	# If you call $browshot->screenshot_create with the same parameters, a new screenshot will be requested.
}
else { # screenshot is finished
	# did the page load (200 OK) or was mnissing (404 Not Found) or some error (40X, 50X);
	if ($screenshot->{response_code} != 200) {
		print "The page may not have be reached, HTTP response code was: ", $screenshot->{response_code}, "\n";
	}
	
	# Was it an HTML page, PDF or image?
	if ($screenshot->{content_type} ne 'text/html') {
		print "The page is not HTML, it is ", $screenshot->{content_type}, "\n";
	}
	
	# with details = 3, you can check what asserts were loaded on the page: images, javascript, frames, etc.
	print "There are ", scalar(@{ $screenshot->{images} }), " images on this page:\n";
	foreach my $url (@{ $screenshot->{images} }) {
		print "$url\n";
	}
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key', 1); # more debug information



$screenshot = $browshot->screenshot_create(array('url' => 'https://browshot.com/', 'details' => 3, 'instance' => 24, 'screen_width' => 1280, 'screen_height' => 1024)); # extra details
# the call to screenshot/create sends the same response as screenshot/information
# so screenshot/create and screenshot/info can be interchanged as long as the cache value is long enough
while ($screenshot->{'status'} != 'finished' &&  $screenshot->{'status'} != 'error') {
	echo "Wait...\n";
	sleep(10);
	$screenshot = $browshot->screenshot_info($screenshot->{'id'}, array('details' => 3));
	# or $screenshot = $browshot->screenshot_create(array('url' => 'https://browshot.com/', 'details' => 3, 'instance' => 24, 'screen_width' => 1280, 'screen_height' => 1024));
}

# screenshot is done: finished (sucessful) or error (failed)
if ($screenshot->{'status'} == 'error') {
	echo sprintf("Screenshot failed: %s\n", $screenshot->{'error'}); # display the reason for the error
	
	# If you call $browshot->screenshot_create with the same parameters, a new screenshot will be requested.
}
else { # screenshot is finished
	# did the page load (200 OK) or was mnissing (404 Not Found) or some error (40X, 50X);
	if ($screenshot->{'response_code'} != 200) {
		echo sprintf("The page may not have be reached, HTTP response code was: %s\n", $screenshot->{'response_code'});
	}
	
	# Was it an HTML page, PDF or image?
	if ($screenshot->{'content_type'} != 'text/html') {
		echo sprintf("The page is not HTML, it is %s\n", $screenshot->{'content_type'});
	}
	
	# with details = 3, you can check what asserts were loaded on the page: images, javascript, frames, etc.
	echo sprintf("There are %d images on this page:\n", count($screenshot->{'images'}));
	foreach ($screenshot->{'images'} as $url) {
		echo "$url\n";
	}
}

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key', 1) # more debug information


screenshot = browshot.screenshot_create('https://browshot.com/', { 'details': 3, 'instance': 24, 'screen_width': 1280, 'screen_height': 1024 }) # extra details
# the call to screenshot/create sends the same response as screenshot/information
# so screenshot/create and screenshot/info can be interchanged as long as the cache value is long enough
while screenshot['status'] != 'finished' and  screenshot['status'] != 'error':
  print "Wait...\n"
  time.sleep(10)
  screenshot = browshot.screenshot_info(screenshot['id'], { 'details': 3 })
  # or $screenshot = $browshot->screenshot_create(array('url' => 'https://browshot.com/', 'details' => 3, 'instance' => 24, 'screen_width' => 1280, 'screen_height' => 1024));

# screenshot is done: finished (sucessful) or error (failed)
if screenshot['status'] == 'error':
  print "Screenshot failed: %s\n" % screenshot['error'] # display the reason for the error
  
  # If you call $browshot->screenshot_create with the same parameters, a new screenshot will be requested.
else: # screenshot is finished
  # did the page load (200 OK) or was mnissing (404 Not Found) or some error (40X, 50X);
  if screenshot['response_code'] != 200:
    print "The page may not have be reached, HTTP response code was: %s\n" % screenshot['response_code']
  
  # Was it an HTML page, PDF or image?
  if screenshot['content_type'] != 'text/html':
    print "The page is not HTML, it is %s\n" % screenshot['content_type']
  
  # with details = 3, you can check what asserts were loaded on the page: images, javascript, frames, etc.
  if 'images' in screenshot and isinstance(screenshot['images'], list):
    print "There are %d images on this page:\n" % len(screenshot['images'])
    for url in screenshot['images']:
      print "%s\n" % url

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key', true) # more debug information


screenshot = browshot.screenshot_create('https://browshot.com/', { 'details' => 3, 'instance' => 24, 'screen_width' => 1280, 'screen_height' => 1024 }) # extra details
# the call to screenshot/create sends the same response as screenshot/information
# so screenshot/create and screenshot/info can be interchanged as long as the cache value is long enough
while (screenshot['status'] != 'finished' && screenshot['status'] != 'error')
  puts "Wait...\n"
  sleep(10)
  screenshot = browshot.screenshot_info(screenshot['id'], { 'details' => 3 })
  # or $screenshot = $browshot->screenshot_create(array('url' => 'https://browshot.com/', 'details' => 3, 'instance' => 24, 'screen_width' => 1280, 'screen_height' => 1024));
end

# screenshot is done: finished (sucessful) or error (failed)
if (screenshot['status'] == 'error')
  puts "Screenshot failed: #{screenshot['error']}\n" # display the reason for the error

  # If you call $browshot->screenshot_create with the same parameters, a new screenshot will be requested.
else # screenshot is finished
  # did the page load (200 OK) or was mnissing (404 Not Found) or some error (40X, 50X);
  if (screenshot['response_code'].to_i != 200)
    puts "The page may not have be reached, HTTP response code was: #{screenshot['response_code']}\n"
  end
  
  # Was it an HTML page, PDF or image?
  if (screenshot['content_type'] != 'text/html')
    puts "The page is not HTML, it is #{screenshot['content_type']}\n"
  end
  
  # with details = 3, you can check what asserts were loaded on the page: images, javascript, frames, etc.
  if (screenshot.key?('images') && screenshot['images'].kind_of?(Array))
    puts "There are #{screenshot['images'].count} images on this page:\n"
    
    screenshot['images'].each { |url|
      puts "#{url}\n"
    }
  end
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/
'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

var interval;

// the call to screenshot/create sends the same response as screenshot/info
// so screenshot/create and screenshot/info can be interchanged as long as the cache value is long enough
client.screenshotCreate(
  // additional details
	{url: 'https://browshot.com/', instance_id: 24, size: 'page', details: 3, screen_width: 1280, screen_height: 1024}, 
	function(screenshot) {
		// If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
		if (screenshot.status == 'error') {
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			screenshotFinished(screenshot);
		}
		else {
			interval = setInterval(checkScreenshot, 1000 * 10, screenshot.id);
		}
	}
);

function checkScreenshot(id) {
	client.screenshotInfo(id, { details: 3 }, function(screenshot) {
		if (screenshot.status == 'error') {
			clearInterval(interval);
			
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			clearInterval(interval);
			
			screenshotFinished(screenshot);
		}
		else {
			console.log(`Waiting for screenshot #${screenshot.id} to finish...`);
		}
	});
}

function screenshotFinished(screenshot) {
	// Did the page load (200 OK) or was mnissing (404 Not Found) or some error (40X, 50X);
	if (screenshot.response_code != 200) {
		console.log(`The page may not have be reached, HTTP response code was: ${screenshot.response_code}`);
	}
	
	// Was it an HTML page, PDF or image?
	if (screenshot.content_type != 'text/html') {
    console.log(`The page is not HTML, it is ${screenshot.content_type}`);
  }
  
  // with details = 3, you can check what asserts were loaded on the page: images, javascript, frames, etc.
  if (screenshot.hasOwnProperty('images')) {
		console.log(`There are ${screenshot.images.length} images on this page:`);
		
		for(var i in screenshot.images) {
			console.log("\t" + screenshot.images[i]);
		}
  }
}

Download code sample


Response

{
	  "id": 12589,
	  "status": "error",
	  "screenshot_url": "https://www.browshot.com/screenshot/image/12589?scale=1&key=my_api_key",
	  "priority": 2,
	  "url": "http://www.google.com/",
	  "size": "screen",
	  "width": 1024,
	  "height": 768,
	  "request_time": 1312106111,
	  "started": 1312258803994,
	  "load": "0",
	  "content": 0,
	  "finished": 1312258829681,
	  "instance_id": 12,
	  "response_code": "",
	  "final_url": "",
	  "content_type":"",
	  "scale":1,
	  "cost": 0,
	  "referer": "",
	  "post_data": "",
	  "cookie: "",
	  "delay": 5,
	  "script": "",
	  "shared_url": "",
	  "details": 2
	  }
{
	  "id": 12589,
	  "status": "error",
	  "screenshot_url": "",
	  "priority": 3
	  }
{
	  "id": 12589,
	  "status": "finished",
	  "screenshot_url": "https://browshot.com/screenshot/image/15/12589?scale=1&key=my_api_key",
	  "priority": 12,
	  "url": "http://www.google.com/",
	  "size": "screen",
	  "width": 1024,
	  "height": 768,
	  "request_time": 1312106111,
	  "started": 1312258803994,
	  "load": 1312258829461,
	  "content": 1312258829661,
	  "finished": 1312258829681,
	  "instance_id": 12,
	  "response_code": 200,
	  "final_url": "http://www.google.com/",
	  "content_type":"text/html",
	  "scale": "1",
	  "cost": 0,
	  "referer": "",
	  "post_data": "foo=bar",
	  "cookie": "",
	  "delay": 5,
	  "script": "",
	  "shared_url": "",
	  "details": 2
	  }
{
	  "id": 12589,
	  "status": "in_queue",
	  "screenshot_url": "",
	  "cost": 0
	  }


  • id: screenshot ID

  • status: status of the request: "in_queue", "processing", "finished", "error"

  • screenshot_url: URL to download the screenshot

  • priority: priority given to the screenshot: high (1) to low (3)

  • url: original URL requested

  • size: screenshot size requested

  • instance_id instance ID used for the screenshot

  • cost: number of credits spent for the screenshot

  • delay: number of seconds to wait after page load

  • details: level of details about the screenshot and the page

  • shots: number of screenshots taken. This may not be accurate until the screenshot is finished



If details=1, additional information is sent:


  • error: description of the problem that occurred

  • final_url: last URL (redirections can occur)

  • final_urls: list of URLs taken at each screenshot. See automation steps to learn how to take multiple screenshots.

  • width: screenshot width

  • height: screenshot height

  • scale: image scale. Always 1 for desktop browsers; mobiles may change the scale (zoom in or zoom out) to fit the page on the screen

  • response_code: HTTP response code for the main page (200, 404, 403, etc.)

  • content_type: content-type sent by the server (text/html, text/plain, image/jpeg, etc.)

  • referer: custom referrer used (see Custom POST Data, Referrer and Cookie)

  • post_data: POST data sent (see Custom POST Data, Referrer and Cookie)

  • cookie: custom cookie used (see Custom POST Data, Referrer and Cookie)

  • script: URL of optional javascript file executed after the page load event

  • hosting: optional S3 and webhook details

  • shared_url: if the screenshot was shared, show the public URL

Trackers:
If the screenshot includes trackers, the response will show the information found:

{
  "trackers": [
    {
      "name":"page title", 
      "value":"document.title",
      "id": "test", 
      "name_type": "string", 
      "input": "", 
      "value_type": "string", 
      "selector": "",
      "return": [{
        "found": 1, 
        "shot": 1, 
        "value": "My Page Title", 
        "name": "page title"
      }
  ]
}

Hosting:
If the screenshot was set to be hosted, or if screenshot/host was called, the response will show the hosting information:

{
  "hosting":[
    {
       "status":"finished",
       "url":"http://browshot.org/static/screenshots/1055447.png",
       "hosting":"browshot"
    }
  ]
}


If details=2, additional information is sent:


  • started: time of processing (UNIX timestamp)

  • finished: time of screenshot completed (UNIX timestamp)

  • load: time the page was loaded (UNIX timestamp, 0 if unknown)

  • request_time: time of request (UNIX timestamp) for the time of request

  • content: time the content was loaded (UNIX timestamp, 0 if unknown)



If details=3, and screenshot/create included details=3, additional information is sent:


  • images: list of absolute URLs of images included on the page

  • scripts: list of absolute URLs of external scripts included on the page

  • stylesheets: list of absolute URLs of external style sheets included on the page

  • embeds: list of absolute URLs of embed included on the page

  • applets: list of absolute URLs of applets included on the page

  • iframes: list of absolute URLs of frames included on the page

  • links: list of absolute URLs of links (a tag) included on the page



Classification:
If the screenshot was requested with html=1, the page content is sent to WebCategorize to be classified into one of the 345 categories supported. The response includes a classification field:

{
  "classification":[
      "id": "WEB14-1",
      "name": "Society > Dating",
      "score": 1,
      "confidence": "high"
    }
  ]
}



/api/v1/screenshot/list

Get information about the last 100 screenshots requested.


Request

Parameters:

  • limit (optional, 0-100, default: 100): number of screenshots' information to return

  • status (optional): get the list of screenshots in a given status (error, finished, in_process)

  • details=0-3 (optional, default: 0): level of details about the screenshot and the page.



Example

https://api.browshot.com/api/v1/screenshot/list?limit=50&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


my $list = $browshot->screenshot_list(limit => 5, status => 'finished'); # last 5 screenshots
foreach my $id (keys %$list) {
	my $url = $list->{$id}->{final_url};
	print "#$id $url\n";
}


# Number of errors
$list = $browshot->screenshot_list(status => 'error');
print scalar(keys %$list), " of the last last 100 screenshots failed\n";

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$list = $browshot->screenshot_list(array('limit' => 5, 'status' => 'finished')); # last 5 screenshots
foreach ($list as $id => $screenshot) {
	echo sprintf("#%d %s\n", $id, $screenshot->{'url'});
}


# Number of errors
$list = $browshot->screenshot_list(array('status' => 'error'));
echo count($list). " of the last last 100 screenshots failed\n";

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


list = browshot.screenshot_list({ 'limit': 5, 'status': 'finished' }) # last 5 screenshots
for id, screenshot in list.iteritems():
	print "#%d %s" % (int(id), screenshot['url'])


# Number of errors
list = browshot.screenshot_list({ 'status': 'error' })
print str(len(list)) + " of the last last 100 screenshots failed"

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


list = browshot.screenshot_list({ 'limit' => 5, 'status' => 'finished' }) # last 5 screenshots
list.each { |id, screenshot|
	puts "##{id} #{screenshot['url']}\n"
}

# Number of errors
list = browshot.screenshot_list({ 'status' => 'error' })
puts "#{list.count} of the last last 100 screenshots failed\n"

Download code sample

'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

// last 5 screenshots
client.screenshotList({ limit: 5, status: 'finished' }, function(list) {
	for(var i in list) {
		console.log(`${list[i].id} ${list[i].url}`);
	}
});

// Number of errors
client.screenshotList({ status: 'error' }, function(list) {
	var count = list.length || 'none';
	console.log(`${count} of the last last 100 screenshots failed`);
});

Download code sample


Response

{
  "52967":{
    "priority":1,
    "status":"finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52967?scale=1&key=my_api_key",
    "id":5296,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52969":{
    "priority":1,
    "status":"finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52969?scale=1&key=my_api_key",
    "id":52969,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type": "text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52971":{
    "priority": 1,
    "status": "processing",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52971?scale=1&key=my_api_key",
    "id":52971,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type": "text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52970":{
    "priority":1,
    "status": "finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52970?scale=1&key=my_api_key",
    "id":52970,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type": "text/html",
    "scale": ",
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52968":{
    "priority":1,
    "status": "finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52968?scale=1&key=my_api_key",
    "id":52968,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type": "text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  }
}


The key is the screenshot ID

See screenshot/info for the list of screenshot information sent depending on the details chosen.



Trackers:
If the screenshot includes trackers, the response will show the information found:

{
  "trackers": [
    {
      "name": "page title", 
      "value": "document.title",
      "id": "test", 
      "name_type": "string", 
      "input": "", 
      "value_type": "string", 
      "selector": "",
      "return": [{
        "found": 1, 
        "shot": 1, 
        "value": "My Page Title", 
        "name": "page title"
      }
  ]
}

Hosting:
If the screenshot was set to be hosted, or if screenshot/host was called, the response will show the hosting information:

{
  "hosting":[
    {
      "status": "finished",
      "url": "http://browshot.org/static/screenshots/1055447.png",
      "hosting": "browshot"
    }
  ]
}



Search for screenshots of a specific URL.

Request

Parameters:

  • url: look for a string matching the URL requested

  • limit (optional, default 50, maximum: 100): maximum number of screenshots' information to return

  • status (optional): get the list of screenshots in a given status (error, finished, in_process)

  • details=0-3 (optional, default: 0): level of details about the screenshot and the page.



Example

Request

https://api.browshot.com/api/v1/screenshot/search?url=google&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


my $list = $browshot->screenshot_search(url => 'google.com', limit => 5, status => 'finished'); # last screenshots of google.com
foreach my $id (keys %$list) {
	my $url = $list->{$id}->{final_url};
	print "#$id $url\n";
}
print "\n";


# no match
$list = $browshot->screenshot_search(url => 'foo.bar');
print "Screenshots for foo.bar: ", scalar(keys %$list), "\n";

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$list = $browshot->screenshot_search('google.com', array('limit' => 5, 'status' => 'finished')); # last screenshots of google.com
foreach ($list as $id => $screenshot) {
	echo sprintf("#%d %s\n", $id, $screenshot->{'url'});
}
echo "\n";


# no match
$list = $browshot->screenshot_search('foo.bar');
echo "Screenshots for foo.bar: " . count($list) . "\n";

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


list = browshot.screenshot_search('google.com', { 'limit': 5, 'status': 'finished' }) # last screenshots of google.com
for id, screenshot in list.iteritems():
  print "#%d %s"% (int(id), screenshot['url'])

print ""


# no match
list = browshot.screenshot_search('foo.bar')
print "Screenshots for foo.bar: %d" % len(list)

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


list = browshot.screenshot_search('google.com', { 'limit' => 5, 'status' => 'finished' }) # last screenshots of google.com
list.each { |id, screenshot| 
  puts "##{id} #{screenshot['url']}\n"
}
puts "\n"


# no match
list = browshot.screenshot_search('foo.bar')
puts "Screenshots for foo.bar: #{list.count}\n"

Download code sample

'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

// last screenshots of google.com
client.screenshotSearch('google.com', { limit: 5, status: 'finished' }, function(list) {
	for(var i in list) {
		console.log(`#${list[i].id} ${list[i].url}`);
	}
});


// no match
client.screenshotSearch('foo.bar', { }, function(list) {
	console.log(`Screenshots for foo.bar: ${list.length || 0}`);
});

Download code sample


Response

{
  "52967":{
    "priority":1,
    "status": "finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52967?scale=1&key=my_api_key",
    "id":52967,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type": "text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52969":{
    "priority": 1,
    "status": "finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52969?scale=1&key=my_api_key",
    "id":52969,
    "url": "http://www.google.org/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.org/",
    "content_type": "text/html",
    "scale": "1",
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52971":{
    "priority":1,
    "status": "processing",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52971?scale=1&key=my_api_key",
    "id":52971,
    "url": "http://www.google.de/",
    "size": screen,
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.de/",
    "content_type": "text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52970":{
    "priority":1,
    "status": "finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52970?scale=1&key=my_api_key",
    "id":52970,
    "url": "http://www.google.fr/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.fr/",
    "content_type": "text/html",
    "scale": 1,
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  },
  "52968":{
    "priority":1,
    "status": "finished",
    "screenshot_url":"https://www.browshot.com/screenshot/image/52968?scale=1&key=my_api_key",
    "id":52968,
    "url": "http://www.google.com/",
    "size": "screen",
    "width": 1024,
    "height": 768,
    "request_time": 1312106111,
    "started": 1312258803994,
    "load": 1312258829461,
    "content": 1312258829661,
    "finished": 1312258829681,
    "instance_id": 12,
    "response_code": 200,
    "final_url": "http://www.google.com/",
    "content_type": "text/html",
    "scale": "1",
    "cost": 0,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": 5,
    "script": "",
    "shared_url": ""
  }
}


The key is the screenshot ID

See screenshot/info for the list of screenshot information sent depending on the details chosen.




/api/v1/screenshot/host

You can host screenshots and thumbnails on your own S3 account or on Browshot.


Request

Parameters:

  • id: screenshot ID

  • hosting: hosting option: s3 or browshot

  • width (optional): width of the thumbnail

  • height (optional): height of the thumbnail

  • scale (optional): scale of the thumbnail

  • bucket (required with hosting=s3): S3 bucket to upload the screenshot or thumbnail

  • file (optional, used with hosting=s3): file name to use

  • headers (optional, used with hosting=s3) HTTP headers to add to your S3 object

  • private(optional, used with hosting=s3): set the ACL to bucket-owner-full-control instead of public-read

If neither width, height and scale are not specified, the original screenshot is hosted.



Example

https://api.browshot.com/api/v1/screenshot/host?id=3965421&hosting=s3&bucket=my_browshot_bucket_name&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


# You can only host screenshots in finished state
my $list = $browshot->screenshot_list(limit => 1, status => 'finished');

my $screenshot = { };
foreach my $id (keys %$list) {
	$screenshot = $list->{id};
}

if (! exists $screenshot->{id}) {
	print "No screenshot finished\n";
}
else {
	my $result = $browshot->screenshot_host(
	  id => $screenshot->{id}, 
	  hosting => 's3', 
	  bucket => 'my_bucket', 
	  file => 'youtube.png', 
	  width => 600
	); # host a thumbnail
	
	if ($result->{status} eq 'ok') {
		print "The screenshot is now hosted at ", $result->{url}, "\n";
	}
	else {
		print "hosting failed: ", $result->{error}, "\n";
	}
}

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


# You can only host screenshots in finished state
$list = $browshot->screenshot_list(array('limit' => 1, 'status' => 'finished'));

if(count($list) == 0) {
	echo "No screenshot finished\n";
}
else {
	$id = 0;
	foreach ($list as $key => $data) {
		$id = $key;
	}
	
	$result = $browshot->screenshot_host($id, array(
	  'hosting' => 's3', 
	  'bucket' => 'my_bucket', 
	  'file' => 'youtube.png', 
	  'width' => 600
	)); # host a thumbnail
	
	if ($result->{'status'} == 'ok') {
		echo sprintf("The screenshot is now hosted at %s\n", $result->{'url'});
	}
	else {
		echo sprintf("hosting failed: %s\n", $result->{'error'});
	}
}

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


# You can only host screenshots in finished state
list = browshot.screenshot_list({ 'limit': 1, 'status': 'finished' })

if len(list) == 0:
	print "No screenshot finished"
else:
  id = 0
  for key, screenshot in list.iteritems():
    id = key
  
  result = browshot.screenshot_host(id, {
    'hosting': 's3', 
    'bucket': 'my_bucket', 
    'file': 'youtube.png', 
    'width': 600
  }) # host a thumbnail
  
  if result['status'] == 'ok':
    print "The screenshot is now hosted at %s" % result['url']
  else:
    print "hosting failed: %s" % result['error']

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key', true)



# You can only host screenshots in finished state
list = browshot.screenshot_list({ 'limit' => 1, 'status' => 'finished' })

if (list.count == 0)
	puts "No screenshot finished\n"
else
  id = 0
  list.each { |key, screenshot|
    id = key
  }
  
  result = browshot.screenshot_host(id, 's3', {
    'bucket' => 'my_bucket', 
    'file' => 'youtube.png', 
    'width' => 600
  }) # host a thumbnail
  
  if (result['status'] == 'ok')
    puts "The screenshot is now hosted at #{result['url']}\n"
  else
    print "hosting failed: #{result['error']}\n"
  end
end

Download code sample

'use strict';

var browshot = require('browshot');

var client = new browshot('my_api_key');



// You can only host screenshots in finished state
client.screenshotList({ limit: 1, status: 'finished' }, function (list) {
	if (list.length == 0) {
		console.log("No screenshot finished");
	}
	else {
		for(var i in list) {
			// host a thumbnail
			client.screenshotHost(list[i].id,
				{
					hosting: 's3',
					bucket: 'my_bucket', 
					file: 'youtube.png', 
					width: 600
				}, function(screenshot) {
					if (screenshot.status == 'ok') {
						console.log(`The screenshot is now hosted at ${screenshot.url}`);
					}
					else {
						console.log(`Hosting failed: ${screenshot.error}`);
					}
				}
			);
		}
	}
});

Download code sample


Response

An error is sent back if the screenshot failed, or if an error occurred during the S3 upload (bad bucket name, wrong ACLs, etc.), etc.

{
  "status": "error",
  "error": "Invalid screenshot id",
  "id": 3965421
}
{
  "status": "error",
  "error": "Screenshot failed previously",
  "id": 3965421
}
{
  "status": "error",
  "error" : "Screenshot failed previously",
  "id": 3965421
}
{
  "status": "ok",
  "url": "http://aws.amazon.com/my_browshot_bucket_name/3965421-640-480.png",
  "id": 3965421
}


  • id: screenshot ID

  • status: status of the request: "error", "ok" or "in_queue"

  • url: URL to the hosted screenshot or thumbnail



You will need our S3 account information to let us upload screenshots and thumbnails to your S3 buckets. Please contact us about S3 hosting.




/api/v1/screenshot/thumbnail

Unlike the other API calls, this API sends back the thumbnail as a PNG file, not JSON. The HTTP response code indicates whether the screenshot was successful (200), incomplete (404), or failed (404). If the screenshot failed or is not finished, a default image "Not found" is sent.

You can crop your screenshots. The crop is done first, then the thumbnail. You can take a 1024x768 screenshot, crop it to 768x768, and get it scaled down to 300x300.


Request

Parameters:

  • id: screenshot ID

  • width (optional): width of the thumbnail

  • height (optional): height of the thumbnail

  • scale (optional): scale of the thumbnail

  • zoom=<1-100> (optional): zoom 1 to 100 percent

  • ratio=<fit|fill> (optional, default: fit). Use fit to keep the original page ratio, and fill to get a thumbnail for the exact width and height specified

  • left (optional, default: 0): left edge of the area to be cropped

  • right (optional, default: screenshot's width): right edge of the area to be cropped

  • top (optional, default: 0): top edge of the area to be cropped

  • bottom (optional, default: screenshot's height): bottom edge of the area to be cropped

  • format (jpeg or png, default: png): image as PNG or JPEG

  • shot (1-10, default: 1): get the second or third screenshot if multiple screenshots were requested

  • quality (1-100): JPEG quality factor (for JPEG thumbnails only)



If you provide both width and height, you need to specify the ratio: fit to keep the original width/height ratio (the thumbnail might be smaller than the specified width and height), or fill to crop the image if necessary.

Examples

Get a thumbnail at 1/3 (33%) of the original:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&zoom=33&key=my_api_key


Get a thumbnail with a height of 100 pixels at most:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&height=100&key=my_api_key


Get a thumbnail of 200 by 100 pixels at most:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&height=100&width=200&ratio=fit&key=my_api_key


Crop the screenshot to 768x768, scale it to a 300x300 thumbnail:

https://api.browshot.com/api/v1/screenshot/thumbnail?id=3965421&right=768&bottom=768&height=300&width=300&ratio=fit&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $screenshot = $browshot->screenshot_create(url => 'http://www.google.com/', instance_id => 12); # all default parameters, instance_id = 12 (free)
# If the screenshot is already in cache, it could be finished already. Othwewise, wait longer
while ($screenshot->{status} ne 'finished' &&  $screenshot->{status} ne 'error') {
	print "Wait...\n";
	sleep 10;
	$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
}

# You can request multiple thumbnails of the same screenshot at no cost
# Get a thumbnail at 1/3 (33%) of the original
$browshot->screenshot_thumbnail_file(id => $screenshot->{id}, zoom => 33, file => "google-1.png");
print "Thumbnail saved to google-1.png\n";

# Get a thumbnail with a height of 100 pixels
$browshot->screenshot_thumbnail_file(id => $screenshot->{id}, height => 100, file => "google-2.png");
print "Thumbnail saved to google-2.png\n";

# Get a thumbnail of 200 by 100 pixels at most
$browshot->screenshot_thumbnail_file(id => $screenshot->{id}, height => 100, width => 200, file => "google-3.png");
print "Thumbnail saved to google-3.png\n";

# Crop the screenshot to 768x768, scale it to a 300x300 thumbnail
$browshot->screenshot_thumbnail_file(id => $screenshot->{id}, right => 768, bottom => 768, height => 300, width => 300, ratio => 'fit', file => "google-4.png");
print "Thumbnail saved to google-4.png\n";

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$screenshot = $browshot->screenshot_create(array('url' => 'http://www.google.com/', 'instance_id' => 12)); # all default parameters, instance_id = 12 (free)
# If the screenshot is already in cache, it could be finished already. Othwewise, wait longer
while ($screenshot->{'status'} != 'finished' &&  $screenshot->{'status'} != 'error') {
	echo "Wait...\n";
	sleep(10);
	$screenshot = $browshot->screenshot_info($screenshot->{'id'});
}

# You can request multiple thumbnails of the same screenshot at no cost
# Get a thumbnail at 1/3 (33%) of the original
$browshot->screenshot_thumbnail_file($screenshot->{'id'}, "google-1.png", array('zoom' => 33));
echo "Thumbnail saved to google-1.png\n";

# Get a thumbnail with a height of 100 pixels
$browshot->screenshot_thumbnail_file($screenshot->{'id'}, "google-2.png", array('height' => 100));
echo "Thumbnail saved to google-2.png\n";

# Get a thumbnail of 200 by 100 pixels at most
$browshot->screenshot_thumbnail_file($screenshot->{'id'}, "google-3.png", array('height' => 100, 'width' => 200));
echo "Thumbnail saved to google-3.png\n";

# Crop the screenshot to 768x768, scale it to a 300x300 thumbnail
$browshot->screenshot_thumbnail_file($screenshot->{'id'}, "google-4.png", array('right' => 768, 'bottom' => 768, 'height' => 300, 'width' => 300, 'ratio' => 'fit'));
echo "Thumbnail saved to google-4.png\n";

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')


screenshot = browshot.screenshot_create('http://www.google.com/', { 'instance_id': 12 }) # all default parameters, instance_id = 12 (free)
# If the screenshot is already in cache, it could be finished already. Othwewise, wait longer
while screenshot['status'] != 'finished' and screenshot['status'] != 'error':
  print "Wait..."
  time.sleep(10)
  screenshot = browshot.screenshot_info(screenshot['id'])

# You can request multiple thumbnails of the same screenshot at no cost
# Get a thumbnail at 1/3 (33%) of the original
browshot.screenshot_thumbnail_file(screenshot['id'], "google-1.png", { 'zoom': 33 })
print "Thumbnail saved to google-1.png"

# Get a thumbnail with a height of 100 pixels
browshot.screenshot_thumbnail_file(screenshot['id'], "google-2.png", { 'height': 100 })
print "Thumbnail saved to google-2.png"

# Get a thumbnail of 200 by 100 pixels at most
browshot.screenshot_thumbnail_file(screenshot['id'], "google-3.png", { 'height': 100, 'width': 200 })
print "Thumbnail saved to google-3.png"

# Crop the screenshot to 768x768, scale it to a 300x300 thumbnail
browshot.screenshot_thumbnail_file(screenshot['id'], "google-4.png", { 'right': 768, 'bottom': 768, 'height': 300, 'width': 300, 'ratio': 'fit' })
print "Thumbnail saved to google-4.png"

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


screenshot = browshot.screenshot_create('http://www.google.com/', { 'instance_id' => 12 }) # all default parameters, instance_id = 12 (free)
# If the screenshot is already in cache, it could be finished already. Othwewise, wait longer
while (screenshot['status'] != 'finished' && screenshot['status'] != 'error')
  puts "Wait...\n"
  sleep(10)
  screenshot = browshot.screenshot_info(screenshot['id'])
end

# You can request multiple thumbnails of the same screenshot at no cost
# Get a thumbnail at 1/3 (33%) of the original
browshot.screenshot_thumbnail_file(screenshot['id'], "google-1.png", { 'zoom' => 33 })
puts "Thumbnail saved to google-1.png\n"

# Get a thumbnail with a height of 100 pixels
browshot.screenshot_thumbnail_file(screenshot['id'], "google-2.png", { 'height' => 100 })
puts "Thumbnail saved to google-2.png\n"

# Get a thumbnail of 200 by 100 pixels at most
browshot.screenshot_thumbnail_file(screenshot['id'], "google-3.png", { 'height' => 100, 'width' => 200 })
puts "Thumbnail saved to google-3.png\n"

# Crop the screenshot to 768x768, scale it to a 300x300 thumbnail
browshot.screenshot_thumbnail_file(screenshot['id'], "google-4.png", { 'right' => 768, 'bottom' => 768, 'height' => 300, 'width' => 300, 'ratio' => 'fit' })
puts "Thumbnail saved to google-4.png\n"

Download code sample

'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

var interval;

// all default parameters, instance_id = 12 (free)
client.screenshotCreate(
	{url: 'http://www.google.com/', instance_id: 12, size: 'page' }, 
	function(screenshot) {
		// If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
		if (screenshot.status == 'error') {
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			screenshotFinished(screenshot);
		}
		else {
			interval = setInterval(checkScreenshot, 1000 * 10, screenshot.id);
		}
	}
);


function checkScreenshot(id) {
	client.screenshotInfo(id, { }, function(screenshot) {
		if (screenshot.status == 'error') {
			clearInterval(interval);
			
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			clearInterval(interval);
			
			screenshotFinished(screenshot);
		}
		else {
			console.log(`Waiting for screenshot #${screenshot.id} to finish...`);
		}
	});
}

function screenshotFinished(screenshot) {
	// Get a thumbnail at 1/3 (33%) of the original
	client.screenshotThumbnailFile(screenshot.id, "google-1.png", { zoom: 33 }, function(file) {
		console.log(`Thumbnail saved to ${file}`);
	});
	
	// Get a thumbnail with a height of 100 pixels
	client.screenshotThumbnailFile(screenshot.id, "google-2.png", { height: 100 }, function(file) {
		console.log(`Thumbnail saved to ${file}`);
	});
	
	// Get a thumbnail of 200 by 100 pixels at most
	client.screenshotThumbnailFile(screenshot.id, "google-3.png", { height: 100, width: 200 }, function(file) {
		console.log(`Thumbnail saved to ${file}`);
	});
	
	// Crop the screenshot to 768x768, scale it to a 300x300 thumbnail
	client.screenshotThumbnailFile(screenshot.id, "google-4.png", { right:768, bottom: 768, height: 300, width: 300, ratio: 'fit' }, function(file) {
		console.log(`Thumbnail saved to ${file}`);
	});
}

Download code sample




/api/v1/screenshot/share

You can make your screenshots public, add notes, and share it with your friends and colleagues. Only screenshots which are completed can be shared.


Request

Parameters:

  • id: screenshot ID

  • note (optional): note to add on the sharing page



Examples

https://api.browshot.com/api/v1/screenshot/share?id=3965421&note=this+is+my+screenshot&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


my $screenshot = $browshot->screenshot_create(url => 'http://mobilio.net/', instance_id => 12); 
sleep 60;

if ($screenshot->{status} eq 'error') {
	print "Screenshot failed: ", $screenshot->{error}, "\n";
	exit(0);
}

# Share this screenshot
$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
if ($screenshot->{status} eq 'finished') { 
	# share a screenshot (must be in finished state)
	my $share = $browshot->screenshot_share(id => $screenshot->{id}, note => 'Browshot is great!');
	if ($share->{status} eq 'ok') {
		print "Screenshot shared at ", $share->{url}, "\n";
	}
	else {
		print "Sharing failed: ", $share->{error}, "\n";
	}
}

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$screenshot = $browshot->screenshot_create(array('url' => 'http://mobilio.net/', 'instance_id' => 12)); 
sleep(60);

if ($screenshot->{'status'} == 'error') {
	echo sprintf("Screenshot failed: %s\n", $screenshot->{'error'});
	exit(0);
}

# Share this screenshot
$screenshot = $browshot->screenshot_info($screenshot->{'id'});
if ($screenshot->{'status'} == 'finished') { 
	# share a screenshot (must be in finished state)
	$share = $browshot->screenshot_share($screenshot->{'id'}, array('note' => 'Browshot is great!'));
	if ($share->{'status'} == 'ok') {
		echo sprintf("Screenshot shared at %s\n", $share->{'url'});
	}
	else {
		echo sprintf("Sharing failed: %s\n", $share->{'error'});
	}
}

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')


screenshot = browshot.screenshot_create('http://mobilio.net/', { 'instance_id': 12 })
time.sleep(60)

if screenshot['status'] == 'error':
  print "Screenshot failed: %s" % screenshot['error']
  exit(0)

# Share this screenshot
screenshot = browshot.screenshot_info(screenshot['id'])
if screenshot['status'] == 'finished':
  # share a screenshot (must be in finished state)
  share = browshot.screenshot_share(screenshot['id'], { 'note': 'Browshot is great!' })
  if share['status'] == 'ok':
    print "Screenshot shared at %s" % share['url']
  else:
    print "Sharing failed: %s\n" % share['error']

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')

screenshot = browshot.screenshot_create('http://mobilio.net/', { 'instance_id' => 12 })
sleep(60)

if (screenshot['status'] == 'error')
  puts "Screenshot failed: #{screenshot['error']}\n"
  exit(0)
end

# Share this screenshot
screenshot = browshot.screenshot_info(screenshot['id'])
if (screenshot['status'] == 'finished')
  # share a screenshot (must be in finished state)
  share = browshot.screenshot_share(screenshot['id'], { 'note' => 'Browshot is great!' })
  if (share['status'] == 'ok')
    puts "Screenshot shared at #{share['url']}\n"
  else
    puts "Sharing failed: #{share['error']}\n"
  end
end

Download code sample

'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

var interval;

client.screenshotCreate({url: 'http://mobilio.net/', instance_id: 12 }, function(screenshot) {
		// If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
		if (screenshot.status == 'error') {
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			screenshotFinished(screenshot);
		}
		else {
			interval = setInterval(checkScreenshot, 1000 * 10, screenshot.id);
		}
	}
);

function checkScreenshot(id) {
	client.screenshotInfo(id, { }, function(screenshot) {
		if (screenshot.status == 'error') {
			clearInterval(interval);
			
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			clearInterval(interval);
			
			screenshotFinished(screenshot);
		}
		else {
			console.log(`Waiting for screenshot #${screenshot.id} to finish...`);
		}
	});
}

function screenshotFinished(screenshot) {
	// share a screenshot (must be in finished state)
	client.screenshotShare(screenshot.id, { note: 'Browshot is great!' }, function(share) {
		if (share.status == 'ok')
			console.log(`Screenshot shared at ${share.url}`);
		else
			console.log(`Sharing failed: ${share.error}`);
	});
}

Download code sample


Response
{
  "status": "error",
  "error" : "Invalid screenshot id",
  "id": 3965421
}
{
  "status": "ok",
  "url": "https://browshot.com/share/U6uVs0VysLbf9VCms",
  "id": 3965421
}


  • id: screenshot ID

  • status: status of the request: "error", "ok"

  • url: URL to the sharing page




/api/v1/screenshot/delete

You can delete details of your screenshots to remove any confidential information.


Request

Parameters:

  • id: screenshot ID

  • data (optional): data to remove. You can specify multiple of them (separated by a ,):

    • image (default): image file (screenshot and thumbnails)

    • url: URL requested

    • metadata: time added, time finished, post data, cookie, and referer used for the screenshot

    • all: all data above



Examples

https://api.browshot.com/api/v1/screenshot/delete?id=3965421&data=image,metadata&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


my $screenshot = $browshot->screenshot_create(url => 'http://mobilio.net/', instance_id => 12); 
sleep 60;

# Delete the screenshto URL
$browshot->screenshot_delete(id => $screenshot->{id}, data => 'url');

my $info = $browshot->screenshot_info(id => $screenshot->{id});
if (! exists ($info->{url}) || $info->{url} eq '') {
	print "URL has been deleted for screenshot #", $screenshot->{id}, "\n";
}

# Delete the image
$browshot->screenshot_delete(id => $screenshot->{id}, data => 'image');
my $image = $browshot->screenshot_thumbnail(id => $screenshot->{id});
if (length($image) == 0) {
	print "Screenshot for #", $screenshot->{id}, " has been deleted\n";
}

# Delete everything
$browshot->screenshot_delete(id => $screenshot->{id}, data => 'all');

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$screenshot = $browshot->screenshot_create(array('url' => 'http://mobilio.net/', 'instance_id' => 12)); 
sleep(60);

# Delete the screenshto URL
$browshot->screenshot_delete($screenshot->{'id'}, array('data' => 'url'));

$info = $browshot->screenshot_info($screenshot->{'id'});
if (! array_key_exists('url', $info) || $info->{'url'} == '') {
	echo sprintf("URL has been deleted for screenshot #%d\n", $screenshot->{'id'});
}

# Delete the image
$browshot->screenshot_delete($screenshot->{'id'}, array('data' => 'image'));
$image = $browshot->screenshot_thumbnail($screenshot->{'id'});
if (strlen($image) == 0) {
	echo sprintf("Screenshot for #%d has been deleted\n", $screenshot->{'id'});
}

# Delete everything
$browshot->screenshot_delete($screenshot->{'id'}, array('data' => 'all'));

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')


screenshot = browshot.screenshot_create('http://mobilio.net/', { 'instance_id': 12 })
time.sleep(60)

# Delete the screenshto URL
browshot.screenshot_delete(screenshot['id'], { 'data': 'url' })

info = browshot.screenshot_info(screenshot['id'])
if not 'url' in info or info['url'] == '':
  print "URL has been deleted for screenshot #%d" % int(screenshot['id'])

# Delete the image
browshot.screenshot_delete(screenshot['id'], { 'data': 'image' })
image = browshot.screenshot_thumbnail(screenshot['id'])
if len(image) == 0:
  print "Screenshot for #%d has been deleted" % int(screenshot['id'])

# Delete everything
browshot.screenshot_delete(screenshot['id'], { 'data': 'all' })

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


screenshot = browshot.screenshot_create('http://mobilio.net/', { 'instance_id' => 12 })
sleep(60)

# Delete the screenshto URL
browshot.screenshot_delete(screenshot['id'], { 'data' => 'url' })

info = browshot.screenshot_info(screenshot['id'])
if (! info.key?('url') || info['url'] == '')
  puts "URL has been deleted for screenshot ##{screenshot['id']}\n"
end

# Delete the image
browshot.screenshot_delete(screenshot['id'], { 'data' => 'image' })
image = browshot.screenshot_thumbnail(screenshot['id'])
if (image.length == 0)
  puts "Screenshot for ##{screenshot['id']} has been deleted\n"
end

# Delete everything
browshot.screenshot_delete(screenshot['id'], { 'data' => 'all' })

Download code sample

var browshot = require('browshot');

var client = new browshot('my_api_key');

var interval;

client.screenshotCreate({url: 'http://mobilio.net/', instance_id: 12 }, function(screenshot) {
	// If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
	if (screenshot.status == 'error') {
		console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
	}
	else if (screenshot.status == 'finished') {
		screenshotFinished(screenshot);
	}
	else {
		interval = setInterval(checkScreenshot, 1000 * 10, screenshot.id);
	}

});


function checkScreenshot(id) {
	client.screenshotInfo(id, { }, function(screenshot) {
		if (screenshot.status == 'error') {
			clearInterval(interval);
			
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			clearInterval(interval);
			
			screenshotFinished(screenshot);
		}
		else {
			console.log(`Waiting for screenshot #${screenshot.id} to finish...`);
		}
	});
}

function screenshotFinished(screenshot) {
	// delete URL
	client.screenshotDelete(screenshot.id, { data: 'url' }, function(screenshot) {
		client.screenshotInfo(screenshot.id, { }, function(info) {
			if (! info.hasOwnProperty('url') || info.url == '') {
				console.log(`URL has been deleted for screenshot #${info.id}`);
			}
		});
	});
	
	// delete the image
	client.screenshotDelete(screenshot.id, { data: 'image' }, function(screenshot) {
		client.screenshotThumbnail(screenshot.id, { }, function(image) {
			if (image.length == 0) {
			console.log(`Image has been deleted for screenshot #${screenshot.id}`);
			}
		});
	});
	
	// Delete everything
	client.screenshotDelete(screenshot.id, { data: 'all' }, function(screenshot) {
		console.log("All data have been deleted");
	});
}

Download code sample


Response
{
  "status": "error",
  "error" : "Invalid screenshot id",
  "id": 3965421
}
{
  "status": "ok",
  "id": 3965421
}


  • id: screenshot ID

  • status: status of the request: "error", "ok"




/api/v1/screenshot/html

Retrieve the HTML code of the rendered page. This API call should be used when html=1 was specified in the screenshot request.

Request

Parameters:

  • id: screenshot ID



This API call returns the HTML of the rendered page when successful, or an empty body with a 404 HTTP status code in case of failure.



Examples

https://api.browshot.com/api/v1/screenshot/html?id=3965421&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


# You must request HTML when creating the screenshot
my $screenshot = $browshot->screenshot_create(url => 'http://mobilio.net/', instance_id => 24, screen_width => 1280, screen_height => 1024, html => 1); 
sleep 60;

$screenshot = $browshot->screenshot_info(id => $screenshot->{id});
if ($screenshot->{status} eq 'finished') {
	my $html = $browshot->screenshot_html(id => $screenshot->{id});
	if (length($html) > 0) {
		print "HTML is available\n";
# 		print "$html\n";
	}
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

# You must request HTML when creating the screenshot
$screenshot = $browshot->screenshot_create(array('url' => 'http://mobilio.net/', 'instance_id' => 24, 'screen_width' => 1280, 'screen_height' => 1024, 'html' => 1)); 
sleep(60);

$screenshot = $browshot->screenshot_info($screenshot->{'id'});
if ($screenshot->{'status'} == 'finished') {
	$html = $browshot->screenshot_html($screenshot->{'id'});
	if (strlen($html) > 0) {
		echo "HTML is available\n";
# 	echo "$html\n";
	}
}

?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')

# You must request HTML when creating the screenshot
screenshot = browshot.screenshot_create('http://mobilio.net/', { 'instance_id': 24, 'screen_width': 1280, 'screen_height': 1024, 'html': 1 })
time.sleep(60)

screenshot = browshot.screenshot_info(screenshot['id'])
if screenshot['status'] == 'finished':
  html = browshot.screenshot_html(screenshot['id'])
  if len(html) > 0:
    print "HTML is available"
#    print html

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

# You must request HTML when creating the screenshot
screenshot = browshot.screenshot_create('http://mobilio.net/', { 'instance_id' => 24, 'screen_width' => 1280, 'screen_height' => 1024, 'html' => 1 })
sleep(60)

screenshot = browshot.screenshot_info(screenshot['id'])
if (screenshot['status'] == 'finished')
  html = browshot.screenshot_html(screenshot['id'])
  if (html.length > 0)
    puts "HTML is available\n"
#    puts html
  end
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/
'use strict';

const browshot = require('browshot');

var client = new browshot('my_api_key');

var interval;

// You must request HTML when creating the screenshot
client.screenshotCreate(
	{
		url: 'http://mobilio.net/',
		instance_id: 24, 
		screen_width: 1280, 
		screen_height: 1024, 
		html: 1 
	}, function(screenshot) {
		// If the screenshot is already in cache, it could be finished already. Otherwise, wait longer
		if (screenshot.status == 'error') {
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			screenshotFinished(screenshot);
		}
		else {
			interval = setInterval(checkScreenshot, 1000 * 10, screenshot.id);
		}
	}
);

function checkScreenshot(id) {
	client.screenshotInfo(id, { }, function(screenshot) {
		if (screenshot.status == 'error') {
			clearInterval(interval);
			
			console.log(`Screenshot #${screenshot.id} failed: ${screenshot.error}`);
		}
		else if (screenshot.status == 'finished') {
			clearInterval(interval);
			
			screenshotFinished(screenshot);
		}
		else {
			console.log(`Waiting for screenshot #${screenshot.id} to finish...`);
		}
	});
}

function screenshotFinished(screenshot) {
	client.screenshotHtml(screenshot.id, function(html) {
		if (html.length > 0) {
			console.log("HTML is available");
		}
	
	});
}

Download code sample





/api/v1/batch/create (updated 1.30)

Get hundreds or thousands of screenshots from a text file. You can use this API call or the dashboard.

Unlike the other API calls, you must issue a POST request with the Content-Type "multipart/form-data" to upload the text file.

The text file must contain the list of URLs to request, 1 URL per line. Failed screenshots will be tried up to 3 times before giving up.

S3 hosting

Screenshots from the batch can be uploaded automatically to S3. Add the S3 file name (optional) to each URL in the file, as a second column:

http://example.org/,example.png
http://other.com/,other.png



Request

Required parameters:

  • instance_id: instance ID to use

  • file: file content


Optional parameters:

  • split (default: 0) (new 1.30): set to 1 to split the ZIP archive into 100MB files

  • size: screenshot size: "screen" (default) or "page"

  • name: name of the batch

  • width: thumbnail width

  • height: thumbnail height

  • format (jpeg or png, default: png): image as PNG or JPEG

  • screen_width (1-5000): width of the browser window. For desktop browsers only.

  • screen_height (1-10000): height of the browser window. For desktop browsers only. (Note: full-page screenshots can have a height of up to 15,000px)

  • delay=0-60 (default: 5): number of seconds to wait after the page has loaded. This is used to let JavaScript run longer before taking the screenshot. Use delay=0 to take screenshots faster

  • referer ( paid screenshots only): use a custom referrer (see Custom POST Data, Referrer and Cookie)

  • headers: any custom HTTP headers.

  • post_data (paid screenshots only): send a POST request with post_data, useful for filling out forms (see Custom POST Data, Referrer and Cookie)

  • cookie (paid screenshots only): set a cookie for the URL requested (see Custom POST Data, Referrer and Cookie)

  • script: URL of javascript file to execute after the page load event

  • script_inline: Javascript content to execute after the page load event.

  • details=1-3 ( default: 2): level of information available with screenshot/info

  • html=0,1 (default: 0): save the HTML of the rendered page which can be retrieved by the API call screenshot/html, and classify the content of the page. This feature costs 1 credit per screenshot

  • hide_popups: hide popups (ads, cookie warning, etc.) on the page

  • dark: run the browser in dark mode - Chrome and Mobile only

Host parameters:

  • hosting: hosting option: s3

  • hosting_height (optional): maximum height of the thumbnail to host

  • hosting_width (optional): maximum width of the thumbnail to host

  • hosting_scale (optional): scale of the thumbnail to host

  • hosting_bucket (required for S3): S3 bucket to upload the screenshot or thumbnail

  • hosting_file (optional, for S3 only): file name to use

  • hosting_headers (optional): list of headers to add to the S3 object



Examples

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits.
#######################



my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


# Create a text file with a list of URLs
open SOURCE, "> batch.txt" or croak "Cannot create file: $!\n";
print SOURCE "google.com\n";
print SOURCE "mobilito.net\n";
close SOURCE;


my $batch = $browshot->batch_create(file => "batch.txt", instance_id => 65, screen_width => 1600, screen_height => 1200, size => 'page'); # Get full size thumbnails
if ($batch->{status} eq 'error') {
	print "Batch failed: ", $batch->{error}, "\n";
	exit(0);
}

print "Batch #", $batch->{id}, " in process\n";

sleep 30;
while ($batch->{status} ne 'finished' && $batch->{status} ne 'error') {
	sleep 15;
	$batch = $browshot->batch_info(id => $batch->{id});
}

if ($batch->{status} eq 'error') {
	print "Batch failed: ", $batch->{error}, "\n";
	exit(0);
}

# The batch succeeded, download the archive. There may be more than 1 URL
foreach my $url (@{ $batch->{urls} }) {
	print "Downloading $url...\n";
	# Use LWP::Simple or LWP::UserAgent to download the archive
}

if (scalar @{ $batch->{urls} } > 1) {
	# Run 7a if the archive was split into multiple files
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

# Create a text file with a list of URLs
$fp = fopen("batch.txt", 'w') or die("Unable to open batch.txt!");;
fwrite($fp, "google.com\n");
fwrite($fp, "mobilito.net\n");
fclose($fp);


$batch = $browshot->batch_create("batch.txt", array('instance_id' => 65, 'screen_width' => 1600, 'screen_height' => 1200, 'size' => 'page')); # Get full size thumbnails
if ($batch->{'status'} == 'error') {
	echo sprintf("Batch failed: %s\n", $batch->{'error'});
	exit(0);
}

echo sprintf("Batch #%d in process\n", $batch->{'id'});

sleep(30);
while ($batch->{'status'} != 'finished' && $batch->{'status'} != 'error') {
	sleep(15);
	$batch = $browshot->batch_info($batch->{'id'});
}

if ($batch->{'status'} == 'error') {
	echo sprintf("Batch failed: %s\n", $batch->{'error'});
	exit(0);
}

# The batch succeeded, download the archive. There may be more than 1 URL
foreach ($batch->{'urls'} as $url) {
	echo "Downloading $url...\n";
	# download the URL
}

if (count($batch->{'urls'}) > 1) {
	# Run 7a if the archive was split into multiple files
}

?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')

# Create a text file with a list of URLs
fp = open("batch.txt", mode='w')
fp.write("google.com\n")
fp.write("mobilito.net\n")
fp.close()


batch = browshot.batch_create("batch.txt", { 'instance_id': 65, 'screen_width': 1600, 'screen_height': 1200, 'size': 'page' }) # Get full size thumbnails
if batch['status'] == 'error':
  print("Batch failed: %s" % batch['error'])
  exit(0)


print "Batch #%d in process" % int(batch['id'])

time.sleep(30)
while batch['status'] != 'finished' and batch['status'] != 'error':
  time.sleep(15)
  batch = browshot.batch_info(batch['id'])


if batch['status'] == 'error':
  print("Batch failed: %s" % batch['error'])
  exit(0)

# The batch succeeded, download the archive. There may be more than 1 URL
for url in batch['urls']:
  print "Downloading %s..." % url

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

# Create a text file with a list of URLs
File.open("batch.txt", 'w') {|f| 
	f.write("google.com\n")
	f.write("mobilito.net\n")
}


batch = browshot.batch_create(65, "batch.txt", { 'screen_width' => 1600, 'screen_height' => 1200, 'size' => 'page' }) # Get full size thumbnails
if (batch['status'] == 'error')
  puts "Batch failed: #{batch['error']}\n"
  exit(0)
end

print "Batch ##{batch['id']} in process\n"

sleep(30)
while (batch['status'] != 'finished' && batch['status'] != 'error')
  sleep(15)
  batch = browshot.batch_info(batch['id'])
end

if (batch['status'] == 'error')
  puts "Batch failed: #{batch['error']}\n"
  exit(0)
end

# The batch succeeded, download the archive. There may be more than 1 URL.
if (batch.key?('urls'))
	batch['urls'].each { |url|
		puts "Downloading #{url}...\n"
	}
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/

var browshot = require('browshot');
const fs = require("fs");

var client = new browshot('my_api_key');

var timeout;

// Create a text file with a list of URLs
fs.writeFile("batch.txt", "google.com\nmobilito.net\n", (err) => {
	if (err) {
		console.log(`Failed to write list of URLs batch.txt: ${err}`);
	}
	else {
		submitBatch("batch.txt");
	}
});


function submitBatch(file) {
	client.batchCreate(
		file, 65, { screen_width: 1600, screen_height: 1200, size: 'page' }, 
		function(batch) {
			fs.unlink(file, function() {});
			
			if (batch.status == 'error') {
				console.log("Batch failed: " + batch.error);
			}
			else {
				console.log(`Batch #${batch.id} in process`);
				
				// Check the status of the batch every 30 seconds
				timeout = setInterval(checkBatch , 1000 * 30, batch.id);
			}
		}
	);
}

function checkBatch(id) {
	client.batchInfo(id, { }, function(batch) {
		if (batch.status == 'error') {
			clearInterval(timeout);
			
			console.log("Batch failed: " + batch.error);
		}
		else if (batch.status == 'finished') {
			clearInterval(timeout);
			
			// The batch succeeded, download the archive. There may be more than 1 URL
			for(var i in batch.urls) {
				console.log(`Downloading ${batch.urls[i]}  ...`);
			}
		}
		else {
			console.log(`Waiting for batch ${batch.id} to finish`);
		}
	});
}

Download code sample


Response

See /api/v1/batch/info for the details.

{
  "status": "error",
  "error" : "Missing file"
}
{
  "status": "in_queue",
  "id": 5
}



/api/v1/batch/info (updated 1.30)

Get the status of a batch requested through the API or the dashboard.


Request

Parameters:

  • id: batch ID



Examples

https://api.browshot.com/api/v1/batch/info?id=5&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;

#######################
# WARNING
# Running this code sample will cost you Browshot credits.
#######################



my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);


# Create a text file with a lsit of URLs
open SOURCE, "> batch.txt" or croak "Cannot create file: $!\n";
print SOURCE "google.com\n";
print SOURCE "mobilito.net\n";
close SOURCE;


my $batch = $browshot->batch_create(file => "batch.txt", instance_id => 65, screen_width => 1600, 
  screen_height => 1200, size => 'page', width => 600); # Get thumbnails
  
if ($batch->{status} eq 'error') {
	print "Batch failed: ", $batch->{error}, "\n";
	exit(0);
}

print "Batch #", $batch->{id}, " in process\n";

sleep 30;
while ($batch->{status} ne 'finished' && $batch->{status} ne 'error') {
	sleep 15;
	$batch = $browshot->batch_info(id => $batch->{id});
}

if ($batch->{status} eq 'error') {
	print "Batch failed: ", $batch->{error}, "\n";
	exit(0);
}

# Check how many screenshot failed
print $batch->{failed}, "/", $batch->{count}, " screenshots failed\n";

# The batch succeeded, download the archive. There may be fore than 1 URL
foreach my $url (@{ $batch->{urls} }) {
	print "Downloading $url...\n";
	# Use LWP::Simple or LWP::UserAgent to download the archive
}

if (scalar @{ $batch->{urls} } > 1) {
	# Run 7a if the archive was split into multiple files
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


# Create a text file with a lsit of URLs
$fp = fopen("batch.txt", 'w') or die("Unable to open batch.txt!");;
fwrite($fp, "google.com\n");
fwrite($fp, "mobilito.net\n");
fclose($fp);


$batch = $browshot->batch_create("batch.txt", array('instance_id' => 65, 'screen_width' => 1600, 
  'screen_height' => 1200, 'size' => 'page', 'width' => 600)); # Get thumbnails
  
if ($batch->{'status'} == 'error') {
	echo sprintf("Batch failed: %s\n", $batch->{'error'});
	exit(0);
}

sprintf("Batch #%d in process\n", $batch->{'id'});

sleep(30);
while ($batch->{'status'} != 'finished' && $batch->{'status'} != 'error') {
	sleep(15);
	$batch = $browshot->batch_info($batch->{'id'});
}

if ($batch->{'status'} == 'error') {
	echo sprintf("Batch failed: %s\n", $batch->{'error'});
	exit(0);
}

# Check how many screenshot failed
echo sprintf("%d/%d screenshots failed\n", $batch->{'failed'}, $batch->{'count'});

# The batch succeeded, download the archive. There may be fore than 1 URL
foreach ($batch->{'urls'} as $url) {
	echo "Downloading $url...\n";
	# Download the archive
}

if (count($batch->{'urls'}) > 1) {
	# Run 7a if the archive was split into multiple files
}

?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')

# Create a text file with a lsit of URLs
fp = open("batch.txt", mode='w')
fp.write("google.com\n")
fp.write("mobilito.net\n")
fp.close()



batch = browshot.batch_create("batch.txt", { 'instance_id': 65, 'screen_width': 1600, 
  'screen_height': 1200, 'size': 'page', 'width': 600 }); # Get thumbnails
  
if batch['status'] == 'error':
  print "Batch failed: %s" % batch['error']
  exit(0)

print "Batch #%d in process" % int(batch['id'])

time.sleep(30)
while batch['status'] != 'finished' and batch['status'] != 'error':
  time.sleep(15)
  batch = browshot.batch_info(batch['id'])

if batch['status'] == 'error':
  print "Batch failed: %s" % batch['error']
  exit(0)

# Check how many screenshot failed
print "%d/%d screenshots failed" % (int(batch['failed']), int(batch['count']))

if 'urls' in batch:
  # The batch succeeded, download the archive. There may be fore than 1 URL
  for url in batch['urls']:
    print "Downloading %s..." % url 
    # Download the archive

  if len(batch['urls']) > 1:
    # Run 7a if the archive was split into multiple files
    print "7a ..."

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

# Create a text file with a list of URLs
File.open("batch.txt", 'w') {|f| 
	f.write("google.com\n")
	f.write("mobilito.net\n")
}


batch = browshot.batch_create(65, "batch.txt", { 'screen_width' => 1600, 
  'screen_height' => 1200, 'size' => 'page', 'width' => 600 }); # Get thumbnails
  
if (batch['status'] == 'error')
  puts "Batch failed: #{ batch['error']}\n"
  exit(0)
end

puts "Batch ##{batch['id']} in process\n"

sleep(30)
while (batch['status'] != 'finished' && batch['status'] != 'error')
  sleep(15)
  batch = browshot.batch_info(batch['id'])
end

if (batch['status'] == 'error')
  puts "Batch failed: #{batch['error']}\n"
  exit(0)
end

# Check how many screenshot failed
puts "#{batch['failed']}/#{batch['count']} screenshots failed\n"

if (batch.key?('urls'))
  # The batch succeeded, download the archive. There may be more than 1 URL.
  batch['urls'].each { |url|
    puts "Downloading #{url}...\n"
    # Download the archive
  }

  if (batch['urls'].count > 1)
    # Run 7a if the archive was split into multiple files
    puts "7a ...\n"
  end
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/

const browshot = require('browshot');
const fs = require("fs");

var client = new browshot('my_api_key');


// Create a text file with a list of URLs
fs.writeFile("batch.txt", "google.com\nmobilito.net\n", (err) => {
	if (err) {
		error(err);
	}
	else {
		submitBatch("batch.txt");
	}
});


function submitBatch(file) {
	client.batchCreate(
		file, 65, { screen_width: 1600, screen_height: 1200, size: 'page', width: 600 }, 
		function(batch) {
			fs.unlink(file, function() {});
			
			if (batch.status == 'error') {
				console.log("Batch failed: " + batch.error);
			}
			else {
				console.log(`Batch #${batch.id} in process`);
				
				// Check the status of the batch every 30 seconds
				timeout = setInterval(checkBatch , 1000 * 30, batch.id);
			}
		}
	);
}

function checkBatch(id) {
	client.batchInfo(id, { }, function(batch) {
		if (batch.status == 'error') {
			clearInterval(timeout);
			
			console.log("Batch failed: " + batch.error);
		}
		else if (batch.status == 'finished') {
			clearInterval(timeout);
			
			// Check how many screenshot failed
			console.log(`${batch.failed}/${batch.count} screenshots failed`);
			
			// The batch succeeded, download the archive. There may be more than 1 URL
			for(var i in batch.urls) {
				console.log(`Downloading ${batch.urls[i]}  ...`);
			}
			
			if (batch.urls.length > 1) {
				// Run 7a if the archive was split into multiple files
				console.log("7a ...");
			}
		}
		else {
			console.log(`Waiting for batch ${batch.id} to finish`);
		}
	});
}

Download code sample


Response

{
  "status": "error",
  "error" : "Wrong batch ID"
}
{
  "status": "in_queue",
  "id": 5
}
{
  "status": "in_process",
  "id": 5,
  "started":  1312106111,
  "finished":  0,
  "count":  10000,
  "processed": 523,
  "failed": 7,
  "split": 1
}
{
  "status": "finished",
  "id": 5,
  "started":  1312106111,
  "finished":  10000,
  "count":  10000,
  "processed": 10000,
  "failed": 7,
  "urls": ["https://browshot.com/static/batch/browshot-5-GQdF0w8dMwkieE5wiUsTPAjGA.zip.001", 
    "https://browshot.com/static/batch/browshot-5-GQdF0w8dMwkieE5wiUsTPAjGA.zip.002"]
}

  • status: status of the request: "in_queue", "processing", "finished", "error"

  • id: batch ID

  • started: time of processing (UNIX timestamp)

  • finished: time of batch completed (UNIX timestamp)

  • count: number of unique URLs in the batch

  • processed: number of screenshots finished

  • failed: number of screenshots failed

  • urls: URLs to download the batch

  • split (new 1.30): 1 if large archive should be split into multiple 100MB files




/api/v1/crawl/create (new 1.29)

Crawl a domain to screenshot all pages. You can use this API call or the dashboard.

The details parameter is set to 3 to capture all the links. This means each screenshot costs an extra credit.



Request

Required parameters:

  • domain: domain to crawl

  • url: URL to start the crawl

  • instance_id: instance ID to use


Optional parameters:

  • max: screenshot size: "screen" (default) or "page"

  • size: screenshot size: "screen" (default) or "page"

  • name: name of the batch

  • width: thumbnail width

  • height: thumbnail height

  • format (jpeg or png, default: png): image as PNG or JPEG

  • screen_width (1-5000): width of the browser window. For desktop browsers only.

  • screen_height (1-10000): height of the browser window. For desktop browsers only. (Note: full-page screenshots can have a height of up to 15,000px)

  • delay=0-60 (default: 5): number of seconds to wait after the page has loaded. This is used to let JavaScript run longer before taking the screenshot. Use delay=0 to take screenshots faster

  • referer ( paid screenshots only): use a custom referrer (see Custom POST Data, Referrer and Cookie)

  • headers: any custom HTTP headers.

  • post_data (paid screenshots only): send a POST request with post_data, useful for filling out forms (see Custom POST Data, Referrer and Cookie)

  • cookie (paid screenshots only): set a cookie for the URL requested (see Custom POST Data, Referrer and Cookie)

  • script: URL of javascript file to execute after the page load event

  • script_inline: Javascript content to execute after the page load event.

  • html=0,1 (default: 0): save the HTML of the rendered page which can be retrieved by the API call screenshot/html, and classify the content of the page. This feature costs 1 credit per screenshot

  • hide_popups: hide popups (ads, cookie warning, etc.) on the page

  • dark: run the browser in dark mode - Chrome and Mobile only

Host parameters:

  • hosting: hosting option: s3

  • hosting_height (optional): maximum height of the thumbnail to host

  • hosting_width (optional): maximum width of the thumbnail to host

  • hosting_scale (optional): scale of the thumbnail to host

  • hosting_bucket (required for S3): S3 bucket to upload the screenshot or thumbnail

  • hosting_file (optional, for S3 only): file name to use

  • hosting_headers (optional): list of headers to add to the S3 object



Examples

https://api.browshot.com/api/v1/crawl/create?domain=blitapp.com&url=https://blitapp.com/&instance_id=13&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot 1.29.0; # requires 1.29.0 or above

#######################
# WARNING
# Running this code sample will cost you Browshot credits.
#######################



my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);



my $crawl = $browshot->crawl_create(url => 'https://blitapp.com/', domain => 'blitapp.com', max => 50, instance_id => 65, screen_width => 1600, screen_height => 1200, size => 'page'); # Get full size thumbnails
if ($crawl->{status} eq 'error') {
	print "Crawl failed: ", $crawl->{error}, "\n";
	exit(0);
}

print "Crawl #", $crawl->{id}, " in process\n";

sleep 30;
while ($crawl->{status} ne 'finished' && $crawl->{status} ne 'error') {
	sleep 15;
	$crawl = $browshot->crawl_info(id => $crawl->{id});
}

if ($crawl->{status} eq 'error') {
	print "crawl failed: ", $crawl->{error}, "\n";
	exit(0);
}

# The crawl succeeded, download the thumbnails.
foreach my $url (@{ $crawl->{urls} }) {
	print "Downloading ", $url->screenshot_url, "...\n";
	 $browshot->screenshot_thumbnail_file(id => $url->id, file => '/tmp/' + $url->id +'.png')
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$crawl = $browshot->crawl_create(array('url' => 'https://blitapp.com/', 'domain' => 'blitapp.com', max => 25, instance_id' => 65, 'screen_width' => 1600, 'screen_height' => 1200, 'size' => 'page')); # Get full size thumbnails
if ($crawl->{'status'} == 'error') {
	echo sprintf("Crawl failed: %s\n", $crawl->{'error'});
	exit(0);
}

echo sprintf("Crawl #%d in process\n", $crawl->{'id'});

sleep(30);
while ($crawl->{'status'} != 'finished' && $crawl->{'status'} != 'error') {
	sleep(15);
	$crawl = $browshot->crawl_info($crawl->{'id'});
}

if ($crawl->{'status'} == 'error') {
	echo sprintf("Crawl failed: %s\n", $crawl->{'error'});
	exit(0);
}

# The crawl succeeded, download the thumbnails.
foreach ($crawl->{'urls'} as $screenshot) {
	echo "Downloading $url...\n";
	# download the URL
  $browshot->screenshot_thumbnail_file($screenshot->{'id'}, "file-" . $screenshot->{'id'} . ".png", array('right' => 768, 'bottom' => 768, 'height' => 300, 'width' => 300, 'ratio' => 'fit'));
}


?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')


crawl = browshot.crawl_create("blitapp.com", "https://blitapp.com/", { 'instance_id': 65, 'screen_width': 1600, 'screen_height': 1200, 'size': 'page' }) # Get full size thumbnails
if crawl['status'] == 'error':
  print("Crawl failed: %s" % crawl['error'])
  exit(0)


print "Crawl #%d in process" % int(crawl['id'])

time.sleep(30)
while crawl['status'] != 'finished' and crawl['status'] != 'error':
  time.sleep(15)
  crawl = browshot.crawl_info(crawl['id'])


if crawl['status'] == 'error':
  print("crawl failed: %s" % crawl['error'])
  exit(0)

# The crawl succeeded, download the thumbnails
for screenshot in batch['urls']:
  print "Downloading screenshot %s..." % screenshot.id
  browshot.screenshot_thumbnail_file(screenshot['id'], "file.png", { 'right': 768, 'bottom': 768, 'height': 300, 'width': 300, 'ratio': 'fit' })

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

crawl = browshot.crawl_create(65, "blitapp.com", "https://blitapp.com/", { 'screen_width' => 1600, 'screen_height' => 1200, 'size' => 'page' }) # Get full size thumbnails
if (crawl['status'] == 'error')
  puts "Crawl failed: #{crawl['error']}\n"
  exit(0)
end

print "Crawl ##{crawl['id']} in process\n"

sleep(30)
while (crawl['status'] != 'finished' && crawl['status'] != 'error')
  sleep(15)
  crawl = browshot.crawl_info(crawl['id'])
end

if (crawl['status'] == 'error')
  puts "crawl failed: #{crawl['error']}\n"
  exit(0)
end

# The crawl succeeded, download the thumbnails
if (crawl.key?('urls'))
	crawl['urls'].each { |screenshot|
		puts "Downloading #{screenshot['id']}...\n"
    browshot.screenshot_thumbnail_file(screenshot['id'], "file-#{screenshot['id']}.png", { 'right' => 768, 'bottom' => 768, 'height' => 300, 'width' => 300, 'ratio' => 'fit' })
	}
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/

var browshot = require('browshot');
const fs = require("fs");

var client = new browshot('my_api_key');

var timeout;



function submitCrawl(file) {
	client.crawlCreate(
		"blitapp.com", "https://blitapp.com/", 65, { screen_width: 1600, screen_height: 1200, size: 'page' }, 
		function(crawl) {		
			if (crawl.status == 'error') {
				console.log("crawl failed: " + crawl.error);
			}
			else {
				console.log(`crawl #${crawl.id} in process`);
				
				// Check the status of the crawl every 30 seconds
				timeout = setInterval(checkCrawl , 1000 * 30, crawl.id);
			}
		}
	);
}

function checkCrawl(id) {
	client.crawlInfo(id, { }, function(crawl) {
		if (crawl.status == 'error') {
			clearInterval(timeout);
			
			console.log("crawl failed: " + crawl.error);
		}
		else if (crawl.status == 'finished') {
			clearInterval(timeout);
			
			// The crawl succeeded, download the thumbnails.
			for(var screenshot of crawl.urls) {
				console.log(`Downloading ${screenshot.id}  ...`);
        client.screenshotThumbnailFile(screenshot.id, `file-${screenshot.id}.png`, { zoom: 33 }, function(file) {
          console.log(`Thumbnail saved to ${file}`);
        });
			}
		}
		else {
			console.log(`Waiting for crawl ${crawl.id} to finish`);
		}
	});
}

Download code sample


Response

See /api/v1/crawl/info for the details.

{
  "status": "error",
  "error" : "Invalid crawl ID"
}
{
  "status": "finished",
  "id": 5
  "domain" : "blitapp.com",
  "url" :"https://blitapp.com/",
  "max": 100,
  "started"
  "finished":
  "count":  50,
  "processed": 50,
  "failed": 2,
  "urls": [
    {
      "id": 12589,
      "status": "finished",
      "screenshot_url": "https://browshot.com/screenshot/image/15/12589?scale=1&key=API_KEY",
      "priority": 12,
      "url": "http://blitapp.com/",
      "size": "screen",
      "width": 1024,
      "height": 768,
      "request_time": 1312106111,
      "started": 1312258803994,
      "load": 1312258829461,
      "content": 1312258829661,
      "finished": 1312258829681,
      "instance_id": 12,
      "response_code": 200,
      "final_url": "http://blitapp.com/",
      "content_type": "text/html",
      "scale": "1",
      "cost": 0,
      "referer": "",
      "post_data": "",
      "cookie": "",
      "delay": 5,
      "script": "",
      "shared_url": "",
      "details": 3
    },
    ...
  ]
}



/api/v1/crawl/info (new 1.29)

Get the status of a crawl requested through the API or the dashboard.


Request

Parameters:

  • id: crawl ID



Examples

https://api.browshot.com/api/v1/crawl/info?id=5&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot 1.29.0; # requires 1.29.0 or above

#######################
# WARNING
# Running this code sample will cost you Browshot credits.
#######################



my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);



my $crawl = $browshot->crawl_create(url => 'https://blitapp.com/', domain => 'blitapp.com', max => 50, instance_id => 65, screen_width => 1600, screen_height => 1200, size => 'page'); # Get full size thumbnails
if ($crawl->{status} eq 'error') {
	print "Crawl failed: ", $crawl->{error}, "\n";
	exit(0);
}

print "Crawl #", $crawl->{id}, " in process\n";

sleep 30;
while ($crawl->{status} ne 'finished' && $crawl->{status} ne 'error') {
	sleep 15;
	$crawl = $browshot->crawl_info(id => $crawl->{id});
}

if ($crawl->{status} eq 'error') {
	print "crawl failed: ", $crawl->{error}, "\n";
	exit(0);
}

# The crawl succeeded, download the thumbnails.
foreach my $url (@{ $crawl->{urls} }) {
	print "Downloading ", $url->screenshot_url, "...\n";
	 $browshot->screenshot_thumbnail_file(id => $url->id, file => '/tmp/' + $url->id +'.png')
}

Download code sample

<?php

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$crawl = $browshot->crawl_create(array('url' => 'https://blitapp.com/', 'domain' => 'blitapp.com', max => 25, instance_id' => 65, 'screen_width' => 1600, 'screen_height' => 1200, 'size' => 'page')); # Get full size thumbnails
if ($crawl->{'status'} == 'error') {
	echo sprintf("Crawl failed: %s\n", $crawl->{'error'});
	exit(0);
}

echo sprintf("Crawl #%d in process\n", $crawl->{'id'});

sleep(30);
while ($crawl->{'status'} != 'finished' && $crawl->{'status'} != 'error') {
	sleep(15);
	$crawl = $browshot->crawl_info($crawl->{'id'});
}

if ($crawl->{'status'} == 'error') {
	echo sprintf("Crawl failed: %s\n", $crawl->{'error'});
	exit(0);
}

# The crawl succeeded, download the thumbnails.
foreach ($crawl->{'urls'} as $screenshot) {
	echo "Downloading $url...\n";
	# download the URL
  $browshot->screenshot_thumbnail_file($screenshot->{'id'}, "file-" . $screenshot->{'id'} . ".png", array('right' => 768, 'bottom' => 768, 'height' => 300, 'width' => 300, 'ratio' => 'fit'));
}


?>

Download code sample

# -*- coding: utf-8 -*-
#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

from browshot import BrowshotClient
import time

browshot = BrowshotClient('my_api_key')


crawl = browshot.crawl_create("blitapp.com", "https://blitapp.com/", { 'instance_id': 65, 'screen_width': 1600, 'screen_height': 1200, 'size': 'page' }) # Get full size thumbnails
if crawl['status'] == 'error':
  print("Crawl failed: %s" % crawl['error'])
  exit(0)


print "Crawl #%d in process" % int(crawl['id'])

time.sleep(30)
while crawl['status'] != 'finished' and crawl['status'] != 'error':
  time.sleep(15)
  crawl = browshot.crawl_info(crawl['id'])


if crawl['status'] == 'error':
  print("crawl failed: %s" % crawl['error'])
  exit(0)

# The crawl succeeded, download the thumbnails
for screenshot in batch['urls']:
  print "Downloading screenshot %s..." % screenshot.id
  browshot.screenshot_thumbnail_file(screenshot['id'], "file.png", { 'right': 768, 'bottom': 768, 'height': 300, 'width': 300, 'ratio': 'fit' })

Download code sample

#!/usr/bin/env ruby

#######################
# WARNING
# Running this code sample will cost you Browshot credits
#######################

require 'browshot'

browshot = Browshot.new('my_api_key')

crawl = browshot.crawl_create(65, "blitapp.com", "https://blitapp.com/", { 'screen_width' => 1600, 'screen_height' => 1200, 'size' => 'page' }) # Get full size thumbnails
if (crawl['status'] == 'error')
  puts "Crawl failed: #{crawl['error']}\n"
  exit(0)
end

print "Crawl ##{crawl['id']} in process\n"

sleep(30)
while (crawl['status'] != 'finished' && crawl['status'] != 'error')
  sleep(15)
  crawl = browshot.crawl_info(crawl['id'])
end

if (crawl['status'] == 'error')
  puts "crawl failed: #{crawl['error']}\n"
  exit(0)
end

# The crawl succeeded, download the thumbnails
if (crawl.key?('urls'))
	crawl['urls'].each { |screenshot|
		puts "Downloading #{screenshot['id']}...\n"
    browshot.screenshot_thumbnail_file(screenshot['id'], "file-#{screenshot['id']}.png", { 'right' => 768, 'bottom' => 768, 'height' => 300, 'width' => 300, 'ratio' => 'fit' })
	}
end

Download code sample

/**********************
* WARNING
* Running this code sample will cost you Browshot credits
***********************/

var browshot = require('browshot');
const fs = require("fs");

var client = new browshot('my_api_key');

var timeout;



function submitCrawl(file) {
	client.crawlCreate(
		"blitapp.com", "https://blitapp.com/", 65, { screen_width: 1600, screen_height: 1200, size: 'page' }, 
		function(crawl) {		
			if (crawl.status == 'error') {
				console.log("crawl failed: " + crawl.error);
			}
			else {
				console.log(`crawl #${crawl.id} in process`);
				
				// Check the status of the crawl every 30 seconds
				timeout = setInterval(checkCrawl , 1000 * 30, crawl.id);
			}
		}
	);
}

function checkCrawl(id) {
	client.crawlInfo(id, { }, function(crawl) {
		if (crawl.status == 'error') {
			clearInterval(timeout);
			
			console.log("crawl failed: " + crawl.error);
		}
		else if (crawl.status == 'finished') {
			clearInterval(timeout);
			
			// The crawl succeeded, download the thumbnails.
			for(var screenshot of crawl.urls) {
				console.log(`Downloading ${screenshot.id}  ...`);
        client.screenshotThumbnailFile(screenshot.id, `file-${screenshot.id}.png`, { zoom: 33 }, function(file) {
          console.log(`Thumbnail saved to ${file}`);
        });
			}
		}
		else {
			console.log(`Waiting for crawl ${crawl.id} to finish`);
		}
	});
}

Download code sample


Response

{
  "status": "error",
  "error" : "Wrong crawl ID"
}
{
  "status": "in_queue",
  "id": 5
  "domain" : "blitapp.com",
  "url" :"https://blitapp.com/",
  "max": 100,
  "started"
  "finished":
  "count":  1,
  "processed": 0,
  "failed": 0,
  "urls": [
    {
      "id": 12589,
      "status": "in_queue",
      "screenshot_url": "https://browshot.com/screenshot/image/15/12589?scale=1&key=API_KEY",
      "url": "http://blitapp.com/",
      "size": "screen",
      "instance_id": 12,
      "content_type": "text/html",
      "cost": 0,
      "referer": "",
      "post_data": "",
      "cookie": "",
      "delay": 5,
      "script": "",
      "shared_url": "",
      "details": 3
    },
    ...
  ]
}
{
  "status": "in_process",
  "id": 5
  "domain" : "blitapp.com",
  "url" :"https://blitapp.com/",
  "max": 100,
  "started"
  "finished":
  "count":  25,
  "processed": 12,
  "failed": 0,
  "urls": [
    {
      "id": 12589,
      "status": "finished",
      "screenshot_url": "https://browshot.com/screenshot/image/15/12589?scale=1&key=API_KEY",
      "priority": 12,
      "url": "http://blitapp.com/",
      "size": "screen",
      "width": 1024,
      "height": 768,
      "request_time": 1312106111,
      "started": 1312258803994,
      "load": 1312258829461,
      "content": 1312258829661,
      "finished": 1312258829681,
      "instance_id": 12,
      "response_code": 200,
      "final_url": "http://blitapp.com/",
      "content_type": "text/html",
      "scale": "1",
      "cost": 0,
      "referer": "",
      "post_data": "",
      "cookie": "",
      "delay": 5,
      "script": "",
      "shared_url": "",
      "details": 3
    },
    ...
  ]
}
{
  "status": "finished",
  "id": 5
  "domain" : "blitapp.com",
  "url" :"https://blitapp.com/",
  "max": 100,
  "started"
  "finished":
  "count":  50,
  "processed": 50,
  "failed": 2,
  "urls": [
    {
      "id": 12589,
      "status": "finished",
      "screenshot_url": "https://browshot.com/screenshot/image/15/12589?scale=1&key=API_KEY",
      "priority": 12,
      "url": "http://blitapp.com/",
      "size": "screen",
      "width": 1024,
      "height": 768,
      "request_time": 1312106111,
      "started": 1312258803994,
      "load": 1312258829461,
      "content": 1312258829661,
      "finished": 1312258829681,
      "instance_id": 12,
      "response_code": 200,
      "final_url": "http://blitapp.com/",
      "content_type": "text/html",
      "scale": "1",
      "cost": 0,
      "referer": "",
      "post_data": "",
      "cookie": "",
      "delay": 5,
      "script": "",
      "shared_url": "",
      "details": 3
    },
    ...
  ]
}

  • status: status of the crawl: "in_queue", "processing", "finished", "error"

  • id: crawl ID

  • started: time of processing (UNIX timestamp)

  • finished: time of crawl completed (UNIX timestamp)

  • count: number of unique URLs in the crawl. This number will change while the crawl is in process.

  • max: maximum number of unique URLs requested

  • processed: number of screenshots finished

  • failed: number of screenshots failed

  • urls: list of URLs in the crawl as described in screenshot/info




Account API

/api/v1/account/info

Get information about your account.


Request

Parameters:

  • details (optional, 1-3, default: 1): level of the information returned



Example

https://api.browshot.com/api/v1/account/info?details=3&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $account = $browshot->account_info();

# Check my balance
print "Free screenshots left for this month: ", $account->{free_screenshots_left}, "\n";
print "Credits left: ", $account->{balance}, "\n";

if ($account->{balance} < 100) {
	# Send an alarm when the balance is low
}

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$account = $browshot->account_info();

# Check my balance
echo sprintf("Free screenshots left for this month: %d\n", $account->{'free_screenshots_left'});
echo sprintf("Credits left: %d\n", $account->{'balance'});

if ($account->{'balance'} < 100) {
	# Send an alarm when the balance is low
}

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


account = browshot.account_info()

# Check my balance
print "Free screenshots left for this month: %d" % int(account['free_screenshots_left'])
print "Credits left: %d\n" % int(account['balance'])

if int(account['balance']) < 100:
  # Send an alarm when the balance is low
  print "balance is low"

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


account = browshot.account_info()

# Check my balance
puts "Free screenshots left for this month: #{account['free_screenshots_left']}\n"
puts "Credits left: #{account['balance']}\n"

if (account['balance'].to_i < 100)
  # Send an alarm when the balance is low
  puts "balance is low\n"
end

Download code sample

var browshot = require('browshot');

var client = new browshot('my_api_key');


client.accountInfo({ }, function(info) {
	// Check my balance
	console.log("Free screenshots left for this month: " + info.free_screenshots_left);
	console.log("Credits left: " + info.balance);
	
	// Send an alarm when the balance is low
	if (info.balance < 100) {
		console.log("balance is low");
	}
});

Download code sample


Response
{
  "balance":0,
  "instances":[],
  "screenshots":[
    {"width":1024,
    "priority":1,
    "status":"finished",
    "content":1320989264533,
    "size":"screen",
    "url":"http://www.free.fr/",
    "id":10,
    "screenshot_url":"http://127.0.0.1:3000/screenshot/image/10?key=my_api_key",
    "load":1320989268347,
    "request_time":1320989261,
    "instance_id":12,
    "height":768,
    "response_code":200,
    "final_url":"http://www.free.fr/adsl/index.html",
    "content_type":"text/html",
    "scale":1,
    "started":1320989261960,
    "finished":1320989273508
    }
  ],
  "browsers":[
    {"appversion":"",
    "user_agent":"custom",
    "name":"Custom browser",
    "javascript":0,
    "mobile":0,
    "appname":"",
    "vendorsub":"",
    "appcodename":"",
    "platform":"",
    "vendor":""
    }
   ],
  "free_screenshots_left": 85,
  "private_instances": 0,
  "hosting_browshot": 0
}
  • balance: number of credits left on your account

  • free_screenshots_left: number of free screenshots available for the current month

  • private_instances: 1 is your account is authorized to create and use private instances, 0 otherwise (default)

  • hosting_browshot: 1 is your account is authorized to request hosting on Browshot, 0 otherwise (default)



If details=2, additional information is sent:



If details=3, additional information is sent:




Instance API

You can get the list of instances available.
(The creation of new private instances is available to some users only, please contact us if you think you need private instances.)

/api/v1/instance/list

Request

No parameters.


Example:

https://api.browshot.com/api/v1/instance/list?key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $instances = $browshot->instance_list();

# Check the list of free browser
print "Free browsers:\n";
foreach my $instance (@{ $instances->{free} }) {
	my $id = $instance->{id};
	print "\t#$id: ", $instance->{browser}->{name}, " ", $instance->{width}, "x", $instance->{height}, "\n";
}

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$instances = $browshot->instance_list();

# Check the list of free browser
echo "Free browsers:\n";
foreach ($instances->{'free'} as $instance) {
	$id = $instance->{'id'};
	echo "\t#$id: " . $instance->{'browser'}->{'name'} . " ", $instance->{'width'} . "x", $instance->{'height'} . "\n";
}

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


instances = browshot.instance_list()

# Check the list of free browser
print "Free browsers:"
for instance in instances['free']:
  print "\t#" + instance['id'] + ": " + instance['browser']['name'] + " ", instance['width'] + "x" + instance['height']

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


instances = browshot.instance_list()

# Check the list of free browser
puts "Free browsers:"
instances['free'].each { |instance|
  puts "\t##{instance['id']}: #{instance['browser']['name']} #{instance['width']}x#{instance['height']}\n"
}

Download code sample

var browshot = require('browshot');

var client = new browshot('my_api_key');


client.instanceList(function(list) {
	// Check the list of free browsers
	console.log("Free instances:");
	for(var i in list.free) {
		console.log(`\t#${list.free[i].id}: ${list.free[i].browser.name} ${list.free[i].width}x${list.free[i].height}`);
	}
});

Download code sample


Response

The instances are divided into 3 types:

  • free: free instances available to all registered users.

  • shared: instances available to all registered users with a positive balance. Each screenshot requested for these instances has a cost.

  • private: custom instances created for a specific user. Each screenshot requested for these instances has a cost.



Example:

{
  "shared":[],
  "free":[{
    "width":1024,
    "height":768,
    "browser":{
      "id": 3,
      "name":"Firefox",
      "javascript":1,
      "mobile":0
     },
     "type":"public",
     "id":11,
     "load":"0.5",
     "screenshot_cost":1,
     "country":"USA"
  }],
  "private":[]
}
  • id: instance ID (required to request screenshots)

  • width: screen width in pixels

  • height: screen height in pixels

  • load: instance load

    • < 1: new screenshot requests will be processed immediately

    • 1-2: new screenshot requests will be processed in about two minutes

    • 2-3: new screenshot requests will be processed in about four minutes

    • 3-4: new screenshot requests will be processed in about six minutes

    • etc.

  • browser: virtual browser features

    • id: browser ID

    • name: browser name and version: Firefox 20.0.1, etc.

    • javascript: JavaScript support: 1 if enabled, 0 if disabled

    • mobile: Mobile browser: 1 if true, 0 if false

  • type: public, shared or private

  • screenshot_cost: number of credits for each screenshot

  • country: instance's country of origin




/api/v1/instance/info

Request

Parameters:

  • id: instance ID


Example:

https://api.browshot.com/api/v1/instance/info?id=12&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $instance = $browshot->instance_info(id => 12);

print "Instance #12 costs ", $instance->{screenshot_cost}, " credit(s) per screenshot.\n";
if ($instance->{load} < 1) {
	print "New screenshots requests will be handled immediately.\n";
}
else {
	print "There may be some delay to start processing new screenshot requests.\n";
}

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$instance = $browshot->instance_info(12);

echo sprintf("Instance #12 costs %d credit(s) per screenshot.\n", $instance->{'screenshot_cost'});
if ($instance->{'load'} < 1) {
	echo "New screenshots requests will be handled immediately.\n";
}
else {
	echo "There may be some delay to start processing new screenshot requests.\n";
}

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


instance = browshot.instance_info(12)

print "Instance #12 costs %d credit(s) per screenshot." % int(instance['screenshot_cost'])
if instance['load'] < 1:
  print "New screenshots requests will be handled immediately."
else:
  print "There may be some delay to start processing new screenshot requests."

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


instance = browshot.instance_info(12)

puts "Instance #12 costs #{instance['screenshot_cost']} credit(s) per screenshot.\n"
if (instance['load'].to_i < 1)
  puts "New screenshots requests will be handled immediately.\n"
else
  puts "There may be some delay to start processing new screenshot requests.\n"
end

Download code sample

var browshot = require('browshot');

var client = new browshot('my_api_key');

client.instanceInfo(12, function(instance) {
	console.log(`Instance #12 costs ${instance.screenshot_cost} credit(s) per screenshot.`);
});

Download code sample


Response
{
  "error": "Instance not found",
  "status": "error"
}
{
  "width":1024,
  "height":768,
  "browser":{
    "id": 3,
    "name":"Firefox",
    "javascript":1,
    "mobile":0
  },
  "type":"public",
  "id":11,
  "load":"0.5",
  "active":1,
  "screenshot_cost":1,
  "country":"Australia"
}

  • id: instance ID (required to request screenshots)

  • width: screen width in pixels

  • height: screen height in pixels

  • load: instance load

    • < 1: new screenshot requests will be processed immediately

    • 1-2: new screenshot requests will be processed in about two minutes

    • 2-3: new screenshot requests will be processed in about four minutes

    • 3-4: new screenshot requests will be processed in about six minutes

    • etc.

  • browser: virtual browser features

    • id: browser ID

    • name: browser name and version: Firefox 24.0.1, etc.

    • javascript: JavaScript support: 1 if enabled, 0 if disabled

    • mobile: Mobile browser: 1 if true, 0 if false

  • type: public, shared or private

  • screenshot_cost: number of credits for each screenshot

  • country: instance's country of origin




Browser API

Each instance can use a different user agent.

/api/v1/browser/list

List of all predefined web browsers. You can get the list of predefined browsers and create new browsers for your private instances.


Request

No parameters.


Example:

https://api.browshot.com/api/v1/browser/list?key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $browsers = $browshot->browser_list();

foreach my $id (keys %{ $browsers }) {
	my $browser = $browsers->{$id};
	print "Browser ", $browser->{name}, ":\n";
	print "\tmobile\n" if ($browser->{mobile} == 1);
	print "\n";
}

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');

$browsers = $browshot->browser_list();

foreach ($browsers as $id => $browser) {
	echo "Browser ". $browser->{'name'} . ":\n";
	if ($browser->{'mobile'} == 1) echo "\tmobile\n" ;
	echo "\n";
}

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


browsers = browshot.browser_list()

for id, browser in browsers.iteritems():
  print "Browser " + browser['name'] + ":"
  if browser['mobile'] == 1:
    print "\tmobile\n"
  print ""

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')

browsers = browshot.browser_list()

browsers.each { |id, browser|
  puts "Browser #{browser['name']}:\n"
  
  if (browser['mobile'].to_i == 1)
    puts "\tmobile\n"
  end
  
  puts "\n"
}

Download code sample

var browshot = require('browshot');

var client = new browshot('my_api_key');

client.browserList(function(list) {
	for(var id in list) {
		console.log(`Browser ${list[id].name}`);
		if (list[id].mobile == 1)
			console.log("\tmobile");
	}

});

Download code sample


Response

{
  "6":{
    "name":"Yahoo Slurp",
    "user_agent":"Mozilla/5.0 (compatible; Yahoo! Slurp; http://help.yahoo.com/help/us/ysearch/slurp)",
    "appname":"",
    "vendorsub":"",
    "appcodename":"",
    "platform":"",
    "vendor":"",
    "appversion":"",
    "javascript":0,
    "mobile":0
  },
  "11":{
    "name":"Android Nesus S",
    "user_agent":"Mozilla/5.0 (Linux; U; Android 2.3.4; en-us; Nexus S Build/GRJ22) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1",
    "appname":"",
    "vendorsub":"",
    "appcodename":"",
    "platform":"",
    "vendor":"",
    "appversion":"",
    "javascript":1,
    "mobile":1
  }
}

The key is the browser ID (same ID as in /api/v1/instance/list)

  • name: browser name and version: Firefox 24.0.1, etc.

  • user_agent: browser user agent string

  • appname, vendorsub, appcodename, platform, vendor, appversion: user agent identifiers

  • javascript: JavaScript support: 1 if enabled, 0 if disabled

  • mobile: Mobile browser: 1 if true, 0 if false




/api/v1/browser/info

Request

Parameters:

  • id: browser ID


Example:

https://api.browshot.com/api/v1/browser/info?id=6&key=my_api_key

#!/usr/bin/perl -w

use strict;
use warnings;
use Carp;

use WebService::Browshot;


my $browshot = WebService::Browshot->new(
	key	=> 'my_api_key',
	debug	=> 0, # no more debug information
);

my $instance = $browshot->instance_info(id => 12);

# Get details on the browser behind this instance
my $browser = $browshot->browser_info(id => $instance->{browser}->{id});

print "Instance #12 uses the browser ", $browser->{name}, "\n";
print "User Agent string: ", $browser->{user_agent} || 'default', "\n";

Download code sample

<?php

require 'vendor/autoload.php'; # Composer
# require_once 'Browshot.php'; # or download Browshot.php

$browshot = new Browshot('my_api_key');


$instance = $browshot->instance_info(12);

# Get details on the browser behind this instance
$browser = $browshot->browser_info($instance->{'browser'}->{'id'});

echo "Instance #12 uses the browser " . $browser->{'name'} . "\n";
echo "User Agent string: " . $browser->{'user_agent'} || 'default' . "\n";

?>

Download code sample

# -*- coding: utf-8 -*-

from browshot import BrowshotClient

browshot = BrowshotClient('my_api_key')


instance = browshot.instance_info(12)

# Get details on the browser behind this instance
browser = browshot.browser_info(instance['browser']['id'])

print "Instance #12 uses the browser " + browser['name']
print "User Agent string: " + browser['user_agent']

Download code sample

#!/usr/bin/env ruby

require 'browshot'

browshot = Browshot.new('my_api_key')


instance = browshot.instance_info(12)

# Get details on the browser behind this instance
browser = browshot.browser_info(instance['browser']['id'])

puts "Instance #12 uses the browser #{browser['name']}\n"
puts "User Agent string: #{browser['user_agent']}\n"

Download code sample

var browshot = require('browshot');

var client = new browshot('my_api_key');

client.instanceInfo(12, function(instance) {
	// Get details on the browser behind this instance
	var browser_id = instance.browser.id;
	
	client.browserInfo(instance.browser.id, function(browser) {
		console.log(`Instance #12 uses the browser ${browser.name}`);
		console.log(`User Agent string: ${browser.user_agent}`);
	});
});




Download code sample


Response
{
  "error": "Browser not found",
  "status": "error"
}
{
  "name":"Yahoo Slurp",
  "user_agent":"Mozilla/5.0 (compatible; Yahoo! Slurp; http://help.yahoo.com/help/us/ysearch/slurp)",
  "appname":"",
  "vendorsub":"",
  "appcodename":"",
  "platform":"",
  "vendor":"",
  "appversion":"",
  "javascript":0,
  "mobile":0
}

  • name: browser name and version: Firefox 24.0.1, etc.

  • user_agent: browser user agent string

  • appname, vendorsub, appcodename, platform, vendor, appversion: user agent identifiers

  • javascript: JavaScript support: 1 if enabled, 0 if disabled

  • mobile: Mobile browser: 1 if true, 0 if false