Audisto API Usage

Domain

The API currently can be reached at https://api.audisto.com/{version}.

Note that the API is not reachable over normal http, but https only.

Currently there are:

Authentication

The API requires authentication. This is provided via basic http authentication. Therefore, you are required to pass your API key and password to every request. How to do this depends on the client you are using.

Authentication in the Browser

When opening an API URL in a browser, the browser will ask you for a username and password. Just copy your API key and password into the according input fields.

Since the API returns data in JSON format, it is a good idea to install a plugin to make the data more accessible, like JSONView, which is available for Firefox and Chrome.

Authentication Using wget

wget is a simple download agent available on Unix systems like Linux or MacOS X. Authentication is simple:

wget --http-user={API key} --http-password={Password} {url}

Example:

wget --http-user=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --http-password=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://api.audisto.com/1.0/status/crawls

Authentication With curl

curl is a another simple download agent available on Unix systems like Linux or MacOS X. Authentication is simple:

curl --user {Api key}:{password}  {url}

Example:

curl --user xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://api.audisto.com/1.0/status/crawls

Return Values

The API 1.0 currently returns only JSON. The API 2.0 returns JSON, XML, CSV, TSV or Excel XML.

Errors

On errors, the following format is returned:

Name Type Meaning
error String An error description, if any
code Integer HTTP error code, like 504 or 404

Example:

{
  "error":"Not Found",
  "status":404
}

Usage Limits

The API currently allows only one request a time per key. If a request is issued while another one is still executing, an error with HTTP code "429 Too Many Requests" is returned.

The number of requests per month is currently not limited.

Chunks

Parts of the API return chunked results. Chunks define pagination, a chunk retrieves a range of pages, which starts at [chunk * size of chunk + 1] and ends at [(chunk + 1) * size of chunk]. Chunks start at 0.

Different chunks can be retrieved using the parameter chunk, e.g. ?chunk=1 will retrieve the second page.

The default size of a chunk is usually 100, but the size of a chunk can be changed by passing the parameter chunksize, e.g. ?chunksize=500.

The maximum chunk size is 10,000. Any larger size will issue an error with HTTP status code "400 Bad Request".