API Documentation

Introduction

Screenshotlayer is a lightweight REST API built to deliver high quality PNG, JPEG & GIF website screenshots at unparalleled speeds and through a simple interface.

In order to ensure the highest possible level of image resolution, our API relies on a powerful rendering engine capable of processing, storing and returning all sorts of website content within just a few seconds.

Welcome - let's get started!


Access & Specification

3-Step Quickstart Guide

Step 1: Base URL

Capturing a snapshot using the screenshotlayer API is simple. Each API request is based at the following URL:

http://api.screenshotlayer.com/api/capture
                

Step 2: Required parameters

In order to make any API request, two required parameters - your personal access_key and the target website's url - have to be specified:


Parameter Description
access_key your personal password used to authenticate with the API - located in your Account Dashboard.
url the full URL (including its respective HTTP Protocol) of the website you want to request a snapshot from, e.g. http://abc.com

Important: If your target website's URL contains the special character &, please make sure to pass a URL encoded version of it into the API's url parameter. Read more »


Step 3: Optional parameters

Based on how you you wish to configure your screenshot, you can choose from a number of optional parameters:


Parameter Description Default
fullpage set to "1" if you want to capture the full height of the target website -
width specify your preferred thumbnail width in pixels 1:1
viewport specify your preferred viewport dimensions in pixels 1440x900
format set your preferred image output format PNG
secret_key your secret key, an md5 hash of the target URL and your secret word. (See URL Encryption) -
css_url attach a URL containing a custom CSS stylesheet -
delay specify a delay before screenshot is captured (in seconds) -
ttl define the time (in seconds) your snapshot should be cached 2592000 (30 days)
force set to "1" if you want to force the API to capture a fresh screenshot -
placeholder attach a URL containing a custom placeholder image or set to "1" to use default placeholder -
user_agent specify a custom User-Agent HTTP header to send with your request -
accept_lang specify a custom Accept-Language HTTP header to send with your request -
export export snapshot via custom ftp path or using your AWS S3 user details -

Example Query:

The following query requests a full-height screenshot of apple.com

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.apple.com
    & viewport = 1440x900
    & fullpage = 1
                


URL Encoding


Strictly speaking, it is always a safer method to URL encode your target website's URL before passing it into the API's url parameter. However, URL encoding is required in case your target website's URL contains the special characters ? or &.

Example URLs:

Find below two website url versions that are required to be URL encoded in order to be processed correctly.

http://website.com?example=yes
http://website.com?example=yes&parameter=one
                

Example query:

This is how the first example URL would be passed into an API request:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http%3A%2F%2Fwebsite.com%3Fexample%3Dyes
                

Not sure about URL encoding? Have a look at this reference page »


Access Key

After signing up, every user is assigned a personal API Access Key - a unique "password" used to authenticate with the API.

To call the screenshotlayer API, simply append your access_key as a parameter to the base URL:

http://api.screenshotlayer.com/api/capture?access_key=YOUR_ACCESS_KEY  
                

You can sign up for a free Access Key here. Our Free Plan offers up to 100 monthly snapshots. Paid plans provide larger request volumes and a full stack of advanced features.


HTTPS - Secure Datastreams

Paid Customers may establish a secure connection via 256-bit HTTPS (industry-standard SSL) to the screenshotlayer API, ensuring encrypted datastreams between server and client.

To connect securely, simply append an s to the HTTP Protocol:

https://api.screenshotlayer.com/api/capture?access_key=YOUR_ACCESS_KEY  
                

Rate Limits

Requests to the API are rate limited based on your current subscription plan:

Subscription Plan Rate Limit
Free 2 Requests / Minute
Basic 30 Requests / Minute
Professional 45 Requests / Minute
Enterprise 45 Requests / Minute

Important: In order to ensure maximum API performance, we recommend Basic, Professional and Enterprise Plan users to limit their usage to a maximum of 1 API request per 2 seconds.

If your rate limit for a given minute has been exceeded, the API will return an error carrying the type rate_limit_reached. This error is listed in the API Error Codes section below.


API Error Codes

If your query fails, the screenshotlayer API will return a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.

Find below an example error - triggered when the user did not provide a valid API Access Key:

{
  "success": false,
  "error": {
    "code": 104,
    "type": "invalid_access_key",
    "info": "You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"    
  }
}
                


Common API errors:


Type Message Description
404 "404_not_found" User requested a resource which does not exist.
101 "missing_access_key" User did not supply an Access Key.
101 "invalid_access_key" User entered an invalid Access Key.
103 "invalid_api_function" User requested a non-existent API Function.
104 "usage_limit_reached" User has reached or exceeded his Subscription Plan's monthly API Request Allowance.
210 "invalid_url" User provided an invalid website URL.

show all errors


API Features

Full-Height Captures
Free Basic Pro Enterprise

By default, screenshots are rendered based on the height of the selected (or default) viewport. Alternatively, you can request the full height of the target website to be captured, simply by setting the API's fullpage parameter to 1.

Example query:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.cnn.com
    & fullpage = 1
                

Thumbnails
Free Basic Pro Enterprise

By default, the screenshotlayer API returns your target website's snapshot in original size (1:1). If you'd like to request a thumbnail, append the API's width parameter containing your preferred thumbnail width in pixels.

Example query:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.facebook.com
    & width = 350
                

Viewport Control
Free Basic Pro Enterprise

The screenshotlayer API's default viewport setting is 1440x900. You can specify a custom viewport by setting the viewport parameter to your desired dimensions. (format: width x height, in pixels)

Example query:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.tumblr.com
    & user_agent = Mozilla/5.0 (iPhone; CPU iPhone OS 8_0_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12A366 Safari/600.1.4&viewport=375x667   
    & viewport = 375x667
                

Important: When requesting mobile-sized viewports (example above), it is highly recommended to also specify a user_agent parameter, as some websites (e.g. google.com) tend to ignore mobile viewports that come without specified HTTP User-Agent headers (See User-Agent parameter).

Find below a list of the most commonly used viewport sizes:

Common Viewports:


Device Viewport
iPhone 4 (s) 320x480
iPhone 5 (c/s) 320x568
iPhone 6 375x667
iPhone 6 Plus 414x736
iPad (2/Mini/Retina) 1024x768
Samsung Galaxy S3, S4, S5 360x640
Macbook 13" 1440x900
iMac 27" 2560x1440

You can find a comprehensive list of mobile viewport sizes here.


Output Formats
Free Basic Pro Enterprise

Your snapshots can be requested in three different formats: PNG, JPG and GIF. You can change the default format (PNG) simply by appending the API's format parameter containing your preferred format.

Example query:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.cnn.com
    & format = JPG
                

Please note: Output formats are not case sensitive, and appending "JPEG" is just as valid "JPG".


URL Encryption
Free Basic Pro Enterprise

For those of you who have to display API request URLs on their website (e.g. inside an <img src="..."> tag, it is crucial to make use of the screenshotlayer API's URL Encryption method, which lets you generate a unique Secret Key for every API request and simply append it to the respective query URL.

In order to prevent your publicly displayed API request URL from being abused, you need to follow these steps:

Step 1: Define your target website's URL

First of all, define the URL of the website you want to take a snapshot of.

In our example we will use the following URL:

http://www.apple.com
                

Step 2: Define your secret keyword

A secret keyword can be any secret word or phrase of your choice. As the next step, make sure you have defined it in your account dashboard. If not, you can simply add a secret keyword here.

In our example we will use the following secret keyword:

mysecretkeyword
                

Step 3: Combine

Now you will need to combine these two parts (URL & secret keyword) into one, resulting in:

http://www.apple.commysecretkeyword
                

Step 4: Generate your md5 Secret Key

Finally, create an md5 hash of the combined parts. (this will be your secret_key)

a9d09c5b1cda7e5ef51fed4526e9cff3
                

Now that you have your Secret Key, you can simply append to your query URL using the API's secret_key parameter and rest assured that your API access is - as long as you'll keep your secret keyword secret - safe from abuse.

Syntax:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.apple.com
    & secret_key = a9d09c5b1cda7e5ef51fed4526e9cff3
                

CSS Injection
Free Basic Pro Enterprise

The screenshotlayer API enables you to inject a custom CSS stylesheet into the target website by appending an existing CSS file URL to the API's css_url parameter.

For our example we have prepared a file called css_inject.css, containing the following CSS declaration:

body {
background: #00ff00 !important;
}
                

Example query:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.youtube.com
    & css_url = https://screenshotlayer.com/downloads/css_inject.css
                

Please note: Attached CSS files must not exceed a file size of 100kB (around 100,000 characters).


Capturing Delay
Free Basic Pro Enterprise

The API's delay parameter enables you to specify a custom delay time (in seconds) before the snapshot is captured. This feature may especially useful if certain contents of your target website appear after the initial page load. (e.g. CSS animations, JavaScript effects)

Example query:

The following query sets a delay time of 3 seconds in order to capture any delayed/animated contents on the target website. (http://tumblr.com)

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.tumblr.com
    & delay = 3
                

Please note: The maximum supported delay time is 20 seconds.


TTL (Caching Time)
Free Basic Pro Enterprise

By default, website screenshots are cached for 30 days (2,592,000 seconds). Using the API's ttl parameter, you can specify a custom caching time (time-to-live) lower than the default setting.

Example query:

The following query requests the snapshot's ttl to be set to 259,200 seconds (3 days).

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.tumblr.com
    & ttl = 259200
                

Please note: The default ttl (30 days, or 2,592,000 seconds) is the maximum supported caching time.


Force Refresh
Free Basic Pro Enterprise

You can easily force the API to capture a fresh screenshot of the requested target URL by appending the force parameter to the request URL and setting it to 1.

Example query:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.tumblr.com
    & force = 1
                


Placeholder image
Free Basic Pro Enterprise

For the very few seconds a freshly captured screenshot loads, there are two options for requesting a placeholder image:

Option 1: Using the default placeholder

By appending the API's placeholder parameter and setting it to 1, you can request the default screenshotlayer placeholder image, which looks like this:

default placeholder image

Option 2: Setting a custom placeholder image URL

If you prefer setting your own custom placeholder image, simply append it to the API's placeholder parameter as an image URL.

Supported file formats: PNG, JPEG, GIF

Example query: (using option 1)

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.twitter.com
    & placeholder = 1
                

Please note: If activated, placeholder images are returned immediately after the API request and remain visible until the respective page is refreshed.


HTTP User-Agent Headers
Free Basic Pro Enterprise

By default, the screenshotlayer API does not send any HTTP User-Agent headers with your request. You can specify a custom user-agent string by appending it to the API's user_agent parameter.

Example query:

The following query requests a screenshot of http://facebook.com on mobile Safari (iOS 8.0.2, iPhone):

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.facebook.com
    & viewport = 375x667
    & user_agent = Mozilla/5.0 (iPhone; CPU iPhone OS 8_0_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12A366 Safari/600.1.4   
                

Common User-Agent Strings:


System UA String
Chrome Generic Win7 64-bit Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36
Chrome Generic MacOSX Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36
Safari 8.0 MacOSX Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/600.6.3 (KHTML, like Gecko) Version/8.0.6 Safari/600.6.3
Firefox Generic Win7 64-bit Mozilla/5.0 (Windows NT 6.1; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0

You can find a full list of user-agent strings here.


HTTP Accept-Language Headers
Free Basic Pro Enterprise

The default HTTP Accept-Language header is en-US, en (US English, or English in general). You can specify a custom Accept-Language header by appending it to the API's accept_lang parameter.

Example query:

The following query requests a screenshot of http://facebook.com in Spanish:

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.facebook.com
    & accept_lang = es
                

You may also specify several different languages at once. Each additional language is separated by a comma. The order in which the values appear in the header determine the hierarchy of importance.

In the following example es-MX (Spanish, Mexico) is the hightest priority, followed by general Spanish and general English:

es-MX,es,en
                

Common Accept-Language Strings:


Language Accept-Language
English (general) en
German de
Spanish es
Italian it
English (US) en-US
English (UK) en-GR
Spanish (Spain) es-ES
Spanish (Mexico) es-MX

You can find a comprehensive list of accept-language strings here.


Export to AWS S3
Pro Enterprise

If you are subscribed to the Professional or Enterprise Plan, you may request the API to directly export your snapshot to your AWS S3 Bucket. This can be done simply by appending your S3 Bucket path (format: s3://API_KEY:API_SECRET@bucket) to the API's export parameter.

Example query:

Find below an example query requesting the API to export a screenshot of http://tumblr.com directly to a specified AWS S3 Bucket.

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.tumblr.com
    & export = s3://DHSJ2HDGALIIDHSJDGAH:7SH6s7Sw9DKSH7h8Zs9Bw9DKSSH7h86s7Sw9Bw9D@mybucket.test/path/to   
                

Important: Uploading your snapshot to the given S3 path may take up to 1 minute to complete. Please be aware that our system can only attempt accessing the specified export path and cannot notify you in case your upload fails.


Export to FTP
Pro Enterprise

Professional and Enterprise Customers may also specify a custom ftp path to directly export captured snapshots to. This can be achieved simply by appending your desired FTP path (format: ftp://user:password@server) to the API's export parameter.

Example query:

Find below an example query requesting the API to export a screenshot of http://tumblr.com directly to a specified FTP path.

http://api.screenshotlayer.com/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http://www.tumblr.com
    & export = ftp://myusername:mypassword@123.12.12.1/path/to   
                

Important: Uploading your snapshot to the given FTP path may take up to 1 minute to complete. Please be aware that our system can only attempt accessing the specified export path and cannot notify you in case your upload fails.


Language Examples

PHP

Capture Snapshots via PHP:

Find below a simple PHP function that lets you capture a screenshot and define all required and optional parameters:

function screenshotlayer($url, $args) {

  // set access key
  $access_key = "YOUR_ACCESS_KEY";
  
  // set secret keyword (defined in account dashboard)
  $secret_keyword = "YOUR_SECRET_KEYWORD";

  // encode target URL
  $params['url'] = urlencode($url);

  $params += $args;

  // create the query string based on the options
  foreach($params as $key => $value) { $parts[] = "$key=$value"; }

  // compile query string
  $query = implode("&", $parts);

  // generate secret key from target URL and secret keyword
  $secret_key = md5($url . $secret_keyword);

  return "https://api.screenshotlayer.com/api/capture?access_key=$access_key&secret_key=$secret_key&$query";

}

// set optional parameters (leave blank if unused)
$params['fullpage']  = '';    
$params['width'] = '';      
$params['viewport']  = '';  
$params['format'] = '';      
$params['css_url'] = '';      
$params['delay'] = '';      
$params['ttl'] = '';  
$params['force']     = '';     
$params['placeholder'] = '';      
$params['user_agent'] = '';      
$params['accept_lang'] = '';      
$params['export'] = '';      

// capture
$call = screenshotlayer("google.com", $params);                
                

Please note: Optional parameters may be left blank if they are not being used.


Ruby

Capture Snapshots via Ruby:

Find below a Ruby function that lets you capture a screenshot and define all required and optional parameters:

                
require 'cgi' unless defined?(CGI)
require 'digest' unless defined?(Digest)
 
def screenshotlayer(url, options={})
    
  # set access key
  access_key = 'YOUR_ACCESS_KEY'
  
  # set secret keyword (defined in account dashboard)
  secret_keyword = 'YOUR_SECRET_KEYWORD'
 
  # define parameters
  parameters = {
    :url       => url,
    :fullpage  => options[:fullpage],
    :width  => options[:width],
    :viewport  => options[:viewport],
    :format  => options[:format],
    :css_url  => options[:css_url],
    :delay  => options[:delay],
    :ttl  => options[:ttl],
    :force  => options[:force],
    :placeholder  => options[:placeholder],
    :user_agent  => options[:user_agent],
    :accept_lang  => options[:accept_lang],
    :export  => options[:export],
  }
   
  query = parameters.
    sort_by {|s| s[0].to_s }. 
    select {|s| s[1] }.       
    map {|s| s.map {|v| CGI::escape(v.to_s) }.join('=') }.
    join('&')
  
  # generate md5 secret key
  secret_key = Digest::MD5.hexdigest(url + secret_keyword)
 
  "https://api.screenshotlayer.com/api/capture?access_key=#{access_key}&secret_key=#{secret_key}&#{query}"
end
 
# set url (required), optional parameters (leave blank if unused) & call function
puts screenshotlayer("www.cnn.com",{ 
    fullpage: "", 
    width: "", 
    viewport: "", 
    format: "", 
    css_url: "", 
    delay: "", 
    ttl: "", 
    force: "", 
    placeholder: "", 
    user_agent: "", 
    accept_lang: "", 
    export: "" })                   
                
                

Please note: Optional parameters may be left blank if they are not being used.


Python

Capture Snapshots using Python:

Building a query to capture a screenshot using Python is as simple as:

                
#!/usr/bin/python
 
import hmac
import hashlib
import urllib
 
 
def screenshotlayer(access_key, secret_keyword, url, args):
    
    # encode URL
    query = urllib.urlencode(dict(url=url, **args))
 
    # generate md5 secret key
    secret_key = hashlib.md5('{}{}'.format(url, secret_keyword)).hexdigest()
 
    return "https://api.screenshotlayer.com/api/capture?access_key=%s&secret_key=%s&%s" % (access_key, secret_key, query)

# set optional parameters (leave blank if unused)
params = {
    'fullpage': '',
    'width': '',
    'viewport': '',
    'format': '',
    'css_url': '',
    'delay': '',
    'ttl': '',
    'force': '',
    'placeholder': '',
    'user_agent': '',
    'accept_lang': '',
    'export': ''
};
 
# set your access key, secret keyword and target URL 
access_key = "YOUR_ACCESS_KEY"
secret_keyword = "YOUR_SECRET_KEYWORD"
url = "www.cnn.com"
 
print screenshotlayer (access_key, secret_keyword, url, params)

                

Please note: Optional parameters may be left blank if they are not being used.


Help / Support


Any issues with API Integration? Be sure to take a look at our Frequently Asked Questions to see if your question has already been answered.

Still need something clarified? Please get in touch with our support team at support@apilayer.com.