URLBOX
Menu
Developer Docs
Making an API request
The url format for making a screenshot request to urlbox.io's API is:
https://api.urlbox.io/v1/YOUR_API_KEY/FORMAT?REQUEST_OPTIONS
And if you are using urlbox directly on a public facing website, you should use the authenticated request url format:
https://api.urlbox.io/v1/YOUR_API_KEY/GENERATED_TOKEN/FORMAT?REQUEST_OPTIONS
Where:
YOUR_API_KEYshould be replaced by your actual urlbox API key which you can get by registering for an account.
(If you have already registered, you can find your API Key by logging in to your account.)GENERATED_TOKENshould be replaced by a hash which is generated server side by taking the HMAC SHA1 of the query string and signing it with your API Secret. This parameter is optional unless you have enabled the Force Authenticated Requests option in your dashboard.
Example code is below to get you started in no time
You can also set format toFORMATshould be eitherpng,webporjpgdepending on which format you want the resulting image.pdfto generate a pdf from the URL, orhtmlto return the raw HTML.REQUEST_OPTIONSshould be replaced by a query string that contains all of the options you want to set.
A table of all options and their defaults are shown below
An example, valid urlbox url is shown below, with the following options:
formatis set to pngurlis set to apple.comthumb_widthis set to 600 pixels widettlis set to 86400 seconds which is equivalent to 1 day, meaning the screenshot will be freshly generated once daily
https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/png?url=apple.com&thumb_width=600&ttl=86400And here is the authenticated version:
https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/73ff36a5393a7a96bd6cdd5c0d05d0fede884cad/png?url=apple.com&thumb_width=600&ttl=86400Simply putting this url as the src attribute in a normal img tag, the resulting image is:
Request Options
Below is a table listing all of the available options to the API.
Combine these options as parameters in the query string for e.g. ?url=bbc.co.uk&full_page=true
Basic Options
The URL of the website you want to screenshot
Default: false
Specify whether to capture the full scrollable area of the website. For PDF's, the full page will always be converted to PDF
Take a screenshot of the element that matches this selector. By default, if the selector is not found, Urlbox will take a normal viewport screenshot. If you prefer Urlbox to fail the request when the selector is not found, pass fail_if_selector_missing=true.
Browser Options
Options to configure the browser before navigating to the URL
Default: 1280
Viewport width of the browser in pixels
Default: 1024
Viewport height of the browser in pixels
Default: screen
Set the css media stylesheet to use. Options are either 'screen' or 'print'. When format is pdf, the default css media stylesheet will be set to 'print'
Sets a cookie on the request when loading the URL. E.g. to set the cookie with key 'OptIn' to the value 'yes', you would pass cookie=OptIn%3Dtrue. Can be set multiple times to set more than one cookie e.g. cookie=OptIn%3Dtrue&cookie=SessionId%3DMTIzNDU. Please note the cookie value must be URL encoded i.e. OptIn=true becomes OptIn%3Dtrue in order to be passed inside the query string and interpreted correctly by Urlbox
Sets a header on the request when loading the URL. E.g. to set the header with key 'X-My-Header' to the value 'SomeValue', you would pass header=X-My-Header%3DSomeValue. Can be set multiple times to set more than one header e.g. header=X-My-Header%3DSomeValue&header=X-My-Other-Header%3DSomeOtherValue. Please note the header value must be URL encoded i.e. X-My-Header=SomeValue becomes X-My-Header%3DSomeValue in order to be passed inside the query string and interpreted correctly by Urlbox
Default: false
Turns off javascript on target url. This option will also disable full_page=true because it is hard to infer the full content height when javascript is turned off.
Default: false
Enable the flash plugin for flash using websites
User-Agent string used to emulate a particular client
Default: en-US
Sets an Accept-Language header on requests to the target URL
Sets an Authorization header on requests to the target URL
Pass in an address to a proxy server to make screenshot requests via that server in the format [address]:[port]. If proxy authentication is needed you can use the following format: [user]:[password]@[address]:[port].
Latitude used to emulate the Geolocation API
Longitude used to emulate the Geolocation API
How accurate the Geolocation API should be in meters
Set local timezone to use for the screeenshot e.g. tz=Europe/London. Default is UTC
Image Options
Options relating to the outputted PNG, WebP or JPEG file
Default: false
Take a 'retina' or high definition screenshot equivalent to setting a device pixel ratio of 2.0 or @2x. Please note that retina screenshots will be double the normal dimensions and will normally take slightly longer to process due to the much bigger image size.
Width in pixels of the generated thumbnail, leave off for full-size screenshot
Crop the width of the screenshot to this size in pixels
Default: 80
JPEG/WebP only - image quality of resulting screenshot (0-100)
Default: false
If a website has no background color set, the image will have a transparent background (PNG/WebP only)
Pass in a filename e.g. download=myfilename.png which sets the content-disposition header on the response. This will make the urlbox link a downloadable link and prompt the user to save the file as myfilename.png.
PDF Options
Options relating to PDF document generation
Default: A4
Sets the pdf page size. Options are 'A0', 'A1', 'A2', 'A3', 'A4', 'A5','A6','Legal', 'Letter', 'Ledger' or 'Tabloid'. Setting this option will override pdf_page_width and pdf_page_height.
Sets the pdf page width in pixels
Sets the pdf page height in pixels
Default: false
Auto scale the website content to the pdf page size
Default: None
Set the margin of the PDF document. Available options are 'None', 'Default' or 'Minimum'
Set a custom pdf top margin
Set a custom pdf right margin
Set a custom pdf bottom margin
Set a custom pdf left margin
Default: 1
Scale factor of the website content. Valid values are numbers between 0.1 and 2
Default: Portrait
Sets the pdf document orientation, options are 'Portrait' or 'Landscape'
Default: true
Sets whether to print background images in the PDF
Default: print
By default, when generating a pdf, the 'print' css media query is used. To generate a pdf using the 'screen' css, set this option to 'screen'
Pass in a filename e.g. download=myfilename.pdf which sets the content-disposition header on the response. This will make the urlbox link a downloadable link and prompt the user to save the file as myfilename.pdf.
Cache Options
Control how Urlbox caches your screenshots or pdf documents
Default: false
Generate a fresh screenshot or pdf instead of getting a cached version
You can pass a unique string such as a UUID, hash or timestamp to have more control over when to generate a fresh screenshot or pdf. For example unique=1574803174491
Default: 2592000 (30 days)
Short for 'time to live'. Number of seconds to keep a screenshot or pdf in the cache. Note the default is also the maximum value for this option.
Wait Options
Waits for the element specified by this selector to be present in the dom before taking a screenshot or pdf. By default Urlbox will take a screenshot or pdf if the wait_for element is not found after waiting for the time specified by the wait_timeout option. If you prefer Urlbox to fail the request when the wait_for element is not found, pass fail_if_selector_missing=true
Waits for the element specified by this selector to be absent from the dom before taking a screenshot or pdf. An example would be waiting for long running loading spinners to be gone before taking a screenshot. By default Urlbox will take a screenshot or pdf if the wait_to_leave element is still present after the time specified by the wait_timeout option. If you prefer Urlbox to fail the request when the wait_to_leave element is still present, pass fail_if_selector_present=true
Default: 30000
How many milliseconds Urlbox should wait for the 'wait_for' element to be available before continuing
Amount of time to wait in milliseconds before urlbox takes the screenshot or pdf
Page Options
Options which modify the page before taking a screenshot or pdf
Blocks requests from popular ad-networks from loading
Automatically hide cookie banners from most websites
Automatically click accept buttons in order to hide popups
Element selector that is clicked before generating a screenshot or pdf e.g. #clickme would click the element with id="clickme". Can be used multiple times to simulate multiple sequential click events.
Element selector that is hovered before generating a screenshot or pdf e.g. #hoverme would hover over the element with id="hoverme"
Hex code or css color string. Some websites don't set a body background colour, and will show up as transparent backgrounds with PNG or black when using JPG. Use this setting to set a background colour. If the website explicitly sets a transparent background on the html or body elements, this setting will be overridden.
Comma delimited string of css element selectors that are hidden by setting their style to `display:none !important;`. Useful for hiding popups.
Word to highlight on the page before capturing a screenshot or pdf
Default: white
Text color of the highlighted word
Default: red
Background color of the highlighted word
Full Page Options
Advanced options that control how Urlbox takes full page screenshots, when full_page=true
By default when Urlbox detects an infinite scrolling page, it does not attempt to continue scrolling until the bottom, as this could result in infinite scrolling! If you want to override this behaviour pass true for this option
Default: false
Enabling skip_scroll will speed up renders by skipping an initial scroll through the page which is used to trigger any lazy loading elements.
Some pages have full-height backgrounds whose heights are set to 100% of the viewport. This can cause the backgrounds to get stretched when making a full page screenshot. If you are seeing this behaviour in your full page screenshots, pass true for this option.
Default: 2098
When Urlbox takes a full_page screenshot, the maximum height of each image section is set as 4096 pixels. If a site is greater than this value, Urlbox will start splitting the screenshot into sections. Sometimes it is worthwhile to experiment with this number
For extremely lengthy websites it may be preferable to limit the screenshot to a maximum height to prevent Urlbox from spending time scrolling and generating an enormous screenshot
When scrolling the page to trigger lazy loading elements, decide by how many pixels the page should be scrolled by. By default the scroll incrememnt is set to the browser viewport height. Some pages lazy loading elements however only trigger when the scroll increment is smaller than this e.g. 400px
When Urlbox decides to split a screenshot into multiple sections, the scroll delay is the time (in milliseconds) between taking the screenshots of each individual section. Whilst Urlbox does detect animations and attempts to wait for them before taking a screenshot, this option could be used to force urlbox to wait for a certain amount of time after scrolling to the next section, to wait for things like animations to finish.
Storage Options
Options relating to storing the screenshots in S3
Default: false
Save the screenshot directly to the S3 bucket configured on your account
The s3 path, including subdirectories and the filename, to save the screenshot to in your S3 bucket. The extension (.png, .jpg or .pdf) will be provided automatically and should not be included in s3_path.
Override the configured s3 bucket that the screenshot will be saved to
Request Behaviour Options
Dictate how Urlbox handles certain scenarios
Default: false
Fails the request if the elements specified by 'selector' or 'wait_for' options are not found on the page after waiting for wait_timeout.
Default: false
Fails the request if the element specified by wait_to_leave option is found on the page after waiting for wait_timeout.
Default: false
If fail_on_4xx=true and the requested URL returns a status code >= 400 and <= 499, Urlbox will fail the request with error code 400 and the message: 'Failed to render. Requested URL returned a 4xx error code and fail_on_4xx was true'
Default: false
If fail_on_5xx=true and the requested URL returns a status code >= 500 and <= 599, Urlbox will fail the request with error code 400 and message: 'Failed to render. Requested URL returned a 5xx error code and fail_on_5xx was true'
Default: 30000
Amount of time to wait in milliseconds for the requested URL to respond
Frequently Asked Questions
Example Code
Sample code is available in the following languages: Node.js, Ruby, PHP, Python, Java and C#.
If you would like help integrating our API with your language please get in touch
Node.js
Sample code to take website screenshots in Node.js
// npm install urlbox --save
import Urlbox from 'urlbox';
// Plugin your API key and secret
const urlbox = Urlbox(YOUR_API_KEY, YOUR_API_SECRET);
// Set your options
const options = {
url: 'github.com',
thumb_width: 600,
format: 'jpg',
quality: 80
};
const imgUrl = urlbox.buildUrl(options);
// https://api.urlbox.io/v1/YOUR_API_KEY/TOKEN/jpg?url=github.com&thumb_width=600&quality=80
// Now set it as the src in an img tag to render the screenshot
<img src={imgUrl} />Ruby
Sample code to take website screenshots in Ruby
# ruby gem coming soon
require 'openssl'
require 'open-uri'
def encodeURIComponent(val)
URI.escape(val, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
end
def urlbox(url, options={}, format='png')
urlbox_apikey = 'YOUR_API_KEY'
urlbox_secret = 'YOUR_API_SECRET'
query = {
:url => url, # required - the url you want to screenshot
:force => options[:force], # optional - boolean - whether you want to generate a new screenshot rather than receive a previously cached one - this also overwrites the previously cached image
:full_page => options[:full_page], # optional - boolean - return a screenshot of the full screen
:thumb_width => options[:thumb_width], # optional - number - thumbnail the resulting screenshot using this width in pixels
:width => options[:width], # optional - number - set viewport width to use (in pixels)
:height => options[:height], # optional - number - set viewport height to use (in pixels)
:quality => options[:quality] # optional - number (0-100) - set quality of the screenshot
}
query_string = query.
sort_by {|s| s[0].to_s }.
select {|s| s[1] }.
map {|s| s.map {|v| encodeURIComponent(v.to_s) }.join('=') }.
join('&')
token = OpenSSL::HMAC.hexdigest('sha1', urlbox_secret, query_string)
"https://api.urlbox.io/v1/#{urlbox_apikey}/#{token}/#{format}?#{query_string}"
end
### USAGE: (format can be png or jpg, we default to png) ###
url = urlbox("www.google.com", {thumb_width: 200, full_page: true, quality: 90}, 'jpg')
puts url
# url: "https://api.urlbox.io/v1/YOUR_API_KEY/TOKEN/jpg?full_page=true&quality=90&thumb_width=200&url=www.google.com"
PHP
Sample code to take website screenshots in PHP
// run this on the command line to install the urlbox php package:
// composer require urlbox/screenshots
use Urlbox\Screenshots\Urlbox;
$urlbox = Urlbox::fromCredentials('API_KEY', 'API_SECRET');
// only required option is a url:
$options['url'] = 'example.com';
// specify any other options to augment the screenshot...
$options['width'] = 320;
// Create the Urlbox URL
$urlboxUrl = $urlbox->generateUrl($options);
// $urlboxUrl is now 'https://api.urlbox.io/v1/API_KEY/TOKEN/png?url=example.com&width=320'
// Generate a screenshot by loading the Urlbox URL in an img tag:
echo '<img src="'.$urlboxUrl.'" alt="Test screenshot generated by Urlbox">'Python
Sample code to take website screenshots in Python
# pypy package coming soon!
#!/usr/bin/python
import hmac
from hashlib import sha1
try:
from urllib import urlencode
except ImportError:
from urllib.parse import urlencode
def urlbox(args):
apiKey = "xxx-xxx"
apiSecret = "xxx-xxx"
queryString = urlencode(args, True)
hmacToken = hmac.new(str.encode(apiSecret), str.encode(queryString), sha1)
token = hmacToken.hexdigest().rstrip('\n')
return "https://api.urlbox.io/v1/%s/%s/png?%s" % (apiKey, token, queryString)
argsDict = {'url' : "twitter.com", 'thumb_width': 400}
print(urlbox (argsDict))Java
Sample code to take website screenshots in Java
import java.io.UnsupportedEncodingException;
import java.math.BigInteger;
import java.net.URLEncoder;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Map;
import java.util.HashMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class Urlbox {
private String key;
private String secret;
Urlbox(String api_key, String api_secret) {
this.key = api_key;
this.secret = api_secret;
}
// main method demos Example Usage
public static void main(String[] args) {
String urlboxKey = "your-urlbox-api-key";
String urlboxSecret = "your-urlbox-secret";
// Set request options
Map<String, Object> options = new HashMap<String, Object>();
options.put("width", 1280);
options.put("height", 1024);
options.put("thumb_width", 240);
options.put("full_page", "false");
options.put("force", "false");
// Create urlbox object with api key and secret
Urlbox urlbox = new Urlbox(urlboxKey, urlboxSecret);
try {
// Call generateUrl function of urlbox object
String urlboxUrl = urlbox.generateUrl("bbc.co.uk", options);
// Now do something with urlboxUrl.. put in img tag, etc..
} catch (UnsupportedEncodingException ex) {
throw new RuntimeException("Problem with url encoding", ex);
}
}
public String generateUrl(String url, Map<String,Object> options) throws UnsupportedEncodingException {
String encodedUrl = URLEncoder.encode(url, "UTF-8");
String queryString = String.format("url=%s", encodedUrl);
for (Map.Entry<String, Object> entry : options.entrySet()) {
String queryParam = "&"+entry.getKey()+"="+entry.getValue();
queryString += queryParam;
}
String token = generateToken(queryString, this.secret);
String result = String.format("https://api.urlbox.io/v1/%s/%s/png?%s", this.key, token, queryString);
System.out.println(result);
return result;
}
private String generateToken(String input, String key) {
String lSignature = "None";
try {
Mac lMac = Mac.getInstance("HmacSHA1");
SecretKeySpec lSecret = new SecretKeySpec(key.getBytes(), "HmacSHA1");
lMac.init(lSecret);
byte[] lDigest = lMac.doFinal(input.getBytes());
BigInteger lHash = new BigInteger(1, lDigest);
lSignature = lHash.toString(16);
if ((lSignature.length() % 2) != 0) {
lSignature = "0" + lSignature;
}
} catch (NoSuchAlgorithmException lEx) {
throw new RuntimeException("Problems calculating HMAC", lEx);
} catch (InvalidKeyException lEx) {
throw new RuntimeException("Problems calculating HMAC", lEx);
}
return lSignature;
}
}C#
Sample code to take website screenshots in C#
Check out our nuget package here
using UrlboxMain;
namespace Screenshot
{
public class Screenshotter
{
Urlbox urlbox = new Urlbox("YOUR_URLBOX_API_KEY", "YOUR_URLBOX_API_SECRET");
public void GetScreenshotUrl()
{
dynamic options = new ExpandoObject();
options.Width = 1280;
options.Thumb_Width = 500;
options.Full_Page = true;
var output = urlbox.GenerateUrl("bbc.co.uk", options);
// output is now https://api.urlbox.io/v1/YOUR_URLBOX_API_KEY/d6b5068716c19ba4556648ad9df047d5847cda0c/png?url=bbc.co.uk&width=1280&thumb_width=500&full_page=true
// to generate a screenshot image you would make a simple GET request to this URL, for example putting it inside an <img> tag.
}
}
}
// ================================================================
// UrlboxMain project/package:
using System;
using System.Collections.Generic;
using System.Dynamic;
using System.Linq;
using System.Text;
using PCLCrypto;
namespace UrlboxMain
{
public class Urlbox
{
String apiKey;
String apiSecret;
static List<String> encodedPropertyNames = new List<String> { "user_agent", "bg_color", "hide_selector", "click_selector", "highlight", "highlightbg", "highlightfg" };
static List<String> booleanPropertyNames = new List<String> { "force", "retina", "full_page", "disable_js" };
public Urlbox(String apiKey, String apiSecret)
{
if (String.IsNullOrEmpty(apiKey) || String.IsNullOrEmpty(apiSecret))
{
throw new ArgumentException("Please provide your Urlbox.io API Key and API Secret");
}
this.apiKey = apiKey;
this.apiSecret = apiSecret;
}
public string GenerateUrl(string url)
{
return this.GenerateUrl(url, new ExpandoObject());
}
public string GenerateUrl(string url, ExpandoObject options)
{
if (String.IsNullOrEmpty(url))
{
throw new ArgumentException("Please provide a url in order to generate a screenshot URL");
}
var encodedUrl = urlEncode(url);
var format = "png";
byte[] key = Encoding.UTF8.GetBytes(this.apiSecret);
var urlString = string.Format("url={0}", encodedUrl);
StringBuilder sb = new StringBuilder(urlString);
foreach (KeyValuePair<string, object> kvp in options)
{
var optionName = kvp.Key.ToLower();
var optionValue = kvp.Value.ToString();
if (String.IsNullOrEmpty(optionValue))
{
continue;
}
if (string.Equals(optionName, "format")){
format = optionValue;
continue;
}
if (encodedPropertyNames.Contains(optionName))
{
optionValue = urlEncode(optionValue);
}
if (booleanPropertyNames.Contains(optionName))
{
if (!(bool)kvp.Value) { continue; }
optionValue = optionValue.ToLower();
}
sb.Append(string.Format("&{0}={1}", optionName, optionValue));
}
var queryString = sb.ToString();
var uniqueToken = generateToken(queryString, key);
return string.Format("https://api.urlbox.io/v1/{0}/{1}/{2}?{3}", this.apiKey, uniqueToken, format, queryString);
}
private static string generateToken(String data, byte[] key)
{
var algorithm = WinRTCrypto.MacAlgorithmProvider.OpenAlgorithm(MacAlgorithm.HmacSha1);
CryptographicHash hasher = algorithm.CreateHash(key);
hasher.Append(Encoding.UTF8.GetBytes(data));
byte[] mac = hasher.GetValueAndReset();
var macStr = byteArrayToString(mac);
return macStr;
}
private static string byteArrayToString(byte[] ba)
{
string hex = BitConverter.ToString(ba).ToLower();
return hex.Replace("-", "");
}
private static string urlEncode(string url)
{
// make it behave like javascript encodeURIComponent()
var encoded = Uri.EscapeDataString(url);
encoded = encoded.Replace("%28", "(");
encoded = encoded.Replace("%29", ")");
return encoded;
}
}
}