Audisto API 2.0 Concepts
Output Formats
The Audisto API 2.0 supports 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 do not have to.
?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 IDvalue
: The value or name of the objectdescription
: 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 propertiestotal
: Total number of itemspage
: Current chunksize
: Current chunk size
items
: An array of data items