Api v1

This is the list of all parameters that you may use on the Tate API.

Overview¶

The API attempts to follow basic REST principles: for simple data-retrieval operations, the general format is {dataset} followed optionally by {objectid}. As such, /artworks will give you a list of artworks and /artworks/N01506 will give you all of Ophelia's metadata. Please keep on reading to see how more complex queries are constructed (such as related data and searches).

You can pass optional query parameters which are detailed below. Some parameters can be applied to any query (e.g. 'pretty') whilst some apply to specific queries (e.g. 'page' for lists).

The API only outputs JSON, encoded as UTF-8. There is no need currently to support other formats or encodings. As such, any HTTP headers relating to content negotiation (e.g. 'Accept') will be ignored. Also the API only supports GET and HEAD requests. Data updates are not done directly on the API (it's more efficient to send data directly to the Elastic cluster).

For the backend, the API is powered by ElasticSearch, which is used both as a data-store and search engine - I invite you to read through the guide on their official website. Unlike Art&Artists, the views will not be cached by Django. Instead the live servers will use a caching system in front of Django (Varnish). The reason is that the Collection data is refreshed weekly hence it makes sense to cache such objects for a long-time.

IMPORTANT NOTE: it is the developers and clients' responsibility to make optimised requests to the API! The Tate API provides means to select only required data (see fields and profile) and those MUST be used. This will make your application more responsive and will lower-down the bandwidth considerably.

API Reference¶

Global Parameters¶

Yep, these parameters can be used on any query!

pretty = [ 1 | 0 ]

Turn on or off pretty printing of the JSON data.

Default: off
Example: /artworks?pretty=1

fields = <field1>[,<field2>,...]

A comma-separated list of fields to include in the response. If only certain fields are required to render data, then it makes to only select them. This will use less bandwith and processing and will make the site snappier.

Default: null (returns the entire data record)
Example: /artists/816?fields=mda,id,birth.place.name

profile = <name>

Similar to fields: instead of specifying a long list of fields (e.g. to render cards), you may use a pre-defined metadata profile. Such profiles are defined in the API's main configuration settings/tateapi.py.

Default: null
Example: /artworks?profile=card

List Parameters¶

To be used with lists, filtered lists and searches

page = <integer>

The API only returns the first 20 results by default. So page selects which page of data you need. Numbering starts at 1.

Default: 1
Example: /search?q=degas&page=2

pagesize = <integer>

Override the default of 20 results per page.

Default: 20
Example: /pages?page=3&pagesize=40

sort = [-]<field1>,<field2>,...

A comma-separated list of fields to sort on. Use - to reverse the order.

Default: will vary Example: /artworks?sort=acno,title *sort by accession number, then by title*

show_facets = [ 1 | 0 ]

Returns the allowed facets (for a given type of document) with possible values and counts of matching documents. In order to return the facets only, use with pagesize=0.

Default: '0' i.e. don't return the facets
Example: /pages/search?show_facets=1

facets = <key>:<value1>[,<value2>,...]

Applies a facet a.k.a. a filter on the list. Multiple <value> are OR'ed: <key> = <value1> OR <value2> OR .... Repeat the parameter to apply multiple facets at once. "Automatic" facets don't need a value - the value is then hard-coded in settings/tateapi.py. For instance facets=featured for Albums which returns "promoted" albums (aka facets=promoted:1). It's a short-cut essentially. It is also possible to negate the value of a facet to select documents which do not match a criteria. Similar to SQL's WHERE <field> <> <value>. Use the ! character before the value to negate it e.g. facets=category:!Imagined Museum to select Albums which do not belong to the Imagined Museum category.

Default: null
Example: /pages/search?facets=event_type:film,exhibition&facets=free_for_all

group_by = <field> group_by_limit = <integer>

Returns matching document(s) for each facet value. This is equivalent to the SQL GROUP BY <field> statement. Only accepts a single value. This will return at most group_by_limit documents.

Note that the query param fields controls which fields are returned, if you wish to do so.

Default: null for group_by and 10 for group_by_limit
Example: /pages/search?show_facets=1&group_by=event_type&group_by_limit=4

Search Parameters¶

Only understood by searches

q = <string>

The user query. No processing is currently performed on the query.

Default: null (returns records as decided by the back-end)
Example: /search?q=matisse&page=5

show_suggestions = [ 1 | 0 ]

Enable ElasticSearch suggestions meachanism - this is used for features such as Did you mean turner? when running a search with truner (sic). suggestions in Elastic returns high-frequency terms. Note that Elastic may not provide any suggestions.

Default: '0' i.e. don't request suggestions
Example: /pages/search?show_suggestions=1

Data types¶

Singletons¶

Singletons are single objects, data records

Artwork record given its accession number {acno} /artworks/{acno}
Artist record given its Artist ID {aid} /artists/{aid}
Drupal record given its Node ID {nodeid} /pages/{nodeid}

Lists¶

Simple, unprocessed lists¶

The entire artworks collection /artworks
The entire set of artists /artists
All the Drupal nodes /pages

Oh, this is getting interesting

The general format is X/<id>/Y where: * X is the filtering dataset * <id> is the filtering object * Y is the target dataset

Examples:

/artists/558/artworks returns Artworks from Artist 558
/venues/1/shows returns Shows at Venue 1 (Tate Britain)

A number of permutations have been implemented - see urls.py to see which ones are currently available.