HyPDF is a service that provides the full set of tools for working with PDF documents.
With HyPDF you can:
Moreover, HyPDF can upload created PDFs to your own AWS S3 bucket for you.
HyPDF is accessible via a simple API and has supported client library for Ruby, though it can be used by any language with support for making HTTP requests.
Ruby/Rails applications will need to add the following entry into their Gemfile specifying the HyPDF client library.
gem 'hypdf', '~> 1.0.19'
Update application dependencies with bundler.
$ bundle install
Call htmltopdf
method with your HTML/URL and optional parameters and get your document directly. Tip: use test option during the development.
@hypdf_response = HyPDF.htmltopdf(
'<html><body><h1>Title</h1></body></html>',
user: YOUR_HYPDF_USER,
password: YOUR_HYPDF_PASSWORD,
# ... other options ...
)
# send PDF to user
send_data(
@hypdf_response[:pdf],
filename: "pdf_with_#{@hypdf_response[:pages]}_pages.pdf",
type: 'application/pdf'
)
# or write to file
File.open('file_name.pdf', 'wb') do |f|
f.write(@hypdf_response[:pdf])
end
HyPDF is accessible via a HTTP API described in API reference section.
The simplest CURL example:
$ curl --data 'content=<html><body><h1>Title</h1></body></html>&user=YOUR_HYPDF_USER&password=YOUR_HYPDF_PASSWORD' https://www.hypdf.com/htmltopdf > test.pdf
Python example (using flask and requests):
import requests
from flask import Flask
from flask import request
app = Flask(__name__)
# Make request to the HyPDF and upload the created file to the AWS S3 in an asynchronous style.
@app.route("/")
def index():
params = {'user': 'YOUR_HYPDF_USER', 'password': 'YOUR_HYPDF_PASSWORD', 'test': 'true', 'content': '<html><body><h1>Title</h1></body></html>', 'bucket': 'hypdf_test', 'key': 'hypdf_test.pdf', 'public': 'true', 'callback': 'http://yoursite.com/pdf_complete'}
r = requests.post('https://www.hypdf.com/htmltopdf', data=params)
return r.json()['job_id']
# Get response from the HyPDF
@app.route("/pdf_complete", methods=['POST'])
def print_pdf_data():
print 'job_id: ' + request.headers['hypdf-job-id']
print 'number of pages: ' + request.headers['hypdf-pages']
print 'url: ' + request.form['url']
return 'ok'
if __name__ == "__main__":
app.run()
Node.js example (using request):
var request = require('request'),
fs = require("fs");
// Create PDF and upload it to AWS S3
request.post(
'https://www.hypdf.com/htmltopdf',
{
json: {
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
content: '<html><body><h1>Title</h1></body></html>',
margin_left: '0.5in',
bucket: 'YOUR_BUCKET_NAME',
key: 'some_file_name.pdf',
public: true
}
},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log('Public URL: ', body.url);
console.log('Number of pages: ', response.headers['hypdf-pages']);
}
}
);
Also there are unofficial Node.js and Java wrappers for the HyPDF API.
Create PDF file from provided HTML or URL.
Ruby:
@hypdf_response = HyPDF.htmltopdf(
'<html><body><h1>Title</h1></body></html>',
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
# ... other options ...
)
# => {pdf: BINARY_PDF_DATA, pages: 1, page_size: "792 x 612 pts (letter)", pdf_version: 1.4}
In other languages just make HTTP request with these parameters:
URL: 'https://www.hypdf.com/htmltopdf'
Method: 'POST'
Content-Type: 'application/json'
Parameters: {content: 'YOUR_HTML', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD'}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Value type | Description |
---|---|---|
test | Boolean | Enable test mode. Defaults to false |
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | Boolean | Grant everyone read access to uploaded file. Defaults to false |
preview | Boolean | Generate preview image for uploaded file. Defaults to false |
callback | String | Create PDF in the background and post results to this URL. |
landscape | Boolean | Landscape paper orientation. Defaults to false |
scale | Float | Scale of the webpage rendering. Defaults to 1. Scale amount must be between 0.1 and 2 |
format | String | Standart paper sizes "letter", "legal", "tabloid", "ledger", "A0", "A1", "A2", "A3, "A4", "A5", "A6" |
paper_width | Float | Paper width in inches. Defaults to 8.5 inches |
paper_height | Float | Paper height in inches. Defaults to 11 inches |
margin_top | Float | Top margin in inches. Defaults 0.4 inches (1cm) |
margin_bottom | Float | Bottom margin in inches. Defaults to 0.4 inches (1cm) |
margin_left | Float | Left margin in inches. Defaults to 0.4 inches (1cm) |
margin_right | Float | Right margin in inches. Defaults to 0.4 inches (1cm) |
header_template | String | HTML template for the document header. Should be valid HTML markup |
footer_template | String | HTML template for the document footer. Should be valid HTML markup |
In footer/header templates you can use "pageNumber", "totalPages", and "date" classes to inject printing values into them:
<div style='font-size:12px;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>
Important note: headers and footers don’t inherit styles from the rest of the page and can’t use external resources. If you need to use images you can convert them to Data URI format with any converter.
This method allows to check background job status.
Ruby:
@hypdf_response = HyPDF.jobstatus(
'ae19dafbb8d4880929d89af6', # your job ID
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
)
# => {"job_id"=>"ae19dafbb8d4880929d89af6", "status"=>"working"}
Other languages:
URL: 'https://www.hypdf.com/jobstatus'
Method: 'GET'
Content-Type: 'application/json'
Parameters: {job_id: 'JOB_ID', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD'}
Result: 'json'
Possible statuses: waiting
, working
, complete
, failed
.
Read meta-information of the document.
Ruby:
@hypdf_response = HyPDF.pdfinfo(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD'
)
# => {"Title"=>"Everyday Rails Testing with RSpec", "Author"=>"Aaron Sumner", "Creator"=>"LaTeX with hyperref package", "Producer"=>"xdvipdfmx (0.7.8)", "CreationDate"=>"Fri Aug 2 05", "32"=>"50 2013", "Tagged"=>"no", "Pages"=>"150", "Encrypted"=>"no", "Page size"=>"612 x 792 pts (letter)", "Optimized"=>"no", "PDF version"=>"1.5"}
Other languages:
URL: 'https://www.hypdf.com/pdfinfo'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD'}
Result: 'json'
Edit metadata of the document.
@hypdf_response = HyPDF.editmeta(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
'Author' => 'Plato',
'Title' => 'Apology'
)
# => {pdf: BINARY_PDF_DATA}
Other languages:
URL: 'https://www.hypdf.com/editmeta'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD', Author: 'Plato', ...}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
test | true, false | Use test mode. |
Title | String | Document title. |
Subject | String | Document subject. |
Author | String | Document author. |
Creator | String | Document creator. |
Producer | String | Document producer. |
Copyright | String | Document copyrights information. |
Keywords | String | Document keywords. |
CreateDate | String | Document creation date in ISO 8601 format, e.g. "2015-06-25T14:09:25Z". |
ModifyDate | String | Document modification date in ISO 8601 format, e.g. "2015-06-25T14:09:25Z". |
all | String | Update all tags at once. |
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | true, false | Grant everyone read access to uploaded file. |
If your document has the Dublin Core metadata you can edit it with special “xmp-dc:”-prefix, for example: “xmp-dc:Creator”, “xmp-dc:Subject”, “xmp-dc:all”.
Extract text content from the document.
Ruby:
@hypdf_response = HyPDF.pdftotext(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
first_page: 2,
last_page: 5,
# ... other options ...
)
# => {text: "Everyday Rails Testing with RSpec\nA practical approach to test-driven..."}
Other languages:
URL: 'https://www.hypdf.com/pdftotext'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD', ...}
Result: 'json'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
first_page | Integer | First page to convert. |
last_page | Integer | Last page to convert. |
no_page_break | true | If present, don't insert page breaks between pages. |
crop_x | Integer | x-coordinate of the crop area top left corner. |
crop_y | Integer | y-coordinate of the crop area top left corner. |
crop_width | Integer | Width of crop area in pixels. |
crop_height | Integer | Height of crop area in pixels. |
Extract certain pages from the document.
Ruby:
@hypdf_response = HyPDF.pdfextract(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
first_page: 2,
last_page: 5,
# ... other options ...
)
# => {pdf: BINARY_PDF_DATA}
Other languages:
URL: 'https://www.hypdf.com/pdfextract'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD', ...}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
first_page | Integer | First page to extract. |
last_page | Integer | Last page to extract. |
test | true, false | Use test mode. |
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | true, false | Grant everyone read access to uploaded file. |
Merge a few documents into one.
Ruby:
@hypdf_response = HyPDF.pdfunite(
'/path/to/file1.pdf', # or instance of File class
'/path/to/file2.pdf', # or instance of File class
'/path/to/file3.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
# ... other options ...
)
# => {pdf: BINARY_PDF_DATA}
Other languages:
URL: 'https://www.hypdf.com/pdfunite'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file_1: 'BINARY_PDF_DATA', file_2: 'BINARY_PDF_DATA', file_3: ..., user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD'}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
test | true, false | Use test mode. |
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | true, false | Grant everyone read access to uploaded file. |
Read form fields' names and values from PDF.
Ruby:
@hypdf_response = HyPDF.readform(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD'
)
# => {"field_name"=>"Field value"}
Other languages:
URL: 'https://www.hypdf.com/readform'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD'}
Result: 'json'
Fill form fields in the existed PDF with provided values. If you don't know form fields' names use readform method.
Ruby:
@hypdf_response = HyPDF.fillform(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
field_name: 'New field value',
# ... other options ...
)
# => {pdf: BINARY_PDF_DATA}
Other languages:
URL: 'https://www.hypdf.com/fillform'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD', field_name: 'New field value'}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
test | true, false | Use test mode. |
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | true, false | Grant everyone read access to uploaded file. |
Encrypt PDF with provided password.
Ruby:
@hypdf_response = HyPDF.encryptpdf(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
pdf_password: 'SOME_PASSWORD',
# ... other options ...
)
# => {pdf: BINARY_PDF_DATA}
Other languages:
URL: 'https://www.hypdf.com/encryptpdf'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD', pdf_password: 'some_password'}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | true, false | Grant everyone read access to uploaded file. |
Remove password from encrypted PDF.
Ruby:
@hypdf_response = HyPDF.decryptpdf(
'/path/to/file.pdf', # or instance of File class
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
pdf_password: 'PDF_PASSWORD',
# ... other options ...
)
# => {pdf: BINARY_PDF_DATA}
Other languages:
URL: 'https://www.hypdf.com/decryptpdf'
Method: 'POST'
Content-Type: 'multipart/form-data'
Parameters: {file: 'BINARY_PDF_DATA', user: 'YOUR_HYPDF_USER', password: 'YOUR_HYPDF_PASSWORD', pdf_password: 'pdf_password'}
Result: 'BINARY_PDF_DATA'
Optional parameters:
Option name | Possible value | Description |
---|---|---|
bucket | String | Upload created PDF to this AWS S3 bucket. |
key | String | File name. |
public | true, false | Grant everyone read access to uploaded file. |
During the development you may want to use the test mode. In this case HyPDF do not count against your daily document quota.
@hypdf_response = HyPDF.pdfunite(
'/path/to/file1.pdf',
'/path/to/file2.pdf',
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
test: true
)
HyPDF can upload created files to your AWS S3 bucket, but before you need to give permission HyPDF to do it.
Policy:
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::495273932038:root"
},
"Action": [
"s3:GetBucketAcl",
"s3:PutObjectAcl",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::YOUR_BUCKET_NAME/*",
"arn:aws:s3:::YOUR_BUCKET_NAME"
]
}
]
}
After that you can use the bucket
option in HyPDF methods:
@hypdf_response = HyPDF.htmltopdf(
'<html><body><h1>Title</h1></body></html>',
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
# ... other options ...
bucket: 'YOUR_BUCKET_NAME',
key: 'some_file_name.pdf', # optional
public: true # optional, generate public readable URL
)
# => { url: "https://s3.amazonaws.com/YOUR_BUCKET_NAME/some_file_name.pdf", pages: 1, page_size: "792 x 612 pts (letter)", pdf_version: 1.4, bucket: "YOUR_BUCKET_NAME", key: "some_file_name.pdf"}
You don’t need to wait and block your application until the document is created, HyPDF can handle your files in asynchronous style. Just provide callback URL that will be called when PDF will be ready.
def create
@hypdf_response = HyPDF.htmltopdf(
'<html><body><h1>Title</h1></body></html>',
user: 'YOUR_HYPDF_USER',
password: 'YOUR_HYPDF_PASSWORD',
# ... other options ...
callback: 'http://www.your-application.com/save_pdf_url',
bucket: 'YOUR_BUCKET_NAME',
key: 'some_file_name.pdf',
public: true
)
# You can check job status in any time
puts HyPDF.jobstatus(@hypdf_response[:job_id])
end
# POST /save_pdf_url
def save_pdf_url
if params[:error]
puts params[:message]
else
# PDF url
puts params[:url]
# Job ID
puts request.headers['hypdf-job-id']
# Number of pages
puts request.headers['hypdf-pages']
end
end
All HyPDF support and runtime issues or product feedback are welcome at support@hypdf.com. Also feel free to subscribe to our Twitter account.