Audisto API 2.0 Concepts

Output Formats

The Audisto API 2.0 supports the several output formats. They can be switched using the output parameter, like ?output=excel.

The following formats are supported

Parameter Type Description
json JSON A hierarchical, tree-like format. This is the default.
xml XML Generally follows the same hierarchical structure like the JSON (indeed it is just a transformation of JSON)
excel Excel Exports data as table, that can be open in Microsoft Excel or Open Office.
csv CSV Table with comma separated values, using double quotes for strings.
tsv TSV Table with tabulators as separators and double quotes around values.

Deep Responses

The default response to a GET request usually serves the minimum of data possible. By passing ?deep=1, the data is enriched with nested or dependent data, like clusters for pages. Use a combination of deep and partial responses to tailor the output to fit your needs.

Partial Responses

To minimize response size (and server load), we support partial responses. This allows to query just the data you want without unnecessary overhead.

We support the whole set of features introduced by Google for the Blogger API: https://developers.google.com/blogger/docs/3.0/performance# partial-response

Partial responses are defined through the fields parameter. Example:

?fields=properties/*,url,id,level,download_time

Regarding tabular data like Excel or CSV, partial responses are only partially supported, since the tree hierarchy is lost.

Condensed Responses

If you pass ?condensed=1 to a request, the API will try to minify and flatten the response wherever possible.

E.g. an enumeration value like

{
    id: 2,
    name: "Crawled",
    description: "URL was successfully crawled"
}

will be turned into the simpler

{
    id: 2
}

This can save bandwidth and storage space.

Filtering

Several data endpoints of Audisto API 2.0 support filtering. This is generally done by appending a parameter named "filter" with a filter list:

?filter={filter_list}

A filter list consists of a list of filters, separated by comma. A filter consists of a key and a value, separated by a double colon. E.g.

?filter=status:2,level:1

The value usually is a number, but can also be a string. Strings can be quoted, but must not.

?filter=language:"en"
?filter=language:en

A filter may also be set for several values at once. This is done using square brackets:

?filter=status:[2,10]

The values are treated like a logical OR combination.

Enumerations

Enumerations are objects with the following properties:

  • id: A unique ID
  • value: The value or name of the object
  • description: A description or explanation for this object

Enumerations are used quite often, e.g. to represents values like a language, generated hints, or internal values.

Lists

The Audisto API supports two kind of lists:

  • chunked list
  • simple list

Simple list

A simple list is simply an array when using the JSON format. Using XML it has a root element named <items>.

Chunked list

A chunked list when using JSON has two properties:

  • chunk: An object with properties
    • total: Total number of items
    • page: Current chunk
    • size: Current chunk size
  • items: An array of data items