Developer Docs

Making an API request

The url format for making a screenshot request to urlbox.io's API is:

And if you are using urlbox directly on a public facing website, you should use the authenticated request url format:

Where:

• YOUR_API_KEY should 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_TOKEN should 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

• FORMAT should be one of either png or jpg depending on which format you want the resulting image

  . You can also set format to pdf to generate a pdf from the URL

• REQUEST_OPTIONS should 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:

• format is set to png
• url is set to apple.com
• thumb_width is set to 600 pixels wide
• ttl is set to 86400 seconds which is equivalent to 1 day, meaning the screenshot will be freshly generated once daily

And here is the authenticated version:

Simply 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

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

// 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 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"

// 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">'

#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('
')
    return "https://api.urlbox.io/v1/%s/%s/png?%s" % (apiKey, token, queryString)

argsDict = {'url' : "twitter.com", 'thumb_width': 400}
print(urlbox (argsDict))

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;
  }
}

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;
    }

  }
}