Overview
The Pdfcrowd API v2 is the new generation of our
API. It is not 100% backward compatible but the changes are mostly syntactic and
the migration from API v1 should be straightforward.
If you want to switch your current API v1 plan to API v2, please follow these steps:
- Activate the free API v2 trial in your account page.
- Follow the instructions below and migrate your API v1 implementation to API v2.
- If the API v2 works to your satisfaction, choose from our API v2 plans.
- If you no longer need the API v1 implementation, you can cancel the API v1 plan.
API v2 Links
API client libraries
If you use our API client library, install the latest version from the
API home page. The library supports both API
versions and you can easily run both implementations side by side under your
current Pdfcrowd account.
The migration should consist of these steps:
- Instantiate the API v2 client.
- Migrate the convert*** method (the one that returns PDF).
- Migrate the conversion settings.
- Error handling (important)
API client instantiation
The code below shows how to instantiate API clients. The first line corresponds
to what you have in your current API v1 implementation (client_v1). The second
line shows how to instantiate the API v2 client (client_v2).
// PHP
client_v1 = new Pdfcrowd("username", "apikey")
client_v2 = new \Pdfcrowd\HtmlToPdfClient("username", "apikey")
// Java
Client client_v1 = new Client("username", "apikey");
Pdfcrowd.HtmlToPdfClient client_v2 = new Pdfcrowd.HtmlToPdfClient("username", "apikey");
// .NET
pdfcrowd.Client client_v1 = new pdfcrowd.Client("username", "apikey");
pdfcrowd.HtmlToPdfClient client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey");
# Ruby
client_v1 = Pdfcrowd::Client.new("username", "apikey");
client_v2 = Pdfcrowd::HtmlToPdfClient.new("username", "apikey");
# Python
client_v1 = pdfcrowd.Client("username", "apikey")
client_v2 = pdfcrowd.HtmlToPdfClient("username", "apikey")
// Node.js
var client_v1 = new pdf.Pdfcrowd("username", "apikey")
var client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey")
Conversion methods
The following table shows the mapping of conversion methods.
Conversion settings methods
If your API implementation is in Node.js, continue below.
If your API v1 implementation customizes the conversion settings, check the
following table to find the corresponding API v2 functionality.
Node.js
API client instantiation:
// Node.js
var client_v1 = new pdf.Pdfcrowd("username", "apikey")
var client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey")
The API v1 client uses a dictionary of options. API v2 uses methods on the client object.
// API v1
client_v1.convertURI(
'http://example.com',
pdf.saveToFile("example.pdf"), {
width: "11in",
height: "8.5in",
user_print_media: true,
}
);
// API v2
client_v2.setPageSize("Letter");
client_v2.setUsePrintMedia(true);
client_v2.convertUrlToFile(
"http://example.com",
"example.pdf",
function(err, fileName) {
if (err) return console.error("Pdfcrowd Error: " + err);
// success, pdf was saved to fileName
});
See the
HTML to PDF API v2 - Node.js
documentation for more examples.
The following table maps API v1 options to API v2 methods. The mapping of the
convert*** methods is here.
HTTP access
The API v2 endpoint is https://api.pdfcrowd.com/convert/
The authentication method for user credentials is HTTP Basic Access Authentication.
Convert URL
# API v1
curl -F "username=username" -F "key=apikey" \
-F 'src=http://example.com' \
-o example.pdf \
https://pdfcrowd.com/api/pdf/convert/uri/
# API v2
curl -f -u "username:apikey" \
-F "url=http://www.example.com" \
-o example.pdf \
https://api.pdfcrowd.com/convert/
Convert file
# API v1
curl -F "username=username" -F "key=apikey" \
-F 'src=@example.html' \
-o example.pdf \
https://pdfcrowd.com/api/pdf/convert/html/
# API v2
curl -f -u "username:apikey" \
-F "file=@example.html" \
-o example.pdf \
https://api.pdfcrowd.com/convert/
Convert string
# API v1
curl -F "username=username" -F "key=apikey" \
-F "src=<html><body><h1>Hello World!</h1></body></html>" \
-o hello.pdf \
https://pdfcrowd.com/api/pdf/convert/html/
# API v2
curl -f -u "username:apikey" \
-F "text=<html><body><h1>Hello World!</h1></body></html>" \
-o hello.pdf \
https://api.pdfcrowd.com/convert/
The following table maps API v1 options to API v2 options.
Miscellaneous
Variables
Replace variables with HTML classes:
%u ⇒ pdfcrowd-source-url
%p ⇒ pdfcrowd-page-number
%n ⇒ pdfcrowd-page-count
<!-- API v1 -->
Page %p of %n.
<!-- API v2 -->
Page <span class='pdfcrowd-page-number'></span> of <span class='pdfcrowd-page-count'></span>.
Placement
API v1 places headers and footers to the margin area. API v2 places them to the
printing area. The height of the header and footer can be set with
setHeaderHeight
and
setFooterHeight.
Units
API v1 allows to specify a unit-less numeric value that is interpreted as
points (1/72 of an inch). API v2 doesn't allow this, the value must be
specified with a mm, in, cm or pt suffix.
Addendum
New API v2 methods |
API v1 methods having no counterpart in API v2 |
|
- setHtmlZoom
- enableHyperlinks
- setTransparentBackground
- setWatermarkRotation
|
New API v2 options |
API v1 options having no counterpart in API v2 |
|
- html_zoom
- no_hyperlinks
- transparent_background
- watermark_offset_x
- watermark_offset_y
- watermark_rotation
- pdfcrowd_logo
|