How to access the API - Calaméo Knowledge Base
Not a Calaméo member yet?
Sign up now! It's FREE!
Get the latest news on Calaméo
Follow us on Facebook
Get Calaméo updates in real-time
Follow us on Twitter

How to access the API

From Calaméo Knowledge Base

Calaméo provides a quick and easy to use RESTful API.

Making a request against the Calaméo API requires only a few easy steps:

Contents

Step 1: Select an API key

If you have not done it already, create an API key for your account (see Get your API key).

An API key provides two information that should remain confidential at all time: a public key and a secret key (click on See more to display an API secret key):

Api keys.png

Note: Do not post either the public or secret key on the support community or anywhere else in order to preserve your account's data integrity.

Step 2: Select an API method

The Calaméo API provides many methods to manage subscribers, fetch publications listings, etc. According to the method you select you will have to send your request to the correct endpoint. Almost all requests must be made to the following endpoint:

http://api.calameo.com/1.0

You can send the request parameters as part of the URL (GET) or inside the HTTP body (POST).

When dealing with document uploads, the appropriate endpoint is:

http://upload.calameo.com/1.0
Note: When uploading files you must use HTTP POST with encoding multipart/form-data.

Step 3: Make the request

To perform an action against the Calaméo API, some parameters are always required:

Name Required Type Description
apikey yes string API public key. The request will be carried out on behalf of the associated account.
signature yes string Signature of the request. See How To Sign Your Requests.
action yes string Method to execute against the API platform.
Note: All data sent to the Calaméo API must be UTF-8 encoded. And all data returned by the API will be UTF-8 encoded. Submitting data in a different encoding may result in incorrect stored values.

Sending the parameters using HTTP GET or HTTP POST request does not impact the response.

http://api.calameo.com/1.0?apikey=<apiKey>&signature=<signature>&action=<method>&...

Some optional parameters may also be included:

Name Type Description
expires timestamp An UNIX timestamp specifying an expiration date and time for the request.
output string Format of the response. Either XML (default), JSON or PHP.

http://api.calameo.com/1.0?apikey=<apiKey>&signature=<signature>&action=<method>&expires=<expires>&output=<output>&...

Step 4: Parse the response

The response from the API platform has the same structure for XML, JSON and PHP formats:

Name Type Description
requestid string Unique ID of the request.
requests integer Total number of requests made during the last hour (for rate limiting).
status string Status of the response. Either ok (success), error (failure).
content mixed Response payload
Note: The HTTP status code from the API platform is always 200 OK even if the request fails.

Here is an example of a standard response:

{
    response:{
        requestid: "kQRNFx",
        requests: 1,
        status: "ok",
        content: ...
    }
}

Step 5: Handle errors

If the API platform encounters a problem, the response status is then error and the content object is replaced with a simple error object containing the error code and a message explaining what went wrong.

See the complete Error Codes table.

Here is an example of error:

{
    response:
    {
        requestid: "kQRNFx",
        requests: 1,
        statu": "error",
        error:
        {
            code: ...,
            message: ...
        }
    }
}