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:

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:

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
                

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:

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: [email protected]]"    
  }
}
                

Common API 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:

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:

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:

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:

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:[email protected]/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:[email protected]/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 [email protected].

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.

Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

	Standard Support	Platinum Support
General review on the issue
Access to knowledge base articles
Email support communication
Regular products updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug and review updates
Option for quarterly briefing call with product Management
Features requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!