NAME

WebService::Browshot - Perl extension for Browshot (https://browshot.com/), a web service to create screenshots of web pages.

SYNOPSIS

use WebService::Browshot;

my $browshot = WebService::Browshot->new(key => 'my_key');
my $screenshot = $browshot->screenshot_create(url => 'http://www.google.com/');
[...]
$browshot->screenshot_thumbnail_file(id => $screenshot->{id}, file => 'google.png');

DESCRIPTION

Browshot (http://www.browshot.com/) is a web service to easily make screenshots of web pages in any screen size, as any device: iPhone, iPad, Android, Nook, PC, etc. Browshot has full Flash, JavaScript, CSS, & HTML5 support.

The latest API version is detailed at http://browshot.com/api/documentation. WebService::Browshot follows the API documentation very closely: the function names are similar to the URLs used (screenshot/create becomes screenshot_create(), instance/list becomes instance_list(), etc.), the request arguments are exactly the same, etc.

The library version matches closely the API version it handles: WebService::Browshot 1.0.0 is the first release for the API 1.0, WebService::Browshot 1.1.1 is the second release for the API 1.1, etc.

WebService::Browshot can handle most the API updates within the same major version, e.g. WebService::Browshot 1.0.0 should be compatible with the API 1.1 or 1.2.

The source code is available on github at https://github.com/juliensobrier/browshot-perl.

METHODS

new()

my $browshot = WebService::Browshot->new(key => 'my_key', base => 'http://api.browshot.com/api/v1/', debug => 1]);

Create a new WebService::Browshot object. You must pass your API key (go to you Dashboard to find your API key).

Arguments:

key

Required. API key.

base

Optional. Base URL for all API requests. You should use the default base provided by the library. Be careful if you decide to use HTTP instead of HTTPS as your API key could be sniffed and your account could be used without your consent.

debug

Optional. Set to 1 to print debug output to the standard output. 0 (disabled) by default.

timeout

Optional. Set the request timeout - in seconds - against the API. Defaults to 90s.

last_error contains the last error message, it is NEVER reset, i.e last_error may not be empty after a successful API call if an earlier call failed.

api_version()

Return the API version handled by the library. Note that this library can usually handle new arguments in requests without requiring an update.

simple()

$browshot->simple(url => 'http://mobilito.net')

Retrieve a screenshot in one function. Note: by default, screenshots are cached for 24 hours. You can tune this value with the cache=X parameter.

Return an array (status code, PNG). See http://browshot.com/api/documentation#simple for the list of possible status codes.

Arguments:

See http://browshot.com/api/documentation#simple for the full list of possible arguments.

url

Required. URL of the website to create a screenshot of.

simple_file()

$browshot->simple_file(url => 'http://mobilito.net', file => '/tmp/mobilito.png')

Retrieve a screenshot and save it locally in one function. Note: by default, screenshots are cached for 24 hours. You can tune this value with the cache=X parameter.

Return an array (status code, file name). The file name is empty if the screenshot was not retrieved. See http://browshot.com/api/documentation#simple for the list of possible status codes.

Arguments:

See http://browshot.com/api/documentation#simple for the full list of possible arguments.

url

Required. URL of the website to create a screenshot of.

file

Required. Local file name to write to.

instance_list()

Return the list of instances as a hash reference. See http://browshot.com/api/documentation#instance_list for the response format.

instance_info()

$browshot->instance_info(id => 2)

Return the details of an instance. See http://browshot.com/api/documentation#instance_info for the response format.

Arguments:

id

Required. Instance ID

browser_list()

Return the list of browsers as a hash reference. See http://browshot.com/api/documentation#browser_list for the response format.

browser_info()

$browshot->browser_info(id => 2)

Return the details of a browser. See http://browshot.com/api/documentation#browser_info for the response format.

Arguments:

id

Required. Browser ID

screenshot_create()

$browshot->screenshot_create(url => 'http://wwww.google.com/', instance_id => 3, size => 'page')

Request a screenshot. See http://browshot.com/api/documentation#screenshot_create for the response format. Note: by default, screenshots are cached for 24 hours. You can tune this value with the cache=X parameter.

Arguments:

See http://browshot.com/api/documentation#screenshot_create for the full list of possible arguments.

url

Required. URL of the website to create a screenshot of.

instance_id

Optional. Instance ID to use for the screenshot.

size

Optional. Screenshot size.

screenshot_info()

$browshot->screenshot_info(id => 568978)

Get information about a screenshot requested previously. See http://browshot.com/api/documentation#screenshot_info for the response format.

Arguments:

id

Required. Screenshot ID.

screenshot_list()

$browshot->screenshot_list(limit => 50)

Get details about screenshots requested. See http://browshot.com/api/documentation#screenshot_list for the response format.

Arguments:

limit

Optional. Maximum number of screenshots to retrieve.

screenshot_search()

$browshot->screenshot_search(url => 'google.com')

Get details about screenshots requested. See http://browshot.com/api/documentation#screenshot_search for the response format.

Arguments:

url

Required. URL string to look for.

screenshot_host()

$browshot->screenshot_host(id => 12345, hosting => 'browshot')

Host a screenshot or thumbnail. See http://browshot.com/api/documentation#screenshot_host for the response format.

Arguments:

id

Required. Screenshot ID.

screenshot_thumbnail()

$browshot->screenshot_thumbnail(id => 52942, width => 500)

Retrieve the screenshot, or a thumbnail. See http://browshot.com/api/documentation#screenshot_thumbnail for the response format.

Return an empty string if the image could not be retrieved.

Arguments:

See http://browshot.com/api/documentation#screenshot_thumbnail for the full list of possible arguments.

id

Required. Screenshot ID.

width

Optional. Maximum width of the thumbnail.

height

Optional. Maximum height of the thumbnail.

screenshot_thumbnail_file()

$browshot->screenshot_thumbnail_file(id => 123456, height => 500, file => '/tmp/google.png')

Retrieve the screenshot, or a thumbnail, and save it to a file. See http://browshot.com/api/documentation#thumbnails for the response format.

Return an empty string if the image could not be retrieved or not saved. Returns the file name if successful.

Arguments:

See http://browshot.com/api/documentation#thumbnails for the full list of possible arguments.

url

Required. URL of the screenshot (screenshot_url value retrieved from C<screenshot_create()> or C<screenshot_info()>). You will get the full image if no other argument is specified.

file

Required. Local file name to write to.

width

Optional. Maximum width of the thumbnail.

height

Optional. Maximum height of the thumbnail.

screenshot_share()

$browshot->screenshot_share(id => 12345, note => 'This is my screenshot')

Share a screenshot. See http://browshot.com/api/documentation#screenshot_share for the response format.

Arguments:

id

Required. Screenshot ID.

note

Optional. Public note to add to the screenshot.

screenshot_delete()

$browshot->screenshot_delete(id => 12345, data => 'url,metadata')

Delete details of a screenshot. See http://browshot.com/api/documentation#screenshot_delete for the response format.

Arguments:

id

Required. Screenshot ID.

data

Optional. Information to delete.

screenshot_html()

$browshot->screenshot_html(id => 12345)

Get the HTML code of the rendered page. See http://browshot.com/api/documentation#screenshot_html for the response format.

Arguments:

id

Required. Screenshot ID.

screenshot_multiple()

$browshot->screenshot_multiple(urls => ['http://mobilito.net/'], instances => [22, 30])

Request multiple screenshots. See http://browshot.com/api/documentation#screenshot_multiple for the response format.

Arguments:

urls

Required. One or more URLs.

instances

Required. One or more instance_id.

batch_create()

$browshot->batch_create(file => '/my/file/urls.txt', instance_id => 65)

Request multiple screenshots from a text file. See http://browshot.com/api/documentation#batch_create for the response format.

Arguments:

file

Required. Path to the text file which contains the list of URLs.

instance_id

Required. instance_id to use for all screenshots.

batch_info()

$browshot->batch_info(id => 5)

Get information about a screenshot batch requested previously. See http://browshot.com/api/documentation#batch_info for the response format.

Arguments:

id

Required. Batch ID.

crawl_create()

$browshot->crawl_create(domain => 'blitapp.com', url => 'https://blitapp.com/', max => 50, instance_id => 65)

Crawl a domain and screenshot all pages. See http://browshot.com/api/documentation#crawl_create for the response format.

Arguments:

domain

Required. Domain to crawl.

url

Required. URl to start with.

instance_id

Required. instance_id to use for all screenshots.

crawl__info()

$browshot->crawl__info(id => 5)

Get information about a crawl_ requested previously. See http://browshot.com/api/documentation#crawl__info for the response format.

Arguments:

id

Required. Crawl ID.

account_info()

Return information about the user account. See http://browshot.com/api/documentation#account_info for the response format.

CHANGES

1.24.0

screenshot_thumbnail_file creates the directory structure as needed.

1.16.0

Check if the file is not a folder in simple_file

1.14.1

Remove deprecated API calls.

1.14.0

Add batch_create and batch_info for API 1.14.

1.13.0

Add screenshot_html and screenshot_multiple for API 1.13.

1.12

Add screenshot_search for API 1.12.

1.11.1

Return Browshot response in case of error if the reply is valid JSON.

1.11

Compatible with API 1.11. Optional HTTP timeout.

1.10

Add screenshot_delete for API 1.10.

1.9.4

Fix status code in error messages.

1.9.3

Keep backward compatibility for screenshot_thumbnail.

1.9.0

Add screenshot_share for API 1.9.

1.8.0

Update screenshot_thumbnail to use new API.

1.7.0

Update screenshot_info to handle additional parameters

1.5.1

Use binmode to create valid PNG files on Windows.

1.4.1

Fix URI encoding.

1.4.0

Add simple and simple_file methods.

1.3.1

Retry requests (up to 2 times) to browshot.com in case of error

SEE ALSO

See http://browshot.com/api/documentation for the API documentation.

Create a free account at http://browshot.com/login to get your free API key.

Go to http://browshot.com/dashboard to find your API key after you registered.

AUTHOR

Julien Sobrier, <julien@sobrier.net>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Julien Sobrier

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm WebService::Browshot

perl -MCPAN -e shell
install WebService::Browshot