Introduction
Zamzar provides a simple API for fast, scalable, high-quality file conversion for 100s of formats. Our API can be used to convert files on your machine, or files accessible over HTTP, FTP, SFTP or even Amazon S3.
These docs cover how to use the API. If you have questions not covered here, check out our FAQ. You will need to signup for an account first to begin using the API.
We offer easy-to-use SDKs for the following languages:
Java
Use our official Java SDK for convenient access to all features of the API. Requires Java 8 or later.
import com.zamzar.api.ZamzarClient;
import com.zamzar.api.invoker.ApiException;
import java.io.File;
public class GettingStarted {
public static void main(String[] args) throws ApiException {
new ZamzarClient("GiVUYsF4A8ssq93FR48H");
.convert(new File("/path/to/local/file"), "pdf") // converts to pdf
.store(new File("/path/to/folder")) // downloads the converted file
.deleteAllFiles(); // removes your files from Zamzar's servers
}
}
PHP
Use our official PHP SDK for convenient access to all features of the API. Requires PHP v7.2.5 or later.
<?php
// Connect to the Production API using an API Key
$zamzar = new \Zamzar\ZamzarClient("GiVUYsF4A8ssq93FR48H");
// Submit a conversion job
$job = $zamzar->jobs->submit([
'source_file' => 'path/to/local/file',
'target_format' => 'xxx'
]);
// Wait for the job to complete (the default timeout is 60 seconds)
$job->waitForCompletion([
'timeout' => 60
]);
// Download the converted files
$job->downloadTargetFiles([
'download_path' => 'path/to/folder/'
]);
// Delete the source and target files on Zamzar's servers
$job->deleteAllFiles();We also offer fully tested code samples for the following languages:
C#
Works on v4.6 (VS 2015) or later. Requires the Microsoft.AspNet.WebApi.Client and System.Json NuGet packages.
If using an earlier version of the .NET Framework, you may need to reconfigure the security policy to avoid TLS 1.0 connections, and/or rewrite our
HttpClient code to use an alternative library, such as RestSharp
cURL
Uses standard cURL. If you encounter SSL certificate problems, try updating your certificate bundle (e.g. on Windows or Linux).
Java
Works on v1.5 or later. Requires the Apache HttpClient library and the JSON library.
Node.js
Works on v0.10.26 or later. Requires the Request package.
PHP
Works on v5.3 or later.
Python
Works on v2.7.6 or later. Requires the Requests library.
Getting Started
This tutorial will show you how to use the Zamzar API to convert a file to a different file format. There are only three short steps involved:
NOTE: All example requests are made to https://sandbox.zamzar.com/. If you want to use the production environment change the endpoint to https://api.zamzar.com/.
In this example, we'll assume that you want to convert an image from GIF to PNG. All curl requests can be made from a shell (Linux) or a Terminal (Mac) – on Windows you can get curl here and run it from a command prompt.
Obtain an API key
Every request to the Zamzar API must include a key, so that we can identify you. Once you have signed up for an account, you can get an API key by visiting the key management page of your developer portal.
Let's see this in action and test your key by sending a simple API request. To do so, you can send a request to inspect the GIF file format. Issue a GET request to the formats/gif endpoint. Use HTTP basic authentication, specify your API key as the username, and leave the password blank.
curl https://sandbox.zamzar.com/v1/formats/gif \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://sandbox.zamzar.com/v1/formats/gif', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://sandbox.zamzar.com/v1/formats/gif";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/formats/gif"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/formats/gif"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Format {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://sandbox.zamzar.com/v1/formats/gif";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Format
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://sandbox.zamzar.com/v1/formats/gif";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
The JSON response provides some information about the GIF file format, such as the target file formats which Zamzar can convert GIFs to.
Example JSON Response
{
"name" : "gif",
"targets" : [
{
"name" : "bmp",
"credit_cost" : 1
},
{
"name" : "jpg",
"credit_cost" : 1
},
{
"name" : "webp",
"credit_cost" : 1
}
]
}Start a conversion job
To convert a file with Zamzar, you need to send a request to the jobs endpoint. For this tutorial, we recommend that you use a relatively small image file (< 1MB), as this will keep your responses nice and snappy. Once you've found a file to upload from your machine, you can issue a request to start your new job.
Note that this is a multi-part request. The first part contains binary data (your image file) while the other part contains typical POST data: a key-value pair that tells use the format to which your file should be converted.
curl https://sandbox.zamzar.com/v1/jobs \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
-F "source_file=@/tmp/portrait.gif" \
-F "target_format=png"var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
target_format: 'png',
source_file: fs.createReadStream('/tmp/portrait.gif')
};
request.post({url:'https://sandbox.zamzar.com/v1/jobs/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start conversion job', err);
} else {
console.log('SUCCESS! Conversion job started:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://sandbox.zamzar.com/v1/jobs";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFilePath = "/tmp/portrait.gif";
$targetFormat = "png";
// Since PHP 5.5+ CURLFile is the preferred method for uploading files
if(function_exists('curl_file_create')) {
$sourceFile = curl_file_create($sourceFilePath);
} else {
$sourceFile = '@' . realpath($sourceFilePath);
}
$postData = array(
"source_file" => $sourceFile,
"target_format" => $targetFormat
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false); // Enable the @ prefix for uploading files
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);require 'net/https'
require 'net/http/post/multipart'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/jobs"
source_file = "/tmp/portrait.gif"
target_format = "png"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post::Multipart.new(
uri.request_uri,
'source_file' => UploadIO.new(source_file, "image/gif"),
'target_format' => target_format
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/jobs"
source_file = "/tmp/portrait.gif"
target_format = "png"
file_content = {'source_file': open(source_file, 'rb')}
data_content = {'target_format': target_format}
res = requests.post(endpoint, data=data_content, files=file_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
// import from JDK
import java.io.*;
public class StartJob {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://sandbox.zamzar.com/v1/jobs";
String sourceFile = "/tmp/portrait.gif";
String targetFormat = "png";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("source_file", new FileBody(new File(sourceFile)))
.addPart("target_format", new StringBody(targetFormat, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartJob
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://sandbox.zamzar.com/v1/jobs";
const string sourceFile = @"/tmp/portrait.gif";
const string targetFormat = "png";
JsonValue json = Upload(apiKey, endpoint, sourceFile, targetFormat).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, string sourceFile, string targetFormat)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(targetFormat), "target_format");
request.Add(new StreamContent(File.OpenRead(sourceFile)), "source_file", new FileInfo(sourceFile).Name);
using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
The response contains the status of the new job (initialising) and confirms the parameters included in your request as well as the cost in credits.
Example JSON Response
{
"id" : 15,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"source_file" : {"id":2,"name":"portrait.gif","size":90571},
"target_files" : [],
"target_format" : "png",
"credit_cost" : 1
}Zamzar is now converting your file. Before you can access the result, you should check to see whether your job has finished successfully, by sending a GET request to the jobs/ID endpoint. In this request, you'll need to use the unique identifier returned by Zamzar when you created your job.
curl https://sandbox.zamzar.com/v1/jobs/15 \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
jobID = 15;
request.get ('https://sandbox.zamzar.com/v1/jobs/' + jobID, function (err, response, body) {
if (err) {
console.error('Unable to get job', err);
} else {
console.log('SUCCESS! Got job:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$jobID = 15;
$endpoint = "https://sandbox.zamzar.com/v1/jobs/$jobID";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$job = json_decode($body, true);
echo "Job:\n----\n";
print_r($job);require 'net/https'
require 'json'
job_id = 15
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/jobs/#{job_id}"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
job_id = 15
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/jobs/{}".format(job_id)
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Job {
public static void main(String[] args) throws Exception {
int jobId = 15;
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://sandbox.zamzar.com/v1/jobs/" + jobId;
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Job
{
static void Main(string[] args)
{
const int jobId = 15;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://sandbox.zamzar.com/v1/jobs/" + jobId;
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
The status attribute of the response will indicate whether the job was successful. If your job hasn't finished yet, wait a few seconds and re-issue the request, as it might take Zamzar a small while to convert your file. In other words, clients are required to poll this endpoint in order to determine whether a job has completed.
Once your job has completed successfully, the response will include the names and unique identifiers of the converted files (target_files).
Example JSON Response
{
"id" : 15,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:13Z",
"source_file" : {"id":2,"name":"portrait.gif","size":90571},
"target_files" : [{"id":3,"name":"portrait.png","size":15311}],
"target_format" : "png",
"credit_cost" : 1
}Download the converted file
Once the job has finished, you need to send one final request to download the converted file.
The response from the requests issued to determine the status of the job indicate that the unique identifier of the target file is 3. A GET request to the files/3/content endpoint can be used to download the file.
curl https://sandbox.zamzar.com/v1/files/3/content \
-u GiVUYsF4A8ssq93FR48H: \
-L \
-O \
-Jvar request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
fileID = 3,
localFilename = '/tmp/portrait.png';
// Note: NPM's request library is incompatible with our API when its followRedirect flag is turned
// on. Instead, this sample code performs a manual redirect if necessary.
request.get({url: 'https://sandbox.zamzar.com/v1/files/' + fileID + '/content', followRedirect: false}, function (err, response, body) {
if (err) {
console.error('Unable to download file:', err);
} else {
// We are being redirected
if (response.headers.location) {
// Issue a second request to download the file
var fileRequest = request(response.headers.location);
fileRequest.on('response', function (res) {
res.pipe(fs.createWriteStream(localFilename));
});
fileRequest.on('end', function () {
console.log('File download complete');
});
}
}
}).auth(apiKey,'',true).pipe(fs.createWriteStream(localFilename));
<?php
$fileID = 3;
$localFilename = "/tmp/portrait.png";;
$endpoint = "https://sandbox.zamzar.com/v1/files/$fileID/content";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
$fh = fopen($localFilename, "wb");
curl_setopt($ch, CURLOPT_FILE, $fh);
$body = curl_exec($ch);
curl_close($ch);
echo "File downloaded\n";require 'net/https'
require 'json'
file_id = 3
local_filename = '/tmp/portrait.png'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/files/#{file_id}/content"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
open(local_filename, "wb") do |file|
file.write(response.body)
end
puts "File downloaded"
end
import requests
from requests.auth import HTTPBasicAuth
file_id = 3
local_filename = '/tmp/portrait.png'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/files/{}/content".format(file_id)
response = requests.get(endpoint, stream=True, auth=HTTPBasicAuth(api_key, ''))
try:
with open(local_filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=1024):
if chunk:
f.write(chunk)
f.flush()
print "File downloaded"
except IOError:
print "Error"
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
// import from JDK
import java.io.*;
public class DownloadFile {
public static void main(String[] args) throws Exception {
int fileId = 3
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://sandbox.zamzar.com/v1/files/" + fileId + "/content";
String localFilename = "/tmp/portrait.png";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
// Save response content to file on local disk
BufferedInputStream bis = new BufferedInputStream(responseContent.getContent());
BufferedOutputStream bos = new BufferedOutputStream(new FileOutputStream(localFilename));
int inByte;
while((inByte = bis.read()) != -1) {
bos.write(inByte);
}
// Print success message
System.out.println("File downloaded");
// Finalise response, client and streams
response.close();
httpClient.close();
bos.close();
bis.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class DownloadFile
{
static void Main(string[] args)
{
const int fileId = 3;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://sandbox.zamzar.com/v1/files/" + fileId + "/content";
const string localFilename = @"/tmp/portrait.png";
Download(apiKey, endpoint, localFilename).Wait();
}
static async Task<JsonValue> Download(string key, string url, string file)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
using (Stream stream = await content.ReadAsStreamAsync())
using (FileStream writer = File.Create(file))
{
stream.CopyTo(writer);
}
}
}
Depending on the size of your file, this request may take a little while to complete. The response headers will indicate whether you can download the file directly, or whether you will need to follow a redirect to download it. In the latter case we recommend passing the following options to curl to save your file locally: -L (follow redirects), -O (Write output to a local file) and -J (use the server-specified Content-Disposition filename). Your file will then be saved to your current working directory like so:
Example cURL Response
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 15k 100 15k 0 0 3464k 0 --:--:-- --:--:-- --:--:-- 3892k
curl: Saved to filename 'portrait.png'If you want to see the headers indicating the content type and length, as well as the suggested filename (via the Content-Disposition header) use:
curl https://sandbox.zamzar.com/v1/files/3/content \
-u GiVUYsF4A8ssq93FR48H: \
-L \
-iThis will give you the following output:
Example cURL Response With Headers
HTTP/1.1 200 OK
Content-Disposition: attachment; filename="portrait.png"
Content-Transfer-Encoding: binary
Content-Type: image/png
Content-Length: 15311
[Binary content of portrait.png]You can write the response body to a filename of your choosing like so:
curl https://sandbox.zamzar.com/v1/files/3/content \
-u GiVUYsF4A8ssq93FR48H: \
-L \
> converted.pngNext steps
We've covered the essentials of the Zamzar API in this tutorial. Most workflows, however, require a couple of extra steps. For example, you might want to:
- Delete the original and converted files from our servers once you've finished converting a file.
- Convert files from an external URL, an (S)FTP server, or from an Amazon S3 bucket.
- Upload a file and then start several conversion jobs.
- Cancel a job if you realise that you've selected the wrong target format.
You might also like to explore our complete code samples: we provide all of the code that you'll need to get started with our most popular types of file conversion.
Once you've tested your client code, you should start using the production environment (api.zamzar.com) rather than the test environment (sandbox.zamzar.com) used in this tutorial. The production environment uses credits from your monthly subscription to allow you to convert larger files and store your files on our servers for longer periods of time.
Reference
Our API is RESTful and speaks JSON.
Authentication
All requests are made over HTTPS using HTTP Basic authentication. Use your API key as the username. No password is required.
curl https://api.zamzar.com/v1/formats/ -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Securing API keys
We use your API keys to identify you and to bill usage of the Zamzar API to your account. As such, it's crucial to maintain the secrecy of your API keys, as you would a password or payment details for any other account.
If you discover that you have accidentally shared one or more of your API keys, you should immediately deactivate the affected keys via the Zamzar developer portal.
If you are developing a mobile or desktop application that requires access to the Zamzar API, under no circumstances should you include your Zamzar API keys in your application's binary, as this is a security risk. (A malicious user can reverse engineer your key from your application's binary or by monitoring the network access between your application and our servers). Instead we recommend having your application route requests to our API via a proxy server. Your proxy server should authenticate your users, sign the requests to our API with one of your API keys, and forward the request to the Zamzar API. In addition to keeping your API keys private, using a proxy server also allows you to change your API keys without needing to distribute a new version of your application to your users.
Do not store your Zamzar API keys in publicly accessible source code repositories.
Connected Services
The Zamzar API can import source files for conversion from external services and also export converted files back
out again. Just use the "Connected Services"
page on your developer dashboard to configure the appropriate access for the Zamzar API.
Note: Currently we support access to Amazon's Simple Storage Service (S3) only.
Amazon S3
If you want to import a file for conversion from Amazon S3 or export converted files back out again, first determine whether you need to setup any credentials to access the file. Amazon provides a useful guide to setting up access permissions for your S3 files, and we provide sample policies below.
If the source file is in a public S3 bucket or the target
export location is public you can just provide the URL without any credentials when issuing your request
to the /jobs or /imports endpoints.
If the source file is in a private S3 bucket or the target export location is private first configure credentials
to allow the Zamzar API to access the file - S3 credentials can be configured for your Zamzar API account
through the "Connected Services" page on
your developer dashboard. You will then need to reference these credentials in the URL you provide when issuing
your request to the /jobs or /imports endpoints. You must use the
name you setup for the credential when configuring it in the "Connected
Services" page, otherwise the request to access the file from Amazon S3 will fail.
Your S3 URL should therefore match one of the following two formats:
- Public file -
s3://my-bucket-name/logo.png - Private file -
s3://CREDENTIAL_NAME@my-bucket-name/logo.png
Sample Amazon S3 Policies
There are two ways in which you can allow the Zamzar API to access your S3 buckets:
- A bucket policy: configurable via S3 and provides per-bucket access
- An IAM user policy: configurable via IAM and provides access to any number of buckets
We provide examples of each type of policy below. YOU MUST EDIT THE POLICY TO USE THE NAME OF YOUR S3
BUCKET (in place of my-bucket-name).
Sample S3 Bucket Policy
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"CanonicalUser": "dbbbf457822a43d09b353de44988d1c4dd05c43ec989baf28f3b8ca764e3af44"
},
"Action": [
"s3:GetObject",
"s3:GetObjectAcl",
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::my-bucket-name/*"
},
{
"Effect": "Allow",
"Principal": {
"CanonicalUser": "dbbbf457822a43d09b353de44988d1c4dd05c43ec989baf28f3b8ca764e3af44"
},
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::my-bucket-name"
}
]
}Sample IAM User Policy
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectAcl",
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::my-bucket-name/*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::my-bucket-name"
}
]
}Custom Headers
We provide, in response to every request, two custom HTTP headers:
- Zamzar-Test-Credits-Remaining (integer) – the number of credits remaining in this billing period for testing file conversion requests with sandbox.zamzar.com
- Zamzar-Credits-Remaining (integer) – the number of file conversion credits remaining in this billing period
curl https://api.zamzar.com/v1/... \
-u GiVUYsF4A8ssq93FR48H: \
-i Example Custom Header Response
HTTP/1.1 200 OK
...
Zamzar-Test-Credits-Remaining: 3
Zamzar-Credits-Remaining: 18
...Errors
When a response contains a 4xx or 5xx response code, the body of the request will contain one or more error objects. An error object comprises:
- message (string) – a description of the error
- code (integer) – a unique identifier for the type of error
- context (object) – (included only for some error codes) further information about the cause of the error
Note that while we might change the message we return for particular type of error, we will not change the error code.
Example JSON Response
{
"errors": [
{
"message": "no value was specified for a mandatory parameter",
"code": 10,
"context": {
"parameter": "name"
}
},
{
"message": "an invalid value was specified for a parameter",
"code": 11,
"context": {
"parameter": "target_format",
"reason": "applescript is not a supported format"
}
}
]
}Error codes
The following error codes are currently used by the Zamzar API.
Problems with the content of the request:
10 – A value was not specified for a mandatory parameter.
{
"message" : "no value was specified for a mandatory parameter",
"code" : 10,
"context" : { "parameter" : "name" }
}
11 – An invalid value was specified for a parameter.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "",
"reason" : ""
}
}
Problems with the nature of the request:
20 – The request did not contain an API key or contained an invalid API key.
{
"message" : "API key was missing or invalid",
"code" : 20
}21 – The request was for a resource that does not exist.
{
"message" : "resource does not exist",
"code" : 21
}22 – The request was for a version of the API that does not exist.
{
"message" : "unrecognised API version",
"code" : 22,
"context" : {
"requested_version" : "v42",
"supported_versions" : ["v1", "v2"]
}
}23 – The request to submit a new job was rejected because this account has no credit.
{
"message" : "no conversion credits remain for this account",
"code" : 23
}24 – The request to submit a new job to the sandbox environment was rejected because this account has no test credits remaining.
{
"message" : "no test/sandbox conversion credits remain for this account",
"code" : 24
}25 – The request to upload a file was rejected because the file size exceeds the maximum file size permitted for the plan to which this account is subscribed.
{
"message" : "the size of file exceeds the maximum file size cap for the current plan",
"code" : 25,
"context" : {
"file_size" : "41943040",
"maximum_file_size" : "10485760"
}
}26 – The request was for a resource that has expired and is no longer available on our servers.
{
"message" : "resource has expired",
"code" : 26
}27 – The request was for a resource that has been deleted and is no longer available on our servers.
{
"message" : "resource been deleted",
"code" : 27
}28 – The request to submit a new job was rejected because the target_format is not a supported conversion type for the input file.
{
"message" : "the target_format is not a supported 'to' format for this source file",
"code" : 28,
"context" : {
"source_format" : "zip",
"target_format" : "pdf"
}
}Problems with the service:
30 – The API is temporarily unavailable.
{
"message" : "service temporarily unavailable",
"code" : 30,
"context" : {
"reason" : "Down for scheduled maintenance until 03:00 UTC."
}
}31 – An unexpected internal error has occurred.
{
"message" : "an unexpected error has occurred",
"code" : 31,
"context" : {
"identifier" : "ERR_54f03c6fad97d4"
}
}
32 – API rate limit exceeded.
{
"message" : "API rate limit exceeded",
"code" : 32,
"context" : {
"retry_after" : 10
}
}
Paged Collections
When you request a list of all of the resources of any type (formats, files, jobs), you will receive a paged collection as a response. A paged collection allows you to view a subset of the entire collection (limited to 50 elements) and makes it easy to implement pagination in your application.
A paged collection comprises:
- data (array) – a subset of the collection over which you are paging
- paging (object) – metadata relating to pagination
A paging object comprises:
- total_count (integer) – the number of elements in the entire collection
- first (integer or string) – the identifier of the first element in this page of the collection
- last (integer or string) – the identifier of the last element in this page of the collection
- limit (integer) – the maximum number of elements that this page could contain
Note that the first and last elements are of type integer when the paged
collection contains files and jobs, and of type string when the paged collection contains formats.
curl https://api.zamzar.com/v1/formats/ -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"name" : "3g2",
...
},
...
{
"name" : "msg",
...
}
],
"paging" : {
"total_count" : 111,
"first" : "3g2",
"last" : "msg",
"limit" : 50
}
}Requesting the next page
If the total_count of a paged collection is larger than the number of elements in the data array,
you can request the next page by appending after=X to the endpoint of your request, where X is the
value of the last property in the paging object. For example, in our above request, gvi was the
last element of the paged collection and we now want to obtain the next page:
curl https://api.zamzar.com/v1/formats/?after=gvi -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/?after=gvi', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/?after=gvi";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?after=gvi"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?after=gvi"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats?after=gvi";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats?after=gvi";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"name" : "jpg",
...
},
...
{
"name" : "ts",
...
}
],
"paging" : {
"total_count" : 111,
"first" : "jpg",
"last" : "ts",
"limit" : 50
}
}Paged collections do not wraparound. If you make a request where after is the last element of the
collection, you'll receive an empty response:
curl https://api.zamzar.com/v1/formats/?after=zip -u GiVUYsF4A8ssq93FR48H:
var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/?after=zip', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$endpoint = "https://api.zamzar.com/v1/formats/?after=zip";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);
require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?after=zip"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?after=zip"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats?after=zip";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats?after=zip";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [],
"paging" : {
"total_count" : 111,
"limit" : 50
}
}Requesting the previous page
You can request the previous page by appending before=X to the endpoint of your request, where X is
the value of the first property in the paging object. For example, in our above request, m4v was
the first element of the paged collection and we now want to obtain the previous page:
curl https://api.zamzar.com/v1/formats/?before=m4v -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/?before=m4v', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/?before=m4v";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?before=m4v"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?before=m4v"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats?before=m4v";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats?before=m4v";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"name" : "3g2",
...
},
...
{
"name" : "m4r",
...
}
],
"paging" : {
"total_count" : 111,
"first" : "3g2",
"last" : "m4r",
"limit" : 50
}
}Paged collections do not wraparound. If you make a request where before is the first element of the
collection, you'll receive an empty response:
curl https://api.zamzar.com/v1/formats/?before=3g2 -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/?before=3g2', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/?before=3g2";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?before=3g2"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?before=3g2"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats?before=3g2";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats?before=3g2";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [],
"paging" : {
"total_count" : 111,
"limit" : 50
}
}Changing the page size
By default, paged collections are limited to 50 elements. You can request pages with fewer elements by appending
limit=X to the endpoint of your request, where X is an integer that represents your desired page
size. The limit parameter must be an integer between 1 and 50 inclusive.
curl https://api.zamzar.com/v1/formats/?limit=10 -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/?limit=10', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/?limit=10";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?limit=10"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats?limit=10"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats?limit=10";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats?limit=10";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"name" : "3g2",
...
},
...
{
"name" : "avi",
...
}
],
"paging" : {
"total_count" : 111,
"first" : "3g2",
"last" : "avi",
"limit" : 10
}
}Combining parameters
The before, after and limit parameters can be combined. Note that paged
collections can never contain more than 50 data elements, and parameter combinations that attempt to make
requests for more than 50 data elements (e.g. using before and after to specify a
large range) will not cause the API to return a data collection with more than 50 elements.
Response Codes
Every response contains an appropriate HTTP status code.
Successful requests:
200 OK
201 CREATED - a new resource was created
204 NO CONTENT - the body of the response is empty
307 TEMPORARY REDIRECT - access the resource by following the location header of the response
Errors:
401 FORBIDDEN - the request is not using authentication
402 PAYMENT REQUIRED - the request cannot be completed because this account does not have sufficient credit
404 NOT FOUND - the requested resource does not exist
410 GONE - the requested resource is no longer available
413 PAYLOAD TOO LARGE - the request is too large, typically because a source file exceeds the maximum file size for this account
422 UNPROCESSABLE - the request was malformed (e.g. missing a required parameter)
429 TOO MAY REQUESTS - the request has exceeded a rate limit
500 INTERNAL SERVER ERROR - an unexpected internal error has occurred
503 UNAVAILABLE - the API is temporarily unavailableSDKs for the API
Zamzar has the following official APIs which provide straightforward access to all API features:
| Language | SDK | Notes |
|---|---|---|
| Java | zamzar-java | Java 8 or later |
| PHP | zamzar-php | PHP 7.2 or later |
We will also be providing Software Development Kits (SDKs) in popular client programming languages for the Zamzar API. If you would like to see a particular language supported let us know.
Rate Limits
In order to provide a stable and reliable service for all users we apply rate limits to different API endpoints. Details of these limits are as follows:
| Endpoint | Method | Rate Limit |
|---|---|---|
https://api.zamzar.com/jobs |
POST | 5 per second |
https://api.zamzar.com/* |
GET | 10 per second |
https://sandbox.zamzar.com/jobs |
POST | 1 per second |
https://sandbox.zamzar.com/* |
GET | 3 per second |
For any requests that exceed our rate limits, the Zamzar API will send an HTTP 429 response that
contains a rate limit warning and advice on when the request can be successfully retried. If you receive this
message you should throttle your client to call the API at a rate below the limit which you have breached. The
retry-after field indicates the number of seconds that you should wait before retrying the request.
Example JSON Response
{
"message" : "API rate limit exceeded",
"code" : 32,
"context" : {
"retry_after" : 10
}
}
Test and Production Environments
To help users test their applications, we provide a test environment (sandbox.zamzar.com).
curl https://sandbox.zamzar.com/v1/formats/ -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://sandbox.zamzar.com/v1/formats/', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://sandbox.zamzar.com/v1/formats/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/formats"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://sandbox.zamzar.com/v1/formats"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://sandbox.zamzar.com/v1/formats";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://sandbox.zamzar.com/v1/formats";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
The API to our test environment is identical to our production environment (api.zamzar.com), with
the following exceptions.
Test Credits
The test environment does not use up the conversion credits purchased with your monthly subscription. Instead, every Zamzar API account includes 100 free credits that can be used with the test environment. Your free credits are reset every month on the anniversary of the date you signed up for your account.
Test Rate Limits
The test environment applies stricter rate limits than the production environment. For further details please see the section on Rate Limits.
Other Differences
The test environment has a lower filesize limit (of 1 MB) than the production environment.
Unicode Support
Responses and requests can contain Unicode characters, encoded with UTF-8.
For example, you can include Unicode characters in requests that create files. If one of your files has a name that contains Unicode characters, responses that reference that file will contain Unicode characters.
Versioning
All requests should include, in the URL, the version of the API that they wish to access. Currently, the
following versions are supported: v1
curl https://api.zamzar.com/v1/formats/ -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Reference – Endpoints
Account
Every API key is associated with an account. The account endpoint allows you to check your current subscription plan and the number of conversions that you have remaining in this billing period.
An account object comprises:
- test_credits_remaining (integer) – the number of test conversion credits remaining in this billing period (free)
- credits_remaining (integer) – the number of conversion credits remaining in this billing period (included as part of your plan)
- plan (plan) – the plan to which you are currently subscribed
A plan object comprises:
- name (string) – the name that we use to describe this plan
- price_per_month (decimal) – the monthly subscription costs for this plan
- conversions_per_month (integer) – the number of conversion credits included in this plan per month
- maximum_file_size (integer) – the maximum size (in bytes) of files that can be uploaded with this plan; or
nullif this plan has no such cap.
Retrieve your account
Inspect your account by issuing a GET request to the account endpoint.
curl https://api.zamzar.com/v1/account \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/account', function (err, response, body) {
if (err) {
console.error('Unable to get account', err);
} else {
var account = JSON.parse(body);
console.log(account);
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/account";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$account = json_decode($body, true);
echo "Account:\n--------\n";
print_r($account);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/account"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/account"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Account {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/account";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Account
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/account";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"test_credits_remaining" : 3,
"credits_remaining" : 18,
"plan" : {
"name" : "Developer",
"price_per_month" : 0,
"conversions_per_month" : 25,
"maximum_file_size" : 1048576
}
}Formats
When using Zamzar to convert a file, you need to specify the target file format. The formats endpoint allows you to determine what formats we can convert your files to.
A format object comprises:
- name (string) – an identifying name
- targets (array of Conversions) – the conversions that Zamzar supports for files of this format
A Conversion object comprises:
- name (string) – the name of a target format
- credit_cost (integer) – the number of base credits that are charged when scheduling a job for this conversion
Retrieve a format
Inspect a format by issuing a GET request to the formats/NAME endpoint.
curl https://api.zamzar.com/v1/formats/doc \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/doc', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/doc";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats/doc"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats/doc"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Format {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats/doc";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Format
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats/doc";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"name" : "doc",
"targets" : [
{
"name" : "docx",
"credit_cost" : 1
},
{
"name" : "pdf",
"credit_cost" : 1
}
]
}Unsupported formats
If we don’t support a format, you’ll get a 404 response.
curl https://api.zamzar.com/v1/formats/weird \
-u GiVUYsF4A8ssq93FR48H: \
-i
HTTP/1.1 404 Not FoundList all formats
Obtain a list of all supported formats by issuing a GET request to the formats endpoint. The response will contain a paged collection of formats. Note that the response includes only those formats for which there is at least one target (i.e., the response excludes formats that Zamzar cannot currently convert to any other format).
curl https://api.zamzar.com/v1/formats/ -u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get('https://api.zamzar.com/v1/formats/', function (err, response, body) {
if (err) {
console.error('Unable to get formats', err);
} else {
console.log('SUCCESS! Supported Formats:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/formats/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$formats = json_decode($body, true);
echo "Formats:\n--------\n";
print_r($formats);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Formats\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/formats"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Formats"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Formats {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/formats";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Formats");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Formats
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/formats";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"name" : "3g2",
"targets" : [
{
"name" : "3gp",
"credit_cost" : 1
},
...
{
"name" : "wmv",
"credit_cost" : 1
}
]
},
...
{
"name" : "msg",
"targets" : [
{
"name" : "doc",
"credit_cost" : 2
},
...
{
"name" : "xps",
"credit_cost" : 2
}
]
}
],
"paging" : {
"total_count" : 111,
"first" : "3g2",
"last" : "msg",
"limit" : 50
}
}Files
Files represent the input to – and output from – a conversion job. The API allows creating a new file (e.g., by uploading a file to our server), retrieval of a file (e.g. that has been created by a conversion job), deleting a file and listing all of your files.
A file is really two things: information about a file (metadata) and a bunch of binary data (content). A file object exposes the metadata, and comprises:
- id (integer) – a unique identifier that we assign to your file
- key (string) – the API key that you used to create this file
- name (string) – the name that you specify for your file (must be no more than 256 chars)
- size (integer) – the size of the file in bytes, derived from the content of the file
- format (string) – the identifier of the Format of the file
- created_at (timestamp) – the time at which the file was created on our servers (UTC in ISO_8601)
The content of a file is exposed under a nested endpoint (e.g. files/1/content).
NOTE: Files expire (are periodically deleted) from our servers.
Creating a new file
To create a new file that can be used as input to a conversion job, *either* import the file from an external source or upload from your local filesystem by issuing a multipart POST request to the files endpoint.
If uploading your file from your local filesystem one part of the request should specify the name of the file:
- name (string) : your name for the file (with a maximum of 256 chars)
Another part of the request should contain the binary data that is contained in your file. This part of the request must also contain the following two headers:
- Content-Type – an Internet media type that indicates the format of the data in the body of the request
- Content-Length – the size, in bytes, of the data in the body of the request
curl https://api.zamzar.com/v1/files \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
-F "content=@/tmp/local_budget.xls" \
-F "name=budget.xls"var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
name: '/tmp/budget.xls',
content: fs.createReadStream('local_budget.xls')
};
request.post({url:'https://api.zamzar.com/v1/files', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to upload file', err);
} else {
console.log('SUCCESS! File uploaded:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/files";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFilePath = "/tmp/budget.xls";
// Since PHP 5.5+ CURLFile is the preferred method for uploading files
if(function_exists('curl_file_create')) {
$sourceFile = curl_file_create($sourceFilePath);
} else {
$sourceFile = '@' . realpath($sourceFilePath);
}
$postData = array(
"name" => $sourceFile,
"content" => $sourceFile
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false); // Enable the @ prefix for uploading files
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);require 'net/https'
require 'net/http/post/multipart'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files"
source_file = "/tmp/portrait.gif"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post::Multipart.new(
uri.request_uri,
'content' => UploadIO.new(source_file, "image/gif")
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files"
source_file = "/tmp/portrait.gif"
file_content = {'content': open(source_file, 'rb')}
res = requests.post(endpoint, files=file_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
// import from JDK
import java.io.*;
public class CreateFile {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/files";
String sourceFile = "/tmp/portrait.gif";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("content", new FileBody(new File(sourceFile)))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class CreateFile
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/files";
const string sourceFile = @"/tmp/portrait.gif";
JsonValue json = Upload(apiKey, endpoint, sourceFile).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, string sourceFile)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StreamContent(File.OpenRead(sourceFile)), "source_file", new FileInfo(sourceFile).Name);
using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 3,
"key" : "GiVUYsF4A8ssq93FR48H",
"name" : "budget.xls",
"size" : 16519,
"format" : "xls",
"created_at" : "2013-10-27T13:41:00Z"
}Error responses when creating a new file
The name and content parameters are mandatory. The response will contain an error if the request does not specify a name, does not specify the content of the file, or if there is an error uploading the file.
{
"message" : "no value was specified for a mandatory parameter",
"code" : 10,
"context" : { "parameter" : "name" }
}
The file must be in a format supported by the API. If the file is in a format that we don’t support, the response will contain an error.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "target_format",
"reason" : "applescript is not a supported format"
}
}
The file must not exceed the maximum file size for your plan. We cannot currently check if a file exceeds the maximum until the request is completed (i.e., the file upload completes), so to prevent wasted bandwidth, please check that the file is within your plan limits before issuing a request to create file.
{
"message" : "the size of file exceeds the maximum file size cap for the current plan",
"code" : 25,
"context" : {
"file_size" : "41943040",
"maximum_file_size" : "10485760"
}
}Monitoring upload progress
When bandwidth is limited or files are large, you may wish to monitor the progress of the upload. This is best achieved using the features built-in to your HTTP library, such as: progress events for XMLHttpRequest (Javascript); Net:HTTPGenericRequest#body_stream (Ruby); and —progress-bar (Curl).
curl https://api.zamzar.com/v1/files \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
-F "content=@huge_budget.xls" \
-F "name=budget.xls" \
--progress-barRetrieving metadata for a file
After uploading a file to our servers, you might like to check that the file has the correct size and other metadata. To obtain the metadata for a file, issue a GET request to the files/ID endpoint:
curl https://api.zamzar.com/v1/files/3 \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
jobID = 3;
request.get ('https://api.zamzar.com/v1/files/' + jobID, function (err, response, body) {
if (err) {
console.error('Unable to get file metadata', err);
} else {
console.log('SUCCESS! Got file metadata:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$fileID = 3;
$endpoint = "https://api.zamzar.com/v1/files/$fileID";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$file = json_decode($body, true);
echo "File:\n-----\n";
print_r($file);require 'net/https'
require 'json'
file_id = 3
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files/#{file_id}"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
file_id = 3
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files/{}".format(file_id)
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class File {
public static void main(String[] args) throws Exception {
int fileId = 3;
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/files/" + fileId;
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class File
{
static void Main(string[] args)
{
const int fileId = 3;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/files/" + fileId;
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"id" : 3,
"key" : "GiVUYsF4A8ssq93FR48H",
"name" : "budget.xls",
"size" : 16519,
"format" : "xls",
"created_at" : "2013-10-27T13:41:00Z"
}Retrieving the content of a file
After converting a file using a job, you will probably want to download the content of the converted file (or all generated files if the conversion contains multiple output files). To obtain the content of a file, issue a GET request to the files/ID/content endpoint:
curl https://api.zamzar.com/v1/files/3/content \
-u GiVUYsF4A8ssq93FR48H: \
-L \
-O \
-Jvar request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
fileID = 3,
localFilename = '/tmp/portrait.png';
// Note: NPM's request library is incompatible with our API when its followRedirect flag is turned
// on. Instead, this sample code performs a manual redirect if necessary.
request.get({url: 'https://api.zamzar.com/v1/files/' + fileID + '/content', followRedirect: false}, function (err, response, body) {
if (err) {
console.error('Unable to download file:', err);
} else {
// We are being redirected
if (response.headers.location) {
// Issue a second request to download the file
var fileRequest = request(response.headers.location);
fileRequest.on('response', function (res) {
res.pipe(fs.createWriteStream(localFilename));
});
fileRequest.on('end', function () {
console.log('File download complete');
});
}
}
}).auth(apiKey,'',true).pipe(fs.createWriteStream(localFilename));
<?php
$fileID = 3;
$localFilename = "/tmp/portrait.png";;
$endpoint = "https://api.zamzar.com/v1/files/$fileID/content";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
$fh = fopen($localFilename, "wb");
curl_setopt($ch, CURLOPT_FILE, $fh);
$body = curl_exec($ch);
curl_close($ch);
echo "File downloaded\n";require 'net/https'
require 'json'
file_id = 3
local_filename = '/tmp/portrait.png'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files/#{file_id}/content"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
open(local_filename, "wb") do |file|
file.write(response.body)
end
puts "File downloaded"
end
import requests
from requests.auth import HTTPBasicAuth
file_id = 3
local_filename = '/tmp/portrait.png'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files/{}/content".format(file_id)
response = requests.get(endpoint, stream=True, auth=HTTPBasicAuth(api_key, ''))
try:
with open(local_filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=1024):
if chunk:
f.write(chunk)
f.flush()
print "File downloaded"
except IOError:
print "Error"
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
// import from JDK
import java.io.*;
public class DownloadFile {
public static void main(String[] args) throws Exception {
int fileId = 3
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/files/" + fileId + "/content";
String localFilename = "/tmp/portrait.png";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
// Save response content to file on local disk
BufferedInputStream bis = new BufferedInputStream(responseContent.getContent());
BufferedOutputStream bos = new BufferedOutputStream(new FileOutputStream(localFilename));
int inByte;
while((inByte = bis.read()) != -1) {
bos.write(inByte);
}
// Print success message
System.out.println("File downloaded");
// Finalise response, client and streams
response.close();
httpClient.close();
bos.close();
bis.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class DownloadFile
{
static void Main(string[] args)
{
const int fileId = 3;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/files/" + fileId + "/content";
const string localFilename = @"/tmp/portrait.png";
Download(apiKey, endpoint, localFilename).Wait();
}
static async Task<JsonValue> Download(string key, string url, string file)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
using (Stream stream = await content.ReadAsStreamAsync())
using (FileStream writer = File.Create(file))
{
stream.CopyTo(writer);
}
}
}
If the request is successful the HTTP header of the response will either be HTTP/1.1 200 OK or HTTP/1.1 307 Temporary Redirect:
Example HTTP 200 response
If you receive an HTTP 200 header response, the body of the response will contain the content of the file, in which case you can download the file data directly:
HTTP/1.1 200 OK
Content-Length: 15311
Content-Disposition: attachment; filename="portrait.png"
Zamzar-Test-Credits-Remaining: 97
Zamzar-Credits-Remaining: 343
Content-Type: image/png; charset=binary
[Binary content of portrait.png]Example HTTP 307 response
If you receive an HTTP 307 header response, you should instruct your client code to follow the redirect link specified in the Location header of the response in order to download the file:
HTTP/1.1 307 Temporary Redirect
Content-Length: 0
Location: https://someotherlocation.com/file
Zamzar-Test-Credits-Remaining: 97
Zamzar-Credits-Remaining: 343
Content-Type: application/json; charset=utf-8When using cURL
Save the content of a file to disk using curl options -L (follow redirects), -O (Write output to a local file) and -J (use the server-specified Content-Disposition filename). Or specify your own filename by redirecting the output of your HTTP call:
curl https://api.zamzar.com/v1/files/3/content \
-u GiVUYsF4A8ssq93FR48H: \
-L \
> converted.pngTroubleshooting
If you receive an HTTP 400 (Bad Request) response from the files/ID/content endpoint, this might indicate that your code is re-sending HTTP authorisation headers when following a redirect. To fix this issue, ensure that your code does not reuse HTTP headers for redirects, or use the sample code included in this documentation (which automatically prevents this).
Deleting a file
If you want to remove our copy of one of your files, issue a DELETE request to the files/ID endpoint. The response will contain the metadata for deleted file, but not its content.
curl https://api.zamzar.com/v1/files/3 \
-u GiVUYsF4A8ssq93FR48H: \
-X DELETEvar request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
fileID = 3;
request.del('https://api.zamzar.com/v1/files/' + fileID, function (err, response, body) {
if (err) {
console.error('Unable to delete file', err);
} else {
console.log('SUCCESS! File deleted', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$fileID = 3;
$endpoint = "https://api.zamzar.com/v1/files/$fileID";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n--------\n";
print_r($response);require 'net/https'
require 'json'
file_id = 3
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files/#{file_id}"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Delete.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
file_id = 3
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files/{}".format(file_id)
res = requests.delete(endpoint, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class DeleteFile {
public static void main(String[] args) throws Exception {
int fileId = 3
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/files/" + fileId;
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpDelete request = new HttpDelete(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class DeleteFile
{
static void Main(string[] args)
{
const int fileId = 3;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/files/" + fileId;
JsonValue json = Delete(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Delete(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.DeleteAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"id" : 3,
"key" : "GiVUYsF4A8ssq93FR48H",
"name" : "budget.xls",
"size" : 16519,
"format" : "xls",
"created_at" : "2013-10-27T13:41:00Z"
}Listing all files
To obtain the metadata for all of your files, issue a GET request to the files endpoint. The response will contain a paged collection of files. Note that files are ordered by creation date — newer files appear before older files — and that expired files are not included.
curl https://api.zamzar.com/v1/files/ \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H'
request.get ('https://api.zamzar.com/v1/files/', function (err, response, body) {
if (err) {
console.error('Unable to get files', err);
} else {
console.log('SUCCESS! Got files:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/files/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$files = json_decode($body, true);
echo "Files:\n--------\n";
print_r($files);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Files\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/files"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Files"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Files {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/files";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Files");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Files
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/files";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"id" : 5,
"key" : "GiVUYsF4A8ssq93FR48H",
"name" : "budget.xls.numbers",
"size" : 18533,
"format" : "numbers",
"created_at" : "2013-10-27T13:41:00Z"
},
{
"id" : 3,
"key" : "GiVUYsF4A8ssq93FR48H",
"name" : "budget.xls",
"size" : 16519,
"format" : "xls",
"created_at" : "2013-10-27T13:41:00Z"
}
],
"paging" : {
"total_count" : 2,
"first" : 5,
"last" : 3,
"limit" : 50
}
}
Imports
Imports represent the process of copying a file to our servers from an external URL, (S)FTP server, or an Amazon S3 bucket. The API allows creating a new import, retrieving the status of an import and listing all of your imports.
An import object comprises:
- id (integer) – a unique identifier that we assign to your import
- key (string) – the API key that you used to create this import
- url (url) – the URL to the original file
- status (string) – the current status of the job (one of
initialising,downloading,successful, orfailed - failure (object) – an explanation for why an import has failed, comprising a code (integer) and a message (string). A failure object is included only if the status of the import is
failed. - file (File) – details of the imported file
- created_at (timestamp) – the time at which the import was created on our servers (UTC in ISO_8601)
- finished_at (timestamp) – the time at which the import finished if successful, or null otherwise (UTC in ISO_8601)
Starting an import
To start the process of importing a new file, issue a POST request to the imports endpoint, specifying the URL of the file to be imported and (optionally) a name for the imported file. Note that if an import fails due to network issues, we automatically retry (up to a maximum of five times) with an exponential back off: we'll initially retry after 10 seconds, and permanently fail the import after 3 hours.
- url (url) : the location of the file to be imported
- filename (string, optional) : a name for the file to be imported (which is used to override any filename included in the
url)
curl https://api.zamzar.com/v1/imports \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
--data-urlencode "url=https://www.example.com/logo.png" \
-d "filename=logo.png"
var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
url: 'https://www.example.com/logo.png',
filename: 'logo.png'
};
request.post({url:'https://api.zamzar.com/v1/imports/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start import', err);
} else {
console.log('SUCCESS! Import started:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$endpoint = "https://api.zamzar.com/v1/imports";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$url = "https://www.example.com/logo.png";
$filename = "logo.png";
$postData = array(
"url" => $url,
"filename" => $filename
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);
require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/imports"
url = "https://www.example.com/logo.png"
filename = "logo.png"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post.new(uri.request_uri)
request.set_form_data(
'url' => url,
'filename' => filename
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/imports"
url = "https://www.example.com/logo.png"
filename = "logo.png"
data_content = {'url': url, 'filename': filename}
res = requests.post(endpoint, data=data_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class StartImport {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/imports";
String url = "https://www.example.com/logo.png"
String filename = "logo.png";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("url", new StringBody(url, ContentType.TEXT_PLAIN))
.addPart("filename", new StringBody(filename, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartImport
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/imports";
const string url = "https://www.example.com/logo.png";
const string filename = "logo.png";
JsonValue json = Upload(apiKey, endpoint, url, filename).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, int importUrl, string importFilename)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(importUrl), "url");
request.Add(new StringContent(importFilename), "filename");
using (HttpResponseMessage response = await client.PostAsync(url, request))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"url" : "https://www.example.com/logo.png",
"status" : "initialising",
"created_at" : "2013-10-27T13:41:00Z",
"finished_at": null
}
We support the following types of URL for importing files:
HTTP
http://www.example.com/logo.pnghttps://www.example.com/logo.pnghttps://username:password@www.example.com/logo.png
FTP
ftp://ftp.example.com/logo.pngftp://username:password@ftp.example.com/logo.png
SFTP
sftp://username:password@sftp.example.com/logo.png
Amazon Simple Storage Service (S3)
Note:CREDENTIAL_NAME below should match exactly the credential name used on the "Connected Services" page. For more information on configuring credentials to access S3, check out the Amazon S3 section here.- Public file -
s3://my-bucket-name/logo.png - Private file -
s3://CREDENTIAL_NAME@my-bucket-name/logo.png
Error responses when starting an import
The url parameter is mandatory. The response will contain an error if the request does not specify a url.
{
"message" : "no value was specified for a mandatory parameter",
"code" : 10,
"context" : { "parameter" : "url" }
}
The url parameter must be a well-formed URL and its scheme must be one of HTTP, HTTPS, FTP, SFTP or S3.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "url",
"reason" : "dropbox is not a supported protocol"
}
}
Passwords should be not be included for insecure URL schemes, such as HTTP.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "url",
"reason" : "http URLs must not include a password (use https instead)"
}
}
For some URL schemes, such as SFTP, a username and a password must be included.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "url",
"reason" : "sftp URLs must include a username and a password"
}
}
For some URL schemes, such as S3, a credential configured through your developer dashboard can be included in the url. An error is reported if a credential is specified in the url but it is not configured in your developer dashboard.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "url",
"reason" : "The not_yet_configured credential is not configured for your account at https://developers.zamzar.com/user/services"
}
}
Retrieving an import
After starting an import, you'll need to check whether it has finished successfully before using the imported file. To obtain the metadata for an import, issue a GET request to the imports/ID endpoint:
curl https://api.zamzar.com/v1/imports/1 \
-u GiVUYsF4A8ssq93FR48H:
var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
importID = 1;
request.get ('https://api.zamzar.com/v1/imports/' + importID, function (err, response, body) {
if (err) {
console.error('Unable to get import', err);
} else {
console.log('SUCCESS! Got import:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$importID = 1;
$endpoint = "https://api.zamzar.com/v1/imports/$importID";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$import = json_decode($body, true);
echo "import:\n----\n";
print_r($import);
require 'net/https'
require 'json'
import_id = 15
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/imports/#{import_id}"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
import_id = 1
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/imports/{}".format(import_id)
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Import {
public static void main(String[] args) throws Exception {
int importId = 1;
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/imports/" + importId;
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Import
{
static void Main(string[] args)
{
const int importId = 1;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/imports/" + importId;
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"url" : "https://www.example.com/logo.png",
"status" : "successful",
"file" : {
"id": 42,
"name": "logo.png",
"size": 47577,
"format" : "png"
}
}
Investigating a failed import
If a file cannot be imported, the response from the imports/ID endpoint will contain a failure code and message:
Example JSON Response
{
"id" : 2,
"key" : "GiVUYsF4A8ssq93FR48H",
"url" : "https://www.example.com/huge.zip",
"status" : "failed",
"failure" : {
"code" : 3,
"message" : "The size of the imported file (1.2 GB) exceeds the maximum file size cap for the current plan (1 GB)."
}
}
Note that while we might change the message that we return for a particular type of failure, we will not change the code. The code of a failure can be used in API clients to determine what action to take in response to a failure (e.g., retrying the job). The current list of possible failure codes is shown below. The message of a failure provides an explanation for the failure, and could be displayed to your users.
- 1 – An internal error occurred.
- 2 – The server hosting the file to be imported did not respond.
- 3 – The server hosting the file to be imported could not be accessed with the provided username and password (or credential).
- 4 – Permission was denied whilst trying to read the file to be imported.
- 5 – The file to be imported could not be found on the server.
- 6 – The URL redirects to an invalid URL, such as to a scheme that we do not support.
- 7 – The file to be imported exceeds the file size cap for your Zamzar API plan.
Listing all imports
To obtain the metadata for all of your imports, issue a GET request to the imports endpoint. The response will contain a paged collection of imports. Note that imports are ordered by creation date — newer imports appear before older imports.
curl https://api.zamzar.com/v1/imports/ \
-u GiVUYsF4A8ssq93FR48H:
var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get ('https://api.zamzar.com/v1/imports/', function (err, response, body) {
if (err) {
console.error('Unable to get imports', err);
} else {
console.log('SUCCESS! Got imports:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$endpoint = "https://api.zamzar.com/v1/imports/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$imports = json_decode($body, true);
echo "Imports:\n-----\n";
print_r($imports);
require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/imports"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Imports\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/imports"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Imports"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Imports {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/imports";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Imports");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Imports
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/imports";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"id" : 2,
"key" : "GiVUYsF4A8ssq93FR48H",
"url" : "https://www.example.com/huge.zip",
"status" : "failed",
"failure" : {
"code" : 3,
"message" : "The size of the imported file (1.2 GB) exceeds the maximum file size cap for the current plan (1 GB)."
}
},
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"url" : "https://www.example.com/logo.png",
"status" : "successful",
"file" : {
"id": 42,
"name": "logo.png",
"size": 47577,
"format" : "png"
}
}
],
"paging" : {
"total_count" : 2,
"first" : 2,
"last" : 1,
"limit" : 50
}
}
Jobs
A job represents the process of converting a file to another format. The API can be used to start a new job, to retrieve the status of a job, to cancel a job, and to obtain a list of all of your jobs.
A job object comprises:
- id (integer) – a unique identifier that we assign to your job
- key (string) – the API key that you used to create this job
- status (string) – the current status of the job (one of
initialising,converting,successful,failedorcancelled) - failure (object) – an explanation for why a job has failed, comprising a code (integer) and a message (string). A failure object is included only if the status of the job is
failed. - sandbox (boolean) – indicates whether or not this job was processed on the developer sandbox (i.e., at no cost)
- created_at (timestamp) – the time at which the job was created (UTC in ISO_8601)
- finished_at (timestamp) – the time at which the job finished if successful, or null otherwise (UTC in ISO_8601)
- import (Import) – an object representing the process of copying the source file to our servers, included only if the source file was originally on another server
- source_file (File) – the input to the job
- target_files (array of Files) – the output from the job
- target_format (string) – the name of the format to which
source_fileis being converted - credit_cost (integer) – the cost in conversion credits of the job
- export_url (URL) – the location to which all converted files will be copied
- exports (array of Exports) – a set of objects representing the process of copying the converted files to the location specified by the
export_url
An export object comprises:
- id (integer) – a unique identifier that we assign to your export
- url (url) – the URL of the resultant file
- status (string) – the current status of the job (one of
initialising,uploading,successfulorfailed) - failure (object) – an explanation for why an export has failed, comprising a code (integer) and a message (string). A failure object is included only if the status of the export is
failed.
Starting a job
To convert a file from one format to another, start a new job. There are four ways to start a new job, depending on the location of your source file:
- Local - If the file is on your machine, you can issue a request that uploads the file and starts a new conversion.
- Remote URL - If the file is on another server, you can issue a request that includes a URL to the source file. We currently support importing source files over HTTP, HTTPS, FTP or SFTP.
- Amazon S3 - If the file is on S3, you can issue a request that includes a URL to the file and AWS credentials.
- Already Uploaded - If the file has already been uploaded to our servers (perhaps because you used it in a previous job), you can issue a request that includes our numeric identifier for the source file.
These four approaches are discussed in more detail below:
Starting a job for a local file
To start a conversion job and upload a source file in a single request, issue a multipart POST request to the jobs endpoint. One part of the request should specify the target format and (optionally) a source format:
- target_format (string) : the identifying name of the format that
source_filewill be converted to - source_format (string, optional) : the identifying name of the format of the
source_file(and is used to specify a source format that is different to the extension of thesource_file)
Another part of the request should contain the binary data that is contained in your source file. This part of the request must also contain the following two headers:
- Content-Type – an Internet media type that indicates the format of the data in the body of the request
- Content-Length – the size, in bytes, of the data in the body of the request
curl https://api.zamzar.com/v1/jobs \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
-F "source_file=@/tmp/portrait.gif" \
-F "target_format=png"var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
target_format: 'png',
source_file: fs.createReadStream('/tmp/portrait.gif')
};
request.post({url:'https://api.zamzar.com/v1/jobs/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start conversion job', err);
} else {
console.log('SUCCESS! Conversion job started:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/jobs";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFilePath = "/tmp/portrait.gif";
$targetFormat = "png";
// Since PHP 5.5+ CURLFile is the preferred method for uploading files
if(function_exists('curl_file_create')) {
$sourceFile = curl_file_create($sourceFilePath);
} else {
$sourceFile = '@' . realpath($sourceFilePath);
}
$postData = array(
"source_file" => $sourceFile,
"target_format" => $targetFormat
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false); // Enable the @ prefix for uploading files
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);require 'net/https'
require 'net/http/post/multipart'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "/tmp/portrait.gif"
target_format = "png"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post::Multipart.new(
uri.request_uri,
'source_file' => UploadIO.new(source_file, "image/gif"),
'target_format' => target_format
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "/tmp/portrait.gif"
target_format = "png"
file_content = {'source_file': open(source_file, 'rb')}
data_content = {'target_format': target_format}
res = requests.post(endpoint, data=data_content, files=file_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
// import from JDK
import java.io.*;
public class StartJob {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs";
String sourceFile = "/tmp/portrait.gif";
String targetFormat = "png";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("source_file", new FileBody(new File(sourceFile)))
.addPart("target_format", new StringBody(targetFormat, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartJob
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs";
const string sourceFile = @"/tmp/portrait.gif";
const string targetFormat = "png";
JsonValue json = Upload(apiKey, endpoint, sourceFile, targetFormat).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, string sourceFile, string targetFormat)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(targetFormat), "target_format");
request.Add(new StreamContent(File.OpenRead(sourceFile)), "source_file", new FileInfo(sourceFile).Name);
using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 15,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"source_file" : {"id":2,"name":"portrait.gif","size":90571},
"target_files" : [],
"target_format" : "png",
"credit_cost" : 1
}Starting a job for a URL
To start a conversion job for a source file that resides on another server, issue a POST request to the jobs endpoint with the following parameters:
- source_file (url) : the URL for the file to be converted
- target_format (string) : the identifying name of the format that
source_filewill be converted to - source_format (string, optional) : the identifying name of the format of the
source_file(and is used to specify a source format that is different to the extension of thesource_file)
curl https://api.zamzar.com/v1/jobs \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
--data-urlencode "source_file=https://www.example.com/logo.png" \
-d "target_format=jpg"
var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
source_file: 'https://www.example.com/logo.png',
target_format: 'jpg'
};
request.post({url:'https://api.zamzar.com/v1/jobs/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start conversion job', err);
} else {
console.log('SUCCESS! Conversion job started:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$endpoint = "https://api.zamzar.com/v1/jobs";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFile = "https://www.example.com/logo.png";
$targetFormat = "jpg";
$postData = array(
"source_file" => $sourceFile,
"target_format" => $targetFormat
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);
require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "https://www.example.com/logo.png"
target_format = "jpg"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post.new(uri.request_uri)
request.set_form_data(
'target_format' => target_format,
'source_file' => source_file
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "https://www.example.com/logo.png"
target_format = "jpg"
data_content = {'source_file': source_file, 'target_format': target_format}
res = requests.post(endpoint, data=data_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class StartJob {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs";
String sourceFile = "https://www.example.com/logo.png";
String targetFormat = "jpg";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("source_file", new StringBody(sourceFile, ContentType.TEXT_PLAIN))
.addPart("target_format", new StringBody(targetFormat, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartJob
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs";
const string sourceFile = "https://www.example.com/logo.png";
const string targetFormat = "jpg";
JsonValue json = Upload(apiKey, endpoint, url, filename).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, string sourceFile, string targetFormat)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(sourceFile), "source_file");
request.Add(new StringContent(targetFormat), "target_format");
using (HttpResponseMessage response = await client.PostAsync(url, request))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"import" : {
"id" : 1,
"url" : "https://www.example.com/logo.png",
"status" : "initialising"
},
"target_files" : [],
"target_format" : "xlsx",
"credit_cost" : 1
}
We support the following types of URL for importing files:
HTTP
http://www.example.com/logo.pnghttps://www.example.com/logo.pnghttps://username:password@www.example.com/logo.png
FTP
ftp://ftp.example.com/logo.pngftp://username:password@ftp.example.com/logo.png
SFTP
sftp://username:password@sftp.example.com/logo.png
Starting a job for an Amazon S3 file
To start a conversion job for a source file that resides on Amazon's Simple Storage Service (S3), first determine whether you need to setup any credentials to access the file. If needed you can configure access to Amazon S3 via the "Connected Services" page.
Next, determine the S3 URL to send to our API. The S3 URL will use one of the styles shown below. For private files, note that CREDENTIAL_NAME must match exactly the credential name you have used on the "Connected Services" page.
- Public file -
s3://my-bucket-name/logo.png - Private file -
s3://CREDENTIAL_NAME@my-bucket-name/logo.png
Once you have determined the S3 URL, issue a POST request to the jobs endpoint with the following parameters:
- source_file (url) : the URL for the file to be converted
- target_format (string) : the identifying name of the format that
source_filewill be converted to - source_format (string, optional) : the identifying name of the format of the
source_file(and is used to specify a source format that is different to the extension of thesource_file)
curl https://api.zamzar.com/v1/jobs \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
--data-urlencode "source_file=s3://CREDENTIAL_NAME@my-bucket-name/logo.png" \
-d "target_format=jpg"
var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
source_file: 's3://CREDENTIAL_NAME@my-bucket-name/logo.png',
target_format: 'jpg'
};
request.post({url:'https://api.zamzar.com/v1/jobs/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start conversion job', err);
} else {
console.log('SUCCESS! Conversion job started:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$endpoint = "https://api.zamzar.com/v1/jobs";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFile = "s3://CREDENTIAL_NAME@my-bucket-name/logo.png";
$targetFormat = "jpg";
$postData = array(
"source_file" => $sourceFile,
"target_format" => $targetFormat
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);
require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "s3://CREDENTIAL_NAME@my-bucket-name/logo.png"
target_format = "jpg"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post.new(uri.request_uri)
request.set_form_data(
'target_format' => target_format,
'source_file' => source_file
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "s3://CREDENTIAL_NAME@my-bucket-name/logo.png"
target_format = "jpg"
data_content = {'source_file': source_file, 'target_format': target_format}
res = requests.post(endpoint, data=data_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class StartJob {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs";
String sourceFile = "s3://CREDENTIAL_NAME@my-bucket-name/logo.png";
String targetFormat = "jpg";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("source_file", new StringBody(sourceFile, ContentType.TEXT_PLAIN))
.addPart("target_format", new StringBody(targetFormat, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartJob
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs";
const string sourceFile = "s3://CREDENTIAL_NAME@my-bucket-name/logo.png";
const string targetFormat = "jpg";
JsonValue json = Upload(apiKey, endpoint, url, filename).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, string sourceFile, string targetFormat)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(sourceFile), "source_file");
request.Add(new StringContent(targetFormat), "target_format");
using (HttpResponseMessage response = await client.PostAsync(url, request))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"import" : {
"id" : 1,
"url" : "s3://CREDENTIAL_NAME@my-bucket-name/logo.png",
"status" : "initialising"
},
"target_files" : [],
"target_format" : "xlsx",
"credit_cost" : 1
}
Starting a job for a file that has already been uploaded
To start a job for a file that you’ve already uploaded to our servers, issue a POST request to the jobs endpoint, with the following arguments:
- source_file (integer) : the unique identifier of the file that will be converted
- target_format (string) : the identifying name of the format that
source_filewill be converted to
curl https://api.zamzar.com/v1/jobs \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
-d "source_file=1" \
-d "target_format=xlsx"var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
source_file: 1,
target_format: 'xlsx'
};
request.post({url:'https://api.zamzar.com/v1/jobs/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start conversion job', err);
} else {
console.log('SUCCESS! Conversion job started:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/jobs";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFileID = 1;
$targetFormat = "xlsx";
$postData = array(
"source_file" => $sourceFileID,
"target_format" => $targetFormat
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file_id = "1"
target_format = "xlsx"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post.new(uri.request_uri)
request.set_form_data(
'target_format' => target_format,
'source_file' => source_file_id
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file_id = "1"
target_format = "xlsx"
data_content = {'source_file': source_file_id, 'target_format': target_format}
res = requests.post(endpoint, data=data_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class StartJob {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs";
int sourceFileId = 1;
String targetFormat = "xlsx";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("source_file", new StringBody(sourceFileId + "", ContentType.TEXT_PLAIN))
.addPart("target_format", new StringBody(targetFormat, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartJob
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs";
const int sourceFileId = 1;
const string targetFormat = "xlsx";
JsonValue json = Upload(apiKey, endpoint, sourceFileId, targetFormat).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, int sourceFileId, string targetFormat)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(sourceFileId.ToString()), "source_file");
request.Add(new StringContent(targetFormat), "target_format");
using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"source_file" : { "id" : 1, "name" : "budget.xls", "size" : 16519 },
"target_files" : [],
"target_format" : "xlsx",
"credit_cost" : 1
}Exporting converted files
When starting a job, you can request that all converted files are automatically transferred to an FTP server, SFTP server, or Amazon S3 bucket, once the job has successfully completed. To do so, include an export_url parameter with your request:
- export_url (url) : the directory (or S3 prefix) to which the converted files will be copied
Note that an export_url must specify a directory and not a filename. For example, ftp://ftp.example.com/uploads/ is valid, whilst ftp://ftp.example.com/uploads/converted.png is not.
We support the following types of URL for exporting files:
FTP
ftp://ftp.example.com/ftp://username:password@ftp.example.com/
SFTP
sftp://username:password@sftp.example.com/
Amazon Simple Storage Service (S3)
Note:CREDENTIAL_NAME below should match exactly the credential name used on the "Connected Services" page. For more information on configuring credentials to access S3, check out the Amazon S3 section here.- Public file -
s3://my-bucket-name/ - Private file -
s3://CREDENTIAL_NAME@my-bucket-name/
In the following example, a file residing on an FTP server is converted and then copied into a private S3 bucket (using credentials):
curl https://api.zamzar.com/v1/jobs \
-u GiVUYsF4A8ssq93FR48H: \
-X POST \
-d "source_file=ftp://ftp.example.com/logo.png" \
-d "target_format=jpg" \
--data-urlencode "export_url=s3://CREDENTIAL_NAME@my-bucket-name/"
var request = require('request'),
fs = require('fs'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
formData = {
source_file: 'ftp://ftp.example.com/logo.png',
target_format: 'jpg',
export_url: 's3://CREDENTIAL_NAME@my-bucket-name/'
};
request.post({url:'https://api.zamzar.com/v1/jobs/', formData: formData}, function (err, response, body) {
if (err) {
console.error('Unable to start conversion job', err);
} else {
console.log('SUCCESS! Conversion job started:', JSON.parse(body));
}
}).auth(apiKey, '', true);
<?php
$endpoint = "https://api.zamzar.com/v1/jobs";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$sourceFile = "ftp://ftp.example.com/logo.png";
$targetFormat = "jpg";
$export_url = "s3://CREDENTIAL_NAME@my-bucket-name/";
$postData = array(
"source_file" => $sourceFile,
"target_format" => $targetFormat,
"export_url" => $export_url
);
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n---------\n";
print_r($response);
require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "ftp://ftp.example.com/logo.png"
target_format = "jpg"
export_url = "s3://CREDENTIAL_NAME@my-bucket-name/"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Post.new(uri.request_uri)
request.set_form_data(
'target_format' => target_format,
'source_file' => source_file
'export_url' => export_url
)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
source_file = "ftp://ftp.example.com/logo.png"
target_format = "jpg"
export_url = "s3://CREDENTIAL_NAME@my-bucket-name/"
data_content = {'source_file': source_file, 'target_format': target_format, 'export_url': export_url}
res = requests.post(endpoint, data=data_content, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.entity.*;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class ExportJob {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs";
String sourceFile = "ftp://ftp.example.com/logo.png";
String targetFormat = "jpg";
String exportUrl = "s3://CREDENTIAL_NAME@my-bucket-name/";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpEntity requestContent = MultipartEntityBuilder.create()
.addPart("source_file", new StringBody(sourceFile, ContentType.TEXT_PLAIN))
.addPart("target_format", new StringBody(targetFormat, ContentType.TEXT_PLAIN))
.addPart("export_url", new StringBody(exportUrl, ContentType.TEXT_PLAIN))
.build();
HttpPost request = new HttpPost(endpoint);
request.setEntity(requestContent);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class StartJob
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs";
const string sourceFile = "ftp://ftp.example.com/logo.png";;
const string targetFormat = "xlsx";
const string exportUrl = "s3://CREDENTIAL_NAME@my-bucket-name/";
JsonValue json = Upload(apiKey, endpoint, sourceFileId, targetFormat).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Upload(string key, string url, string sourceFile, string targetFormat, string exportUrl)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "") })
using (HttpClient client = new HttpClient(handler))
{
var request = new MultipartFormDataContent();
request.Add(new StringContent(sourceFile), "source_file");
request.Add(new StringContent(targetFormat), "target_format");
request.Add(new StringContent(exportUrl), "export_url");
using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"import" : {
"id" : 1,
"url" : "https://www.example.com/logo.png",
"status" : "initialising"
},
"target_files" : [],
"target_format" : "jpg",
"credit_cost" : 1,
"export_url" : "s3://CREDENTIAL_NAME@my-bucket-name/",
"exports" : []
}
After the job has been completed, the converted file will start to be copied to the specified export_url. You can retrieve the status of the export by polling the GET /jobs/ID endpoint and interrogating the status of the exports stanza. (Possible states include initialising and successful). For example, requesting GET /jobs/1 will produce the following response for a job with a successfully completed export:
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:02Z",
"import" : {
"id" : 1,
"url" : "https://www.example.com/logo.png",
"status" : "successful"
},
"target_files" : [
{
"id" : 2,
"name": "logo.jpg",
"size": 43575
}
],
"target_format" : "jpg",
"credit_cost" : 1,
"export_url" : "s3://CREDENTIAL_NAME@my-bucket-name/",
"exports" : [
{
"id" : 1,
"url" : "s3://CREDENTIAL_NAME@my-bucket-name/logo.jpg",
"status" : "successful"
}
]
}
Error responses starting a new job
The target_format parameter must be the name of a format object. The source_file parameter must either be the binary data of the file to be converted (if using a multipart POST), a URL that is well-formed and uses a scheme that we support, or the identifier of one of your file objects. Otherwise, the response will contain an error object.
Note: Although these error messages can be used to determine whether a format or file exists, we recommend using the files/ID and formats/NAME endpoints for that.
{
"errors": [
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "target_format",
"reason" : "applescript is not a supported format"
}
}
]
}Both the source_file and target_format parameters are mandatory. The response will contain an error object if the request does not specify a value for these parameters.
{
"errors": [
{
"message" : "no value was specified for a mandatory parameter",
"code" : 10,
"context" : { "parameter" : "source_file" }
}
]
}The source_file must not exceed the maximum file size for your plan. We cannot currently check if a file exceeds the maximum until the request is completed (i.e., the file upload completes), so to prevent wasted bandwidth, please check that the file is within your plan limits before issuing a request to create file.
{
"errors" : [
{
"message" : "the size of file exceeds the maximum file size cap for the current plan",
"code" : 25,
"context" : {
"file_size" : 1073741824,
"maximum_file_size" : 52428800
}
}
]
}Any export_url must be a well-formed URL, and its scheme must be one of FTP, SFTP or S3.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "export_url",
"reason" : "dropbox is not a supported protocol"
}
}
Any export_url that uses the SFTP scheme must include a username and a password.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "export_url",
"reason" : "sftp URLs must include a username and a password"
}
}
For some URL schemes, such as S3, a credential configured through your developer dashboard can be included in the export_url. An error is reported if a credential is specified in the export_url but it is not configured in your developer dashboard.
{
"message" : "an invalid value was specified for a parameter",
"code" : 11,
"context" : {
"parameter" : "export_url",
"reason" : "The not_yet_configured credential is not configured for your account at https://developers.zamzar.com/user/services"
}
}
Retrieving a job
After creating a conversion job, you’ll need to check whether it has finished successfully before accessing the converted file. To obtain the metadata for a job, issue a GET request to the jobs/ID endpoint:
curl https://api.zamzar.com/v1/jobs/15 \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
jobID = 15;
request.get ('https://api.zamzar.com/v1/jobs/' + jobID, function (err, response, body) {
if (err) {
console.error('Unable to get job', err);
} else {
console.log('SUCCESS! Got job:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$jobID = 15;
$endpoint = "https://api.zamzar.com/v1/jobs/$jobID";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$job = json_decode($body, true);
echo "Job:\n----\n";
print_r($job);require 'net/https'
require 'json'
job_id = 15
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs/#{job_id}"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
job_id = 15
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs/{}".format(job_id)
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Job {
public static void main(String[] args) throws Exception {
int jobId = 15;
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs/" + jobId;
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Job
{
static void Main(string[] args)
{
const int jobId = 15;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs/" + jobId;
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"id" : 15,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:13Z",
"source_file" : {"id":2,"name":"portrait.gif","size":90571},
"target_files" : [{"id":3,"name":"portrait.png","size":15311}],
"target_format" : "png",
"credit_cost" : 1
}Investigating a failed job
If a conversion job fails, the response from the jobs/ID endpoint will contain a failure code and message.
Example JSON Response
{
"id" : 15,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "failed",
"failure" : {"code":2,"message":"The source file was too small to convert."},
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"source_file" : {"id":2,"name":"portrait.gif","size":0},
"target_format" : "png",
"credit_cost" : 1
}
Note that while we might change the message that we return for a particular type of failure, we will not change the code. The code of a failure can be used in API clients to determine what action to take in response to a failure (e.g., retrying the job). The current list of possible failure codes is shown below. The message of a failure provides an explanation for the failure, and could be displayed to your users.
- 1 – An internal error occurred.
- 2 – The source file was too small.
- 3 – The source file could not be imported.
When a job fails because the source file could not be imported, more information can be found by inspecting the failure of the import object, as shown below. See the imports documentation for a complete list of possible failures.
Example JSON Response
{
"id" : 16,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "failed",
"failure" : {
"code": 3,
"message": "The source file could not be imported."
},
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"import" : {
"id" : 2,
"url" : "https://www.example.com/huge.zip",
"status" : "failed",
"failure" : {
"code" : 2,
"message" : "A 'Forbidden' response was received when accessing: https://www.example.com/huge.zip"
}
},
"target_format" : "png",
"credit_cost" : 1
}
Investigating a failed export
If exporting one or more converted files fails, the response from the jobs/ID endpoint will contain a failure code and message for each failed export object. Note that if an export fails due to network issues, we automatically retry (up to a maximum of five times) with an exponential back off: we'll initially retry after 10 seconds, and permanently fail the export after 3 hours.
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:02Z",
"import" : {
"id" : 1,
"url" : "https://www.example.com/book.pdf",
"status" : "successful"
},
"target_files" : [
{
"id" : 2,
"name": "book.page1.png",
"size": 34563
},
{
"id" : 3,
"name": "book.page2.png",
"size": 43575
}
],
"target_format" : "png",
"credit_cost" : 1,
"export_url" : "s3://CREDENTIAL_NAME@my-bucket-name/",
"exports" : [
{
"id" : 1,
"url" : "s3://CREDENTIAL_NAME@my-bucket-name/book.page1.png",
"status" : "successful"
},
{
"id" : 2,
"url" : "s3://CREDENTIAL_NAME@my-bucket-name/book.page2.png",
"status" : "failed",
"failure" : {
"code" : 5,
"message" : "A file named book.page2.png' already exists on the server at 's3://CREDENTIAL_NAME@my-bucket-name/'"
}
}
]
}
Note that while we might change the message that we return for a particular type of failure, we will not change the code. The code of a failure can be used in API clients to determine what action to take in response to a failure (e.g., retrying the job). The current list of possible failure codes is shown below. The message of a failure provides an explanation for the failure, and could be displayed to your users.
- 1 – An internal error occurred.
- 2 – The server due to receive the converted files did not respond.
- 3 – The server due to receive the converted files could not be accessed with the provided username and password (or credential).
- 4 – Permission was denied whilst trying to write the converted files to the server.
- 5 – A file with the same name as a converted file already exists on the server.
Multiple output files
Some conversion jobs will produce multiple output files - for example if you convert a Powerpoint PPT presentation with multiple slides to PNG, one PNG output file will be produced for each slide. When more than 1 "target file" is produced we will bundle up all output files into a single ZIP file for your convenience. You can also download individual files should you need to.
To obtain the ID's for all files produced simply examine the target_files array in the response to the jobs/ID endpoint:
Example JSON Response
{
"id" : 15,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : true,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:13Z",
"source_file" : {"id":2,"name":"test.ppt","size":44437},
"target_files" : [{"id":3,"name":"project_overview-0.png","size":292169},
{"id":4,"name":"project_overview-1.png","size":76719},
{"id":5,"name":"project_overview-2.png","size":20350},
{"id":6,"name":"project_overview.zip","size":506557}],
"target_format" : "png",
"credit_cost" : 1
}Cancelling a job
Jobs will be cancelled by our systems if you do not have enough credits remaining in your allowance to complete a particular conversion – in this case no credits will be charged as no conversion will take place.
If you need to cancel a job before it finishes, issue a DELETE request to the jobs/ID endpoint – please note credits will still be charged for the conversion. The response will contain the cancelled job object:
curl https://api.zamzar.com/v1/jobs/1 \
-u GiVUYsF4A8ssq93FR48H: \
-X DELETEvar request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H',
jobID = 1;
request.del('https://api.zamzar.com/v1/jobs/' + jobID, function (err, response, body) {
if (err) {
console.error('Unable to cancel job', err);
} else {
console.log('SUCCESS! Job cancelled', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$jobID = 1;
$endpoint = "https://api.zamzar.com/v1/jobs/$jobID";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$response = json_decode($body, true);
echo "Response:\n--------\n";
print_r($response);require 'net/https'
require 'json'
job_id = 1
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs/#{job_id}"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Delete.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
job_id = 1
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs/{}".format(job_id)
res = requests.delete(endpoint, auth=HTTPBasicAuth(api_key, ''))
print res.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class CancelJob {
public static void main(String[] args) throws Exception {
int jobId = 1
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs/" + jobId;
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpDelete request = new HttpDelete(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class CancelJob
{
static void Main(string[] args)
{
const int jobId = 1;
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs/" + jobId;
JsonValue json = Delete(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Delete(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.DeleteAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "cancelled",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"source_file" : { "id" : 1, "name" : "budget.xls", "size" : 16519 },
"target_files" : [],
"target_format" : "xlsx",
"credit_cost" : 1
}Listing all jobs
To obtain a list of all of your jobs, issue a GET request to the jobs endpoint. The response will contain a paged collection of jobs. Note that jobs are ordered by creation date: newer jobs appear before older jobs.
curl https://api.zamzar.com/v1/jobs/ \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get ('https://api.zamzar.com/v1/jobs/', function (err, response, body) {
if (err) {
console.error('Unable to get jobs', err);
} else {
console.log('SUCCESS! Got jobs:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/jobs/";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$jobs = json_decode($body, true);
echo "Jobs:\n-----\n";
print_r($jobs);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Jobs\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Jobs"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Jobs {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Jobs");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Files
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"id" : 18,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:13Z",
"source_file" : { "id" : 3, "name" : "invitations.doc", "size" : 38301 },
"target_files" : [{ "id" : 14, "name" : "invitations.pdf", "size" : 0 }],
"target_format" : "pdf",
"credit_cost" : 1
},
{
"id" : 3,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "initialising",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"source_file" : { "id" : 2, "name" : "guest_list.xls", "size" : 7392 },
"target_files" : [],
"target_format" : "xlsx",
"credit_cost" : 1
},
{
"id" : 1,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "cancelled",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : null,
"source_file" : { "id" : 1, "name" : "budget.xls", "size" : 16519 },
"target_files" : [],
"target_format" : "xlsx",
"credit_cost" : 1
}
],
"paging" : {
"total_count" : 3,
"first" : 18,
"last" : 1,
"limit" : 50
}
}You can also obtain a list of all of the jobs that have completed successfully. The response will contain a paged collection of jobs. Note that jobs are ordered by creation date: newer jobs appear before older jobs.
curl https://api.zamzar.com/v1/jobs/successful \
-u GiVUYsF4A8ssq93FR48H:var request = require('request'),
apiKey = 'GiVUYsF4A8ssq93FR48H';
request.get ('https://api.zamzar.com/v1/jobs/successful', function (err, response, body) {
if (err) {
console.error('Unable to get successful jobs', err);
} else {
console.log('SUCCESS! Got successful jobs:', JSON.parse(body));
}
}).auth(apiKey, '', true);<?php
$endpoint = "https://api.zamzar.com/v1/jobs/successful";
$apiKey = "GiVUYsF4A8ssq93FR48H";
$ch = curl_init(); // Init curl
curl_setopt($ch, CURLOPT_URL, $endpoint); // API endpoint
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_USERPWD, $apiKey . ":"); // Set the API key as the basic auth username
$body = curl_exec($ch);
curl_close($ch);
$jobs = json_decode($body, true);
echo "Jobs:\n-----\n";
print_r($jobs);require 'net/https'
require 'json'
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs/successful"
uri = URI(endpoint)
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new(uri.request_uri)
request.basic_auth(api_key, '')
response = http.request(request)
puts "Jobs\n"
puts JSON.parse(response.body)
end
import requests
from requests.auth import HTTPBasicAuth
api_key = 'GiVUYsF4A8ssq93FR48H'
endpoint = "https://api.zamzar.com/v1/jobs/successful"
response = requests.get(endpoint, auth=HTTPBasicAuth(api_key, ''))
print "Jobs"
print response.json()
// import Apache HTTP Client v 4.3
import org.apache.http.*;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.*;
// import JSON
import org.json.*;
public class Jobs {
public static void main(String[] args) throws Exception {
String apiKey = "GiVUYsF4A8ssq93FR48H";
String endpoint = "https://api.zamzar.com/v1/jobs/successful";
// Create HTTP client and request object
CloseableHttpClient httpClient = getHttpClient(apiKey);
HttpGet request = new HttpGet(endpoint);
// Make request
CloseableHttpResponse response = httpClient.execute(request);
// Extract body from response
HttpEntity responseContent = response.getEntity();
String result = EntityUtils.toString(responseContent, "UTF-8");
// Parse result as JSON
JSONObject json = new JSONObject(result);
// Print result
System.out.println("Jobs");
System.out.println(json);
// Finalise response and client
response.close();
httpClient.close();
}
// Creates a HTTP client object that always makes requests
// that are signed with the specified API key via Basic Auth
private static CloseableHttpClient getHttpClient(String apiKey) {
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials(apiKey, ""));
CloseableHttpClient httpClient = HttpClientBuilder.create()
.setDefaultCredentialsProvider(credentialsProvider)
.build();
return httpClient;
}
}
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Json;
class Files
{
static void Main(string[] args)
{
const string apiKey = "GiVUYsF4A8ssq93FR48H";
const string endpoint = "https://api.zamzar.com/v1/jobs/successful";
JsonValue json = Query(apiKey, endpoint).Result;
Console.WriteLine(json);
}
static async Task<JsonValue> Query(string key, string url)
{
using (HttpClientHandler handler = new HttpClientHandler { Credentials = new NetworkCredential(key, "")})
using (HttpClient client = new HttpClient(handler))
using (HttpResponseMessage response = await client.GetAsync(url))
using (HttpContent content = response.Content)
{
string data = await content.ReadAsStringAsync();
return JsonObject.Parse(data);
}
}
}
Example JSON Response
{
"data" : [
{
"id" : 18,
"key" : "GiVUYsF4A8ssq93FR48H",
"status" : "successful",
"sandbox" : false,
"created_at" : "2013-10-27T13:41:00Z",
"finished_at" : "2013-10-27T13:41:13Z",
"source_file" : { "id" : 3, "name" : "invitations.doc", "size" : 38301 },
"target_files" : [{ "id" : 14, "name" : "invitations.pdf", "size" : 0 }],
"target_format" : "pdf",
"credit_cost" : 1
}
],
"paging" : {
"total_count" : 1,
"first" : 18,
"last" : 18,
"limit" : 50
}
}Troubleshooting
Below we describe some common problems and solutions that customers have encountered whilst using the Zamzar API. If we can be of further assistance, feel free to contact us.
File name comprises more than 256 characters
If you receive an HTTP 422 (Unprocessable) response from the POST /files or the POST /jobsendpoints and the context in the JSON response indicates that the name parameter comprises more than 256 characters, this indicates that your API client is attempting to convert a file whose name is too long for our API. Try renaming the file such that it has a shorter file name, and re-submitting your conversion job.
Polling for export status
If you have requested an export for a file conversion job and wish to poll for the status of that export, you should be aware there can sometimes be a short delay between the job being marked as successful and your export being started. You should ensure any code you write to interrogate the jobs/ID endpoint recognises that the exports attribute of the job object in the response is only populated when the export is started.
400 - Bad Request
If you receive an HTTP 400 (Bad Request) response from the files/ID/content endpoint, this might indicate that your code is re-sending HTTP authorisation headers when following a redirect. To fix this issue, ensure that your code does not reuse HTTP headers for redirects, or use the sample code included in this documentation (which automatically prevents this).
More specifically, if you see that your code is sending an HTTP request to s3.amazonaws.com ensure that the request does not include an Authorization: Basic ******* header.
Connecting via TLS 1.0
If your .NET client raises an exception with the message Authentication failed because the remote party has closed the transport stream when attempting to connect to the Zamzar API, this might indicate that your code is attempting to use TLS 1.0. As of 14th August 2018, we no longer accept TLS 1.0 connections.
To fix this issue, either update to .NET Framework 4.6 (or higher), or configure your .NET client to communicate over TLS 1.2 (or TLS 1.1). For example, the following C# code can be used to reconfigure the default security protocol to use TLS 1.2 with a fallback to TLS 1.1:
// Only necessary on .NET Framework 4.5 or earlier
ServicePointManager.SecurityProtocol =
SecurityProtocolType.Tls12 |
SecurityProtocolType.Tls11;