Screenshot API Guide:

API Builder Tool

You can use our API Builder Tool to visually see how the most common parameters are used in the API requests!

API endpoints

https://api.pagelr.com or http://api.pagelr.com

Simplest API call

The PageLr API uses simple Urls (Http GET) requests designed to minimize the amount of parameters required, every API parameter has a default value, except the uri parameter that is required.
A minimum valid request looks like:

/capture?uri=apple.com

A request like this using all default parameters would return the full length page, captured in a viewport (browser width) of 1024 pixels.

Customized API call

The above example returned an image with a width of 1024 pixels, and the height corresponding to the full page. If you want the same page capture but at a different size, you can get a scaled down version by append the desired image width e.g. &width=600 to the api call.

/capture?uri=apple.com&width=600

Combining parameters

The above example returned an image with a width of 600 pixels, and the height corresponding to the full page scaled down from a width of 1024 pixels. Now when you want different browser size for instance 128, and at a 4/3 aspect ratio can get a scaled down version by append the desired parameters e.g. &width=600&b_width=1280&height=450 to the url.

/capture?uri=apple.com&width=600&b_width=1280&height=450

Enable JavaScript

Some web pages requires javascript to run for them to render their content. When loading and running JavaScript in a web page, it can slow down a page considerably. We do not enable JavaScript in the API per default to make sure you can get the quickest screenshot possible without any extra work.

To enable javascript when generating a page screenshot, add javascript to the service url, like:

/capture/javascript?uri=apple.com&width=600&b_width=1280&height=450

Parameter reference

uri

The uri to the page you want to capture. If it contains anything more than a simple path it need to be urlencoded.

Simple example:

/capture?uri=apple.com&width=600&b_width=1280&height=450

Url encoded example:

/capture?uri=amazon.com%2Fb%3Fnode%3D5521637011&width=400&height=300

HTTPS:

HTTP is used as default protocol in the request, if you require SSL/HTTPS you add that to the uri parameter.

/capture?uri=https://apple.com&width=600&b_width=1280&height=450

b_width

The viewport or browser width in pixels is defined by b_width and is used layout and render the page. Default is 1024 pixels. Most webpages are designed to fill up the width of a 1024 pixel wide screen, commonly with a content width around 980 pixels with some space and chrome around.

Wide screen capture:

To capture a page rendering at a larger width, e.g. 1280 pixels, add &b_width=1280 to the request.

/capture?uri=apple.com&width=600&b_width=1280&height=450

width

The width of the image returned, scaled down from the browser width, if no width is specified image will have the same width as the viewport (b_width).

/capture?uri=apple.com**&width=600&**b_width=1280&height=450

height

The height of the image returned, if a width is specified and is smaller than b_width the image height will be scaled down with the same proportions as width/b_width.

/capture?uri=apple.com&width=600&b_width=1280&height=450

Fullpage capture:

If no height is specified in the request the image will have the full height of the web page, this is how you get a fullpage screenshot capture.

/capture?uri=apple.com&width=400&b_width=1280

delay

Some pages are built up with scripts and some scripts might run even after the page has already loaded. As such a page might be rendered a while after it has loaded, in some cases this takes some time. In those cases when we capture an image of the page it can be incomplete and to capture it properly we need to wait a bit. With the 'delay' parameter you can specify how many milliseconds the service should wait after the page is loaded before it captures the image. For instance to wait 0.5 seconds you add `&delay=500` to the request.

/capture/javascript?uri=stripe.com&width=600&b_width=1280&height=450&delay=500

/capture?uri=stripe.com&width=600&b_width=1280&height=450

There are also pages that changes their look dynamically over time, with a slider or animations. To capture such a page at different points in time you can use the delay parameter with different values. Maximum delay supported is 30 seconds, &delay=30000.

NEW! Retina screenshot images

If you need your screenshots with resolution optimizied for high resolution displays, e.g. retina displays.

retina

The retina parameter is optional with a default value of `retina=1.0` for standard retina display simply specify `&retina=2.0` and you will get the screenshot image at double (x 2.0) the resolution. This does not effect the layout etc. for responsive pages etc. The viewport with is still the same as specified by the `&b_width=` parameter

Caching

The PageLr service has built in caching, there are two important reasons to avail of the caching in the service. Foremost it allows to server already captured images really fast, in fractions of a second, secondly captured screenshots served from the cache does NOT count against your Used Capture count in the subscriptions.

maxage

Caching is based on that you specify the oldest screenshot image you are happy with. Many web pages are not updated that frequently so we use a default value of one day `&maxage=86400`. To get a new not cached capture you can specify `&maxage=0` but keep in mind every fresh capture counts against your subscription. Remember by default if you don’t specify a `maxage` screenshots are cached for 24 hours.

Refresh a cached capture

If for some reason you normally use default or bigger maxage, i.e. a week or a few days, but a cached image need to be updated before it becomes too old. You can request the screenshot with the same parameters, and add &maxage=0, this will refresh the image in the cache. After which your normal request will return the fresh image, and you don't have to change any code or change the orginial request parameters.

/capture?uri=apple.com&width=400&b_width=1280&maxage=0

format

By default PNG screenshot images are returned, this due to the PNG formats superior quality when images contains text and sharp edges. Unfortunately this also adds to the download size of the screenshots. When download size and speed is more important than the image quality you can use the 'format' parameter to request a JPEG image instead, add `&format=jpg` to the request.

/capture?uri=apple.com&width=400&b_width=1280&format=jpg

Ad blocking (experimental)

ads

When you need to capture screenshots without advertisement, maybe to avoid adult unrelated content, due to speed or whatnot you can specify &ads=0 in the request, and request for content on the captured page coming from known adservers will be excluded. The service currently blocks ads from this ad server list.

Authorization

You can choose between three different Authorization modes for your subscription:

• Referer

  Typically when you embed a link to the api in a web page, such in a <img> tag's src attribute, the api call is then identified by which domain the page is hosted on. If your page where you refer to an API link is http://www.example.com/page.html, then you specify www.example.com as your referer. Then for your subscription, only api calls (image urls etc.) from this hosting domain are authorized.

• API Key

  Typically when calling the PageLr API programmatically, you identify and associate your calls with your unique 32-character API Key. Add &key=1234ABCD1234ABCD1234ABCD1234ABCD to your urls. You can find your key in your subscription details at Manage Subscription

• Hash Key

  The most secure authorization alternative, requires that each API url with it's hash key is generated server side, or pre-generated before authored in the web pages. You can set your secret phrase in your subscription details at Manage Subscription