API Documentation

To help you use Conversion Services from your personal server or a standalone PC we developed this REST API.

You can find out more in the documentation below.


Available Conversion Services

The API allows you to access the following Conversion Services:

  • HTML Page to PDF (file upload)
  • HTML Page to PDF (page by URL)
  • HTML Table to CSV (file upload)
  • HTML Table to CSV (page by URL)
  • Make Website Snapshot
  • Excel (XLS) to PDF
  • Excel (XLS) to HTML
  • Excel (XLS) to CSV
  • OpenOffice Calc (ODS) to CSV
  • CSV to Excel (XLS)
  • XML to CSV
  • XML to Excel (XLS)
  • Image to PDF
  • CSV to XML
  • PDF to Text

API URL

API is available at the following URL:

https://conversiontools.io/api/<request>

Where <request> is one of the available API commands.


API Response

API responses are encoded in JSON format:

{ code: <return-code>, message: "<message-text>" }

In case of success, <return-code> will be equal to 0 and <message-text> will contain "OK", like this:

{ code: 0, message: "OK" }

In case of error, <return-code> will be a non-zero value and <message-text> will contain more information about the error:

{ code: 1, message: "Error message" }

API Commands

File conversion process consists of the following 4 phases:

  1. Uploading file to server
  2. Running conversion task
  3. Checking task status
  4. Downloading result file

In case a Conversion Service doens't require to perform file upload (URL is provided), then you have to skip phase 1.


1. Uploading file to server

For this you should use a regular HTTP POST file upload request (e.g. via a form) with the enctype="multipart/form-data" attribute.

Request:

POST: /api/files

Input parameter:

fileThe file's name.

Response:

{ code: 0, message: "OK", file_id: "55599405d565a6f4d5e86ac3" }

Where code and message are described in API Response, while file_id is an ID that will be used in the following phase.


2. Running conversion task

Request:

POST: /api/tasks

Input parameters:

typeConversion service type, see conversion tasks names for a full list of possible values.
file_idFor services which require a file to be uploaded, this is the file_id returned in the previous phase.
urlFor services which require URL, this is a place to put it.
options[]Each conversion has its own set of options, which can be found below (click on the type name to expand details).
 Possible values
options[orientation]Landscape
Portrait
options[pagesize]A4
B5
Letter
options[colormode]colored
grayscale
options[background]yes
no
options[images]yes
no
options[javascript]yes
no
 Possible values
options[delimiter]comma
semicolon
vertical_bar
tabulation
 Possible values
options[format]jpg
png
options[images]yes
no
options[javascript]yes
no
 Possible values
options[orientation]Landscape
Portrait
This conversion has no options.
 Possible values
options[delimiter]comma
semicolon
vertical_bar
tabulation
This conversion has no options.
 Possible values
options[orientation]Landscape
Portrait
 Possible values
options[delimiter]comma
semicolon
vertical_bar
tabulation
 Possible values
options[delimiter]comma
semicolon
vertical_bar
tabulation
options[header]yes
no
This conversion has no options.

Response:

{ code: 0, message: "OK", task_id: "55599405d5bbc6f4d5e86ac4" }

Where code and message are described in API Response, while task_id is a UUID that will be used in the following phase.


3. Checking task status

You should perform this check in a loop, while waiting between tries for some time (e.g. 10 seconds).

Request:

GET /api/tasks/<task_id>

Input parameter:

task_idThis is the task_id returned in the previous phase.

Response:

{
    code: 0,
    message: "OK",
    status: "<status>",
    file_id: "55599405d565a6f4d5e86ac3",
}

code and message are described in API Response. status is one of the following:

  • PENDING - task is queued and waiting to run
  • RUNNING - task is running
  • SUCCESS - finished successfully
  • ERROR - finished with error

If you get SUCCESS or ERROR you should break out of the checking loop. On SUCCESS you will find the result's file ID in file_id (it will be used in the next phase).

4. Downloading result file

Request:

GET /api/files/<file_id>

Input parameter:

file_idThis is the file_id returned in the previous phase.

Response:

The response will contain a "Content-Disposition: attachment;" HTTP header, which should trigger the file download process (if you're using a browser).


Conversion tasks names

Conversion Service TypeConversion Service Description
convert.html2pdfHTML Page to PDF (file upload)
convert.url2pdfHTML Page to PDF (page by URL)
convert.html2csvHTML Table to CSV (file upload)
convert.url2csvHTML Table to CSV (page by URL)
convert.url2imgMake Website Snapshot
convert.xls2pdfExcel (XLS) to PDF
convert.xls2htmlExcel (XLS) to HTML
convert.xls2csvExcel (XLS) to CSV
convert.ods2csvOpenOffice Calc (ODS) to CSV
convert.csv2xlsCSV to Excel (XLS)
convert.xml2csvXML to CSV
convert.xml2xlsXML to Excel (XLS)
convert.img2pdfImage to PDF
convert.csv2xmlCSV to XML
convert.pdf2txtPDF to Text
© 2012-2016 SunlightWebLab.com - Web Services Development and Consulting
Contact Us | API Documentation | Terms of Use | Privacy Policy