Documentation
Introduction
The SavePage API can be used to programmatically retrieve screenshot image of any URL.
Using the powerful rendering engine of the real Chrome browser, you can quickly get a perfect snapshot of any website.
Quick start
How to get access to the SavePage API
The SavePage uses API keys for authorization. An API key is a special access token that the client needs to provide as a query parameter when making API calls.
You can sign up for a free API key here. Our Free Plan offers generous limits for getting started with SavePage.
API Endpoint
The endpoint will accept either GET or POST requests. For maximum security, always use POST HTTPS requests.
https://api.savepage.io/v1/
Required parameters
Our API uses query parameters since they are the simplest and the most common type of parameters.
When using GET request they appear at the end of the request URL after a question mark (?), with name=value pairs separated by ampersands (&). When using POST request, query parameters are sent in the body with appropriate Content-Type header.
| Name | Description | Example | Required |
|---|---|---|---|
key | Your API key | 123456 | Yes |
q | URL you want to request a snapshot from* | https://www.google.com | Yes |
* Since this parameter can contain reserved characters :/?#[]@!$&'()*+,;= it should be sent as percent-encoded (encodeURIComponent/urlencode).
Example API request
https://api.savepage.io/v1/?key=123456&q=https://www.google.com
Optional parameters
| Name | Description | Example | Default | Plans |
|---|---|---|---|---|
width | Page viewport width in pixels | 800 | 1440 | Basic/Pro |
height | Page viewport height in pixels | 600 | 900 | Basic/Pro |
fullpage | Request full page render | true | false | Basic/Pro |
thumb_width | Resize screenshot image based on width in pixels | 400 | - | Basic/Pro |
delay | Wait for the specified number of seconds after the webpage has loaded | 2 | 0 | Basic/Pro |
nocookie | Prevent cookie banners and popups from being displayed | true | false | All |
noads | Prevent ads, tracking, and analytics code | true | false | All |
format | Image format, jpeg or png are accepted | jpeg | jpeg | All |
refresh | Refresh the screenshot if the cached version is older than n seconds | 3600 | - | All |
user_agent | Custom User-Agent header* | Firefox 77 | - | All |
accept_language | Custom Accept-Language header | en-US | - | All |
maxage | Specify the time in seconds for Cache-Control response header | 3600 | 2629746 | All |
cookie | Pass login or other information stored in the Cookie data** | SID=zx5r3Vm; q=5 | - | All |
hash | Required when using API Secret word, md5(URL+APISecret) | 8udI3nt3xidnwq90In | - | All |
*Since this parameter can contain reserved characters :/?#[]@!$&'()*+,;= it should be sent as percent-encoded (encodeURIComponent/urlencode).
**Limited to POST requests for security reasons. This data should be sent in the POST request body.
Example: requesting mobile website
https://api.savepage.io/v1/?key=123456&q=https://www.google.com&width=390&height=844&accept_language=fr-CA&user_agent=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%2012_2%20like%20Mac%20OS%20X%29%20AppleWebKit%2F605.1.15%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F15E148
Example: POST request using CURL
curl -X POST https://api.savepage.io/v1 --data "key=123456&q=https://www.google.com&width=300" --output image.jpg
Response
The successful API response will be sent as HTTP 200 OK, and it will contain the screenshot image.
The following headers will be sent with each response:
| Value | Description |
|---|---|
Cache-Control: public, max-age=2629746; | How long the content stays in the browser’s cache (configurable) |
Last-Modified: Thu, 09 Sep 2021 07:44:07 GMT | Time when the image was last modified |
Content-Type: image/jpeg | Image type (configurable) |
Content-Length: 44360 | Image size in bytes |
If the browser issues a request with the If-Modified-Since header, and if the image hasn’t been modified since the last modified time, then a 304 - Not modified response is generated. This response tells the browser that the image in its local cache hasn’t changed, and its cache lifetime can be renewed.
Note: Other headers from intermediate proxies and CDN may be present as well.
Workers
Each API request launches a single worker to generate the screenshot. While creating a screenshot, the worker is considered busy. If all your workers are currently busy, you will get a 481 error on your API calls until a worker is free again. In practice, this means that if you have a single worker, all your requests can be performed in a sequential fashion. While if you have multiple workers, you can request and process several screenshots at the same time.
Caching
The SavePage API will cache all requested screenshot images. The exact TTL depends on various parameters and it can take up to a month for all cached images to expire.
If the API request is sent with the refresh=-1 parameter, the screenshot will be re-rendered, the image will be updated, and the Last-Modified header will be set accordingly.
Errors
If the request cannot be successfully completed, an HTTP response with a 422 status code will be returned. The response from the API may also contain one or more error elements in the JSON response. This information can be used to determine what went wrong.
Error codes:
| Code | Description |
|---|---|
| 461 | Cannot verify the API Key |
| 462 | Invalid or blank URL sent |
| 471 | Invalid security hash, access denied |
| 472 | IP restricted, access denied |
| 473 | Origin restricted, access denied |
| 474 | Too many requests from the same IP address |
| 481 | All workers are busy, please try again later |
| 482 | Too many requests, limit exceeded for this plan |
| 483 | Too many screenshots, limit exceeded for this plan |
| 490 | Rendering error, cannot generate screenshot |
| 491 | Cache error, cannot fetch the cached image |
Example error reponse:
{"error":"Cannot verify the API Key"}
Rendering Engine
Our rendering engine can only retrieve publicly accessible pages. Unfortunately, we cannot guarantee the correct screenshot response for every single URL. Some of the reasons for the failed, blank, or inaccurate screenshot are beyond our control:
- Pages that require authentication or login
- Slow pages or servers with slow response times
- Advanced bot-prevention installed at the targeted website
- Captcha or Paywall protection installed
- Temporary networking issues or downtimes
- Restrictions based on IP address or range of addresses (known cloud providers block)