Take Website Screenshots with our RESTful Screenshot API

GrabzIt's REST API allows you to captures URL's or HTML entirely using RESTful techniques. Before you start please read the following caveats carefully depending on your use case one of our other API solutions maybe more suitable.

- Some features such as merging and encrypting captures are not available through this REST API. To use these features you will need to use another API Library
- Do not use this API on the client side, it will expose your Application Key! Instead use the JavaScript API
- To limit which servers can access your API, authorize the IP Addresses you want to grant access to

To get started just select what you want to do from the filter below and the available parameters will be displayed along with a basic example.

What do you want to do?

Below is the API URL, that is used for all REST API calls. When making requests please ensure all parameter values are URL encoded.

https://api.grabz.it/convert?key=Sign in to view your Application Key&format=&url=https%3A%2F%2Fwww.bbc.com%2F

Below is the API URL, that is used for all REST API calls. When converting HTML all parameters must be posted in the request body as key-value pairs. Ensure all parameter values are URL encoded, and the content type is application/x-www-form-urlencoded.

curl 
    -d key=Sign in to view your Application Key 
    -d format= 
    -d html=%3Ch1%3EConvert%20Me%21%3C%2Fh1%3E 
    https://api.grabz.it/convert

The capture will then be returned in the HTTP response. The following additional options are also available with this type of capture, all of which are optional except for those marked as required. When testing the API functionality we recommend using Postman to simplify the process.

url - the URL to the capture.
- Required
html - the HTML to the convert.
- Required
- When converting HTML you must use a HTTP POST.
key - your Application Key.
- Required
callback - the URL of the handler GrabzIt should call after it has completed its work.
- Find out how to create a handler by following the documentation for each language ASP.NET, Java, Node.js, Perl, PHP, Python and Ruby.
customid - the custom identifier that you can associate with the capture.
- This will be returned with any callback URL you have specified.
format - the format the capture should be in.
- Default: jpg
- Options:
  - bmp8
  - bmp16
  - bmp24
  - bmp
  - csv
  - gif
  - html
  - jpg
  - json
  - pdf
  - docx
  - png
  - seo
  - tiff
  - mp4
  - webp
  - xlsx
address - the URL to execute the HTML code in. Can be useful if the HTML being converted uses relative URL's to resources such as CSS and images.
- Default: empty
background - if true the background of the web page should be included in the PDF
- Default: 1
- Options:
  - 0 = indicates the PDF document should not include the web page background
  - 1 = indicates the PDF document should include the web page background
background - if true the background images of the web page should be included in the DOCX
- Default: 1
- Options:
  - 0 = indicates the DOCX document should not include the web page background images
  - 1 = indicates the DOCX document should include the web page background images
bwidth - the width of the browser in pixels
- Default: 1366
- Maximum: 10000
- Auto Width: -1 (passing -1 means that the width of the browser matches the width of the document)
bheight - the height of the browser in pixels.
- Default: 1170
- Maximum: 10000
- Full Length: -1 (passing -1 means that a sceenshot of the whole web page is taken)
click - this specifies the HTML element, using a CSS selector to click. Remember a delay may also be required to view the effects of the click
country - the country the screenshot/capture should be taken from.
- Default: The current fastest location
- Options: "SG", "UK", "US"
coverurl - the URL of a web page that should be used as a cover page for the PDF
- Default: empty
customwatermarkid - add a custom watermark or special watermark to the file
- Default: empty
delay - the number of milliseconds to wait before taking the screenshot
- Default: 0
- Maximum: 30000
duration - the length in seconds of the video that should be converted into a animated GIF.
- Default: maximum length for package
duration - the length in seconds of the web page should be recorded for.
- Default: 10
- Maximum: 60
export - the export URL that specifies where the capture should be exported too.
fps - the number of frames per second that should be captured.
- Default: 10
- Minimum: 0.2
- Maximum: 60
fps - the number of frames per second that should be captured.
- Default: 1
- Minimum: 0.2
- Maximum: 20
hd - if true the image capture will be in high definition this doubles the size of the image dimensions.
- Default: 0
- Options:
  - 0 = create a high definition image
  - 1 = create a high definition image
height - the height of the resulting thumbnail in pixels
- Default: if both the output width and output height are not specified or 0 then the output width and height will match the final image width and height, if the output width is specified the output height will be proportional to the output width
- Maximum: Maximum height for package
- Full Height: -1 (passing -1 means that the height of the thumbnail is not reduced)
height - the height of the resulting video in pixels
- Default: if not set it will match the browser height
- Maximum: Maximum height for package
height - the custom height of the resulting document in mm
- Default: page size height
- Minimum: 15
- Full Length: -1 (passing -1 means that the page height is equal to the web page)
height - the height of the resulting animated GIF in pixels.
- Default: 120px
- Maximum: Maximum height for package
- Auto-size: -1 (passing -1 means that the height of the animated GIF is scaled in relation to its width, if the height is being auto-sized the width cannot)
hide - the CSS selectors of the one or more HTML elements in the web page to hide, to specify multiple HTML elements to hide seperate each selector with a comma.
- Default: empty
includealltables - if true all table on the web page will be extracted with each table appearing in a separate spreadsheet sheet.
- Only available with the XLSX format
- Default: 0
- Options:
  - 0 = indicates all the tables will not be extracted
  - 1 = indicates all the tables will be extracted
includeheadernames - if true header names will be included in the table
- Default: 1
- Options:
  - 0 = indicates the header names will not be include in the table
  - 1 = indicates the header names will be include in the table
includeimages - if true the images of the web page should be included in the DOCX
- Default: 1
- Options:
  - 0 = indicates the DOCX document will not include web page images
  - 1 = indicates the DOCX document will include web page images
includelinks - true if links should be included in the document
- Default: 1
- Options:
  - 0 = indicates the document should not include links
  - 1 = indicates the document should inlcude links
includeoutline - true if PDF bookmarks should be included
- Default: 0
- Options:
  - 0 = indicates the PDF document will not include a outline
  - 1 = indicates the PDF document will include a outline
mergeid - add the ID of a capture that should be merged at the beginning of the new document
- Default: empty
mtop - the margin in millimeters that should appear at the top of the document page
- Default: 10
mleft - the margin in millimeters that should appear at the left of the document page
- Default: 10
mbottom - the margin in millimeters that should appear at the bottom of the document page
- Default: 10
mright - the margin in millimeters that should appear at the right of the PDF document
- Default: 10
media - the CSS Media Type of the PDF document
- Default: Screen
- Options:
  - Print
  - Screen
noads - if true adverts should be automatically hidden.
- Default: 0
- Options:
  - 0 = display adverts
  - 1 = hide adverts
nonotify - if true all commonly found cookie notifications should be automatically hidden.
- Default: 0
- Options:
  - 0 = display cookie notifications
  - 1 = hide cookie notifications
orientation - the orientation of the document
- Default: Portrait
- Options:
  - Portrait
  - Landscape
pagesize - the page size of the document
- Default: A4
- Options:
  - A3
  - A4
  - A5
  - A6
  - B3
  - B4
  - B5
  - B6
  - Legal
  - Letter
password - the password to protect the document with
- Default: empty
proxy - the HTTP proxy details the browser software should use to use to create this capture
post - any post parameters you want to send.
quality - the quality of the capture, JPG, DOCX, PDF and WEBP have a default compression of 90% and GIF 85%. This parameter has no effect on BMP, PNG or TIFF images.
- Reducing the quality will reduce the filesize and reduce download times.
- Default: -1
- Minimum: -1
- Maximum: 100
repeat - number of times to loop the animated GIF.
- Default: 0
- Loop Continuously: 0
- Never Loop: -1
reverse - if true the frames of the animated GIF are reversed
- Default: 0
- Options:
  - 0 = indicates the animation will not be reveresed
  - 1 = indicates the animation will be reversed
requestas - the type of user agent you wish to use
- Default: 0
- Options:
  - 0 = indicates the standard version of the website should be returned
  - 1 = indicates the mobile version of a website should be returned
  - 2 = indicates the search engine view of a website should be returned
speed - the speed of the animated GIF.
- Default: 1
- Minimum: 0.2
- Maximum: 10
start - the starting position of the video that should be converted into a animated GIF.
- Default: 0 seconds
start - the starting time in seconds after loading that the video should be captured from.
- Default: 0 seconds
tabletoinclude - the index of the table to be converted, were all tables in a web page are ordered from the top of the web page to bottom
- Default: 1
target - this parameter specifies the CSS selector of the only HTML element on the target web page that is to be turned into a document, all other parts of the web page are ignored. If there are multiple matching HTML elements the first one is chosen.
- Default: empty
target - this parameter specifies the CSS selector of the only HTML element on the target web page that is to be turned into a image, all other parts of the web page are ignored. If there are multiple matching HTML elements the first one is chosen.
- Default: empty
target - the id of the only HTML element in the web page that should be used to extract tables from
- Default: empty
transparent - if true the image capture should be transparent. This is only compatible with png and tiff images.
- Default: 0
- Options:
  - 0 = create a non-transparent image
  - 1 = create a transparent image
templateid - add a template ID that specifies the header and footer of the document
- Default: empty
tvars - add custom template variables. These variables must come as a key and value pair and be seperated by a equals sign, with each value in the key value pair URL encoded. If there are multiple pairs, each pair should be seperated by a ampersand. For example: a=1&b=2
- Default: empty
title - provide a title to the PDF document
- Default: empty
waitfor - this specifies the HTML element, using a CSS selector. Once the element is visible the capture is executed. If there are multiple matching HTML elements the first one is chosen. When this parameter is used it will wait for a maximum of 25 seconds before the capture is performed.
width - the width of the resulting thumbnail in pixels
- Default: if both the output width and output height are not specified or 0 then the output width and height will match the final image width and height, if the output height is specified the output width will be proportional to the output height
- Maximum: Maximum width for package
- Full Width: -1 (passing -1 means that the width of the thumbnail is not reduced)
width - the width of the resulting video in pixels
- Default: if not set it will match the browser width
- Maximum: Maximum width for package
width - the custom width of the resulting document in mm
- Default: page size width
- Minimum: 15
width - the width of the resulting animated GIF in pixels.
- Default: 180px
- Maximum: Maximum width for package
- Auto-size: -1 (passing -1 means that the width of the animated GIF is scaled in relation to its height, if the width is being auto-sized the height cannot)

User Details

Get your current account package, and remaining allowance with this simple call.

https://api.grabz.it/user?key=Sign in to view your Application Key

Header and Footer Templates

Get the list of header and footer templates for PDF and DOCX files associated with your account, like so.

https://api.grabz.it/templates?key=Sign in to view your Application Key

Web Monitors

Add Monitor

Add a URL to monitor from your app with this easy call. This will return a JSON object of the web monitor including its identifier.

key - your Application Key.
- Required
url - the URL to the monitor.
- Required
callbackurl - the webhook to notify of a change.
email - the email address to notify of a change.
repeat - how often in minutes the URL should be checked for a change.
cssselector - the CSS selector that should be used to identify what part of the web page should be monitored.
- Specify :root to monitor the whole web page

https://api.grabz.it/monitor?key=Sign in to view your Application Key&url=https://www.astropioneer.blog&email=hello@example.com&repeat=60&cssselector=%23id1

Delete Monitor

To delete a web monitor just specify its ID, along with your application key. You get the ID when creating the monitor from the Add Monitor web method above. On success it will return true in the result attribute.

https://api.grabz.it/monitor/[Monitor ID]/delete?key=Sign in to view your Application Key

Error Handling

If there is some issue with the request you have made to the API, a JSON object will be returned explaining the error. The best way to determine this is to check the content type of the response before processing, if its application/json an error has occurred. The error code found in the JSON follows the standard list of codes.

{
    "Result": false,
    "Code":"URL is missing",
    "Message":100
}