API guide

Our thumbnails capturing service is based on HTTP GET requests.

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

Complete request scheme:
http://api.screenshotmachine.com/?key=[key]&size=[size]&format=[format]&hash=[hash]&cacheLimit=[cacheLimit]&timeout=[timeout]&url=[url]

Parameters description

Parameter Type Mandatory Description
key String Yes Unique user account key is required for using our service. You will get your key after sign up.
url String Yes The web page URL you want to capture. Url encoding is recommended and http(s):// protocol prefix is optional.
size String No Size of the thumbnail or screenshot. Default value is T. You can choose from these available sizes:
T: (120 x 90px) - tiny
S: (200 x 150px) - small
E: (320 x 240px) - seminormal
N: (400 x 300px) - normal
M: (640 x 480px) - medium
L: (800 x 600px) - large
X: (1024 x 768px) - extra large
F: full page, complete page from the top to the bottom (can be pretty long)

The mobile device screen resolutions are also available. You can capture a webpage using mobile phone's screen resolution.
There are two options available:

Nmob: (480 x 800px) - normal
Fmob: full page, complete page from the top to the bottom

format String No Format of the thumbnail or screenshot. Default value is JPG. Available values are: JPG, PNG, GIF
hash String No If you are calling our service directly from the public HTML pages, we suggest you to safeguard your account with hash parameter. The hash parameter value is calculated using MD5 algorithm from url parameter value and secret phrase.

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

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

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

Examples:
cacheLimit=0 : never use cache, always download fresh screenshot
cacheLimit=1 : use image from cache only if is not older than 1 day
cacheLimit=2 : use image from cache only if is not older than 2 days
etc...
timeout Integer
(0, 200,400, 600, 800, 1000)
No
Using timeout parameter, you can manage how long capturing engine should wait before the screenshot is created. Default value is 200. This parameter is useful when you want to capture a webpage with some fancy animation and you want to wait until the animation finish.

Examples:
timeout=0 : capture webpage immediately
timeout=200 : wait 200ms before capturing
timeout=400 : wait 400ms before capturing
etc...

Examples

(Let's assume, your account key is 12345)

1) Capture the tiny size (default) thumbnail of http://google.com
http://api.screenshotmachine.com/?key=12345&url=http://google.com

2) Capture the full page screenshot of http://google.com in PNG format
http://api.screenshotmachine.com/?key=12345&size=F&format=PNG&url=http://google.com

3) Capture the extra large (1024 x 768px) screenshot of http://google.com using secret phrase Hello in JPG (default) format
http://api.screenshotmachine.com/?key=12345&size=X&hash=94f0097b94d2f2486db52aab7cf268ad&url=http://google.com

Ruby example

This simple gem is brought you by smart guys from Tupalo.com

Error handling

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

Example:
X-Screenshotmachine-Response: invalid_url

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

Error code Description Error image
invalid_hash Provided hash is invalid.
invalid_key Specified user account key is invalid.
invalid_url Specified URL is invalid or authorization is required (401 Unauthorized status code was sent). See Basic_access_authentication for more info.
missing_key User account key is missing in your request.
missing_url URL parameter is missing in your request.
no_credits Your account is exhausted, you need/should to buy more unique URLs.
unsupported Free account owners are not allowed to call our API using HTTPS protocol.
system_error Generic system error. Oops, sometimes bad things happens in the universe:(