Getting started

The first thing you need is an Auth Key. This is unique to you. You will get it the moment you sign up on PDFRocket.

Before you proceed go ahead and sign up here to get the Auth Key. You will get an Auth Key even on the free plan and the key will allow you access the API 50 times.

Once you have the Auth Key, its time to create a simple page fetcher...

The Simplest Use-Case

The simplest implementation of PDFRocket is by sending a request like this...

curl "https://api.pdfrocket.io/?auth_key=YOUR_KEY&source_url=https://example.com" -o example.pdf

• The source_url can be HTTP or HTTPS protocol
• Inline HTML can be passed directly with the source_html parameter. But you will need to use HTTP POST to do that.
• It's best to url encode the URL value if it contains any variables
• If the Auth key has expired or if you have run out of your quota, this call will return an error
• It will also return an error if the page cannot be found.

Sample code

curl "https://api.pdfrocket.io/?auth_key=YOUR_KEY&source_url=https://example.com" -o example.pdf

  <?php
  $ch = curl_init();
  $url = "https://example.com";
  curl_setopt($ch, CURLOPT_URL,"https://api.pdfrocket.io/?
  auth_key=YOURKEY&source_url=".url_encode($url));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
  curl_setopt($ch, CURLOPT_HEADER, FALSE);
  $response = curl_exec($ch);
  curl_close($ch);

  var_dump($response);

          

var request = require('request');
var url = 'https://example.com';

request(
  {
    method: 'GET',
    url: 'https://api.pdfrocket.io/?auth_key=YOURKEY&source_url=' + url,
    headers: {
      Accept: 'application/json',
    },
  },
  function(error, response, body) {
    console.log(body);
  }
);
          

# importing the requests library 
import requests 
  
# PDFRocket-endpoint 
URL = "https://api.pdfrocket.io"
  
# insert your auth key here
auth_key = "xxxyyy"
url = "https://example.com"
  
# defining a params dict for the parameters to be sent to the API 
PARAMS = {'auth_key':auth_key, 'url':url} 
  
# sending get request and saving the response as response object 
r = requests.get(url = URL, params = PARAMS) 
  
print r.text() 
          

require 'httparty'

url = 'https://api.pdfrocket.io'
query = {
  'auth_key' => 'your auth_key',
  'url' => 'https://example.com'
}

response = HTTParty.get('https://api.pdfrocket.io', query: query)
results = response.body
puts results
          

HTTP GET & POST

Even though the example above uses simple HTTP GET, and is super useful in certain situations, You will need to use the HTTP POST to access some of the more complex features listed below.

Because of this, we have highlighted all the options where HTTP POST is required.

Document Configuration

Lets look at the options we can exercise to configure the PDF document.

Document Name

To change the default name of the downloaded PDF document, pass the preferred name like this...

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &document_name = mydoc.pdf

Set Password

You can optionally set a user level password & a owner level password for your PDFs.

The owner password allows the holder of the password to modify access permissions like copy & edit permissions. The user password only allows access to already specified levels for that user.

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &owner_password = byBigPassword
 &user_password = mySmallPassword

Inline PDF

When you access PDF Rocket through a GET request through the browser, by default, it will force a download.

If you want to override this and show it inline in the browser itself, set the inline option to 1.

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &inline = 1

Accessing Password Protected Websites

If the website you want to render is password protected you can pass the auth_username and the auth_password parameters to let our API access them.

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &auth_username = allowed_user
 &auth_password = secret

Layout

Page Format

PDF Rocket supports various standard page formats. The example below shows you how to set it by using the page_format parameter. If empty, the format defaults to A4.

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &page_format = A5

The list of supported formats are...

These are pre-configured page sizes. if you dont find the exact size you want here you can use the technique listed below to set a custom size for your page.

Custom Size

You can set a custom size for the page using page_width and page_height parameter. These will override the page size parameter listed above

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &page_width = 1200
 &page_height = 800

Orientation

By default, PDF Rocket defaults to portrait. You can set it to landscape by setting the landcape parameter to true

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &landscape = true

Margins

By default, no margins are set by PDF Rocket. You can change that by setting margin_left, margin_right, margin_top and margin_bottom parameters as shown below. You will have to specify either px or cm unit types along with the numeric value. Margins also have to be set before setting the header option shown below

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &margin_left = 10px
 &margin_right = 10px

Headers & Footers

Headers/Footers can be set as normal text or as HTML templates. The templates can be passed by an external url or as inline HTML. Lets explore all the options here

Note: For headers/Footers to work, make sure you have added the appropriate margins.

Plain Text headers/footers

For plain text headers/footers you can set the parameters header_text, header_align, footer_text, footer_align. The headers/footers are center aligned by default

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &margin_top = 50px
 &header_text = MyHeader
 &header_align = right

HTML headers/footers

For HTML headers/footers you can set the parameters header_url or if you want to pass inline HTML, set it to the HTTP POST parameter header_html

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &margin_top = 50px
 &header_url = http://example.com/myheader.html

  
    <style>
    .header{
      width:100%;
      line-height: 24px;
      font-family: 'Helvetica Neue', 'Helvetica', Helvetica, Arial, sans-serif;
      background-color: #333;color:#fff;
      text-align: center;
      font-size: 15px;
      margin-top: 0px;
      height:100px;
      padding-top: 30px;
      float:left;
    }
    </style>


	<div class='header' >
        Printed on {{date}} from {{url}} - {{pageNumber}} of {{totalPages}}
        </div>

As you may have noticed in the HTML above, you can use some select variables in them. You can use {{date}}, {{url}}, {{pageNumber}}, {{totalPages}} & {{title}}

Page customizations

lazy loading & wait_after_load

Many websites have images that lazy load. Some load them as the user scrolls down to them. PDF Rocket simulates this behaviour very well. The default wait_after_load is 1000 milliseconds or 1 sec. Pass a value upto 10000 to wait longer on certain image heavy pages. The example below waits for 5 seconds(while automatically scrolling) before rendering the PDF.

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &wait_after_load = 5000

Custom CSS Injection

Set the parameter css_url to the URL of a file with custom CSS in it. Just like so...

https://api.pdfrocket.io/?auth_key=YOUR_KEY
 &source_url = https://example.com
 &css_url = http://example.com/mycss.css

    body{
      background-color: green !important;
    }

Rate Limits & error handling

Rate limits

Here are the API rate limits based on the plan you are on...

If you exceed the rate limit, the API will return an rate_limit_exceeded error with the code 402.

Error codes

Here are the different error codes and their meaning. When there is an error, the API returns a "error": "description" string with a description of the error.

Code Examples

Starter PHP code

The function pdfRocket() below can be used to access the full range of options in the API. We have included some examples to get you started easily. Replace the API key with your own to try the code. If you dont have an API key, get one for free in just 2 minutes here

<?php


function pdfRocket($params) {
  $curl = curl_init();

  curl_setopt_array ($curl, array (
      CURLOPT_URL => "https://api.pdfrocket.io/",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => json_encode($params),
      CURLOPT_HTTPHEADER => array ('Content-Type:application/json'),
  ));

  $response = curl_exec($curl);
  $error = curl_error($curl);
  $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  curl_close($curl);

  if (!empty($error)) {
      throw new Exception($error);
  } elseif ($statusCode >= 400) {
      $body = json_decode($response, true);
      if (isset($body['error'])) {
          throw new Exception($body['error']);
      } else {
          throw new Exception($response);
      }
  }

  return $response;
}


//Basic Example
$response = pdfRocket(array (
  'auth_key' => 'your_api_key',
  'source_url' => 'https://www.example.com',
));



//Example with custom CSS
$response = pdfRocket(array (
  'auth_key' => 'your_api_key',
  'source_url' => 'https://www.example.com',
  'css_url' => 'https://www.example.commycss.css',
));


//Example with Inline HTML
$source_html = file_get_contents('invoice.html');
$response = pdfRocket(array (
  'api_key' => 'your_api_key',
  'source_html' => $source_html,
  'margin_left' => '40px',
  'margin_right' => '40px'
  
));

//Example with margins
$response = pdfRocket(array (
  'api_key' => 'your_api_key',
  'source_url' => 'https://example.com',
  'margin_left' => '40px',
  'margin_right' => '40px'
  
));



//save the pdf file locally
file_put_contents('result.pdf', $response);

//or show the pdf inline 
//header("Content-type:application/pdf");
//echo $response;