Documentation

Introduction

This page will attempt to teach you how to generate screenshots and PDFs of web pages.

Requests

A couple things to know about making requests:

  1. All requests must be POSTs.
  2. All requests must include a key header, which is where you place your API key. This is how we authenticate your requests

Authentication

Every call must include your API key in a key header field.

Example request to grab a screenshot of Google

Note the key header field...
$ curl --header "key: API_KEY" --data "url=https://www.google.com" https://www.screengrabapi.com/api/v1/screenshot.json

Responses

This is how you get your data back.

Format

Responses are in JSON. Deal with it.

Response Properties

There's not much to responses:

  • code - All responses should all include an integer code property, which is just an HTTP status code.
  • data - If code is 200, then this will contain a base64 encoded version of the data you want. This is only present when code == 200.
  • message - If code is not 200, then this should contain an error message explaining what went wrong. This is only present when code != 200.
A successful response looks like this:

{
  "code": 200,
  "data": base64 encoded data
}

And a failed response looks like this:

{
  "code": Error Code,
  "message": An error message,
  ...(there may be additional data)
}

Response Codes

All responses will have a code property.

  • 200 - Everything went fine.
  • 400 - You did something wrong
  • 401 - Missing API key
  • 403 - Invalid API key
  • 429 - Rate limit exceeded
  • 500 - We fucked something up, sorry.

Screenshots

This section will explain how to generate a screenshot of a web page.

Endpoint

The endpoint for generating screenshots is:
https://www.screengrabapi.com/api/v1/screenshot.json

Options

url - String
REQUIRED
The URL you want to take a screenshot of.
type - png/jpg
default png
Set the format of the screenshot.
full - true/false
default false
Determines whether the full page should be captured, or just the viewport.
viewport[width|height] - Ints,
default width=1024, height=768
Determines the viewport width. Use this paramter like:
viewport[width]=1920 and viewport[height]=1080

Examples

Check out these examples of how to take screenshots.

Take a full page screenshot of a Wikipedia page

$ curl --header "key: API_KEY" --data "url=https://en.wikipedia.org/wiki/Web_browser" --data "full=true" https://www.screengrabapi.com/api/v1/screenshot.json

Take a mobile screenshot of CNN

$ curl --header "key: API_KEY" --data "url=https://www.cnn.com" --data "viewport[width]=320" --data "viewport[height]=480" https://www.screengrabapi.com/api/v1/screenshot.json

Generating PDFs

This section will explain how to generate a PDF of a web page.

Endpoint

The endpoint for generating PDFs is:
https://www.screengrabapi.com/api/v1/pdf.json

Options

url - String
REQUIRED
The URL you want to generate a PDF of.
format - String
default Letter
A paper format like Letter, A4, etc.
Cannot be used in conjunction with the width/height options.
width - Int
default null
Set the width of the PDF.
Cannot be used in conjunction with the format option.
height - Int
default null
Set the height of the PDF.
Cannot be used in conjunction with the format option.
pages - Int range
default null
Sets the pages included in the PDF. Use values like 1-10, 2-4, etc. Default is null which will include all pages.
landscape - true/false
default false
Sets the PDF orientation to landscape.
background - true/false
default false
Include the background (colors, images) in the PDF content.

Examples

Check out these examples of how to generate PDFs of a web page.

Generate a PDF of a Wikipedia page

$ curl --header "key: API_KEY" --data "url=https://en.wikipedia.org/wiki/Web_browser" https://www.screengrabapi.com/api/v1/pdf.json

Generate a two page PDF of a long Wikipedia page

$ curl --header "key: API_KEY" --data "url=https://en.wikipedia.org/wiki/Web_browser" --data "pages=2-3" https://www.screengrabapi.com/api/v1/pdf.json