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.16

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.

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

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 used a premium instance, use instance_id=65 for example.


You can add any of the arguments that is 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 (update 1.16)

Screenshots 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 24hours. Specify cache=0 if you want a new screenshot.

  • delay=0-120 (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.

  • flash_delay=0-30 (default: 10): number of seconds to wait after the page has loaded if Flash elements are present. Use flash_delay=0 to take screenshots faster.

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

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



Optional parameters:

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

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

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

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

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

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

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

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

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



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 width of the thumbnail to host

  • hosting_width (optional): maximum height 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


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


Multiple screenshots
You can take multiple screenshots of the same page at a specific interval with these additional parameters:

  • shots (1-10, default: 1): take multiple screenshots of the same page. This costs 1 additional credit for every 2 additional screenshots.

  • shot_interval (1-10, default: 5): number of seconds between 2 screenshots


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 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=3&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


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": "10",
  "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",
  "flash_delay": "10",
  "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

  • error: description of the problem that occurred

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

  • url: original URL requested

  • size: screenshot size requested

  • width: screenshot width

  • height: screenshot height

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

  • 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

  • instance_id instance ID used for the screenshot

  • cost: number of credits spent for the screenshot

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

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

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

  • delay: number of seconds to wait after page load

  • flash_delay: number of seconds to wait after page load if Flash elements are present

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

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



If details=1, additional information is sent:


  • 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.)



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



/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/create?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/create?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


Response

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




/api/v1/screenshot/info

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: 2): 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


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": "10",
	  "response_code": "",
	  "final_url": "",
	  "content_type":"",
	  "scale":"1",
	  "cost": "0",
	  "referer": "",
	  "post_data": "",
	  "cookie: "",
	  "delay": "5",
	  "flash_delay": "10",
	  "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": "10",
	  "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",
	  "flash_delay": "10",
	  "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

  • error: description of the problem that occurred

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

  • url: original URL requested

  • size: screenshot size requested

  • width: screenshot width

  • height: screenshot height

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

  • 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

  • instance_id instance ID used for the screenshot

  • cost: number of credits spent for the screenshot

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

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

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

  • delay: number of seconds to wait after page load

  • flash_delay: number of seconds to wait after page load if Flash elements are present

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

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

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


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"
    }
  ]
}
  • status: status of the request: "error", "finished"

  • url: URL to the hosted screenshot or thumbnail

  • hosting: hosting option chosen

  • width: thumbnail width specified (if any)

  • height: thumbnail height specified (if any)

  • scale: thumbnail scale specified (if any)

  • bucket: bucket specified (S3 only)

  • file: file name specified (if any, S3 only)



If details=1, additional information is sent:

  • 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.)



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, 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




/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 list of screenshot in a given status (error, finished, in_process)



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


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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "script": "",
    "shared_url": ""
  }
}


The key is the screenshot ID

  • id: screenshot ID

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

  • screenshot_url: URL to download the screenshot

  • error: description of the problem that occurred

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

  • url: original URL requested

  • size: screenshot size requested

  • width: screenshot width

  • height: screenshot height

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

  • 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

  • instance_id instance ID used for the screenshot

  • cost: number of credits spent for the screenshot

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

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

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

  • delay: number of seconds to wait after page load

  • flash_delay: number of seconds to wait after page load if Flash elements are present

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

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

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



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=1, additional information is sent:

  • 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.)



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, 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




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 list of screenshot in a given status (error, finished, in_process)



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


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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.org/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.de/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.fr/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "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": "10",
    "response_code": "200",
    "final_url": "http://www.google.com/",
    "content_type":"text/html",
    "scale": "1",
    "cost": "0",
    "referer": "",
    "post_data": "",
    "cookie": "",
    "delay": "5",
    "flash_delay": "10",
    "script": "",
    "shared_url": ""
  }
}


The key is the screenshot ID

  • id: screenshot ID

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

  • screenshot_url: URL to download the screenshot

  • error: description of the problem that occurred

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

  • url: original URL requested

  • size: screenshot size requested

  • width: screenshot width

  • height: screenshot height

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

  • 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

  • instance_id instance ID used for the screenshot

  • cost: number of credits spent for the screenshot

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

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

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

  • delay: number of seconds to wait after page load

  • flash_delay: number of seconds to wait after page load if Flash elements are present

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

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

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




/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

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


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), or 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 ration, 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




/api/v1/screenshot/share

You can make your screenshots public, add notes, and share it with your friends and colleagues. Only screenshots which are successfully 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


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


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 calls 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





/api/v1/batch/create

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" in order 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.



Request

Required parameters:

  • instance_id: instance ID to use

  • file: file content


Optional parameters:

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

  • name: name of the batch

  • width: screenshot width

  • height: screenshot height

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

  • delay=0-120 (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

  • flash_delay=0-30 (default: 10): number of seconds to wait after the page has loaded if Flash elements are present. Use flash_delay=0 to take screenshots faster

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

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

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

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

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

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

  • shots (1-3, default: 1): take 2 or 3 screenshots of the same page. This costs 1 credit

  • shot_interval (1-10, default: 5): number of seconds between 2 screenshots



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


Response

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

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



/api/v1/batch/info (update 1.15)

Get the status of a batch requested through the API or through 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 fore 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


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
}
{
  "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 (new 1.15): URLs to download the batch




Account API

/api/v1/account/info

Get information about your account.


Request

Parameters:

  • details (optional, 1-3, default: 1): level of 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


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":"",
    "flash":"0"
    }
   ],
  "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


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",
      "flash":"1"
     },
     "type":"public",
     "id":"11",
     "load":"0.5",
     "screenshot_cost":"1",
     "country":"USA"
  }],
  "private":[]
}
  • id: instance ID (required to requests 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

    • flash: Flash 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=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 $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


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

  • id: instance ID (required to requests 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

    • flash: Flash 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 "\tFlash\n" if ($browser->{flash} == 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" ;
	if ($browser->{'flash'} == 1) echo "\tFlash\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"
  if browser['flash'] == 1:
    print "\tFlash\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
  
  if (browser['flash'].to_i == 1)
    puts "\tFlash\n"
  end
  
  puts "\n"
}

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",
    "flash":"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":"",
    "flash":"0",
    "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

  • flash: Flash 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


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",
  "flash":"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

  • flash: Flash support: 1 if enabled, 0 if disabled

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