Documentation Powered by ReDoc

Digital Bodleian Data API Specification (1.0.0)

Download OpenAPI specification:Download

URL: https://www.bodleian.ox.ac.uk

Search

Fulltext Queries

Fulltext queries are performed by setting the value of the q parameter in the querystring. Complex operations for filtering can be accomplished by using Lucene query syntax in the fq parameter, e.g., fq=(collections:"Arabic" OR collections:"Western). This has been tested with AND, OR, and NOT operators. Multiple fq parameters provided will be treated as AND statements.

The response is an object that can be parsed for a page of search results. The member key contains an array of search results, if any were found. Results to a query are sorted by relevance by default in this array. The sorting of the array can be controlled with the sort query parameter.

query Parameters
q
string
Enum: "binding" "collections" "contents" "date" "decorations" "description" "hands" "holding-institution" "inscriptions" "languages" "materials" "musical-notation" "provenance" "shelfmark" "titles" "architects" "people" "artists" "authors" "cartographers" "commentators" "composers" "compilers" "draughtsmen" "editors" "engravers" "former-owners" "illustrators" "origins" "patrons" "photographers" "printers" "publishers" "sitters" "translators" "performers"
Example: q=unicorns

A fulltext search query. This supports some Lucene search syntax, such as the fuzzy operator (~). Phrases can be searched by surrounding them in quotation marks. Field-specific queries from the list above work, as do the boolean operators AND, OR, and NOT, e.g., ?q=talmud NOT collections:"Arabic" AND date:[1700 TO *].

page
integer
Example: page=10

The page number.

fq
string
Enum: "collections" "completeness" "origins" "languages" "has-musical-notation"
Example: fq=collections:"Arabic"&fq=(collections:"Arabic" OR collections:"Western)&fq=date:[700 TO 900]

A filter to apply to the query. Use this with Lucene syntax to filter on a given value, e.g., completeness:Yes for completely digitised objects or has-musical-notation:No for objects without musical notation. Fields from the list above are supported. Multiple fq parameters provided will be treated as AND statements. For dates, date:[1250 TO 1350] represents the inclusive range 1250-01-01 to 1350-12-31, and date:[* TO 1350] means 'up to and including 1350'. Note that these ranges are inclusive on both ends.

sort
string
Enum: "relevance" "shelfmark" "published" "date"
Example: sort=date desc

Controls the sort order of the results. relevance desc (default) will sort the results in order from most to least relevant. shelfmark will sort the results first by institution, then by shelfmark in alphanumeric order. published desc will sort by most recently digitized first. date asc will sort by creation date. Each of these can be reversed using asc or desc.

rows
string
Enum: "20" "40" "100"

The number of results per page.

Responses

Response samples

Content type
application/ld+json
{}

Collections

Retrieve a Digital Bodleian Collection

Digital Bodleian collections are retrieved by accessing this route using a GET request and submitting a string containing the collection name, e.g., /collections/western-medieval-manuscripts.

path Parameters
name
required
string
Example: western-medieval-manuscripts

The name of the collection

Responses

Response samples

Content type
application/ld+json
{}

Search a Digital Bodleian Collection

Fulltext queries can be performed on collections by accessing this route using a GET request and submitting a string containing the collection name and setting the value of the q parameter in the querystring.

Complex operations for filtering can be accomplished by using Lucene query syntax in the fq parameter, e.g., fq=(languages:English). This has been tested with AND, OR, and NOT operators. Multiple fq parameters provided will be treated as AND statements.

The response is an object that can be parsed for a page of search results. The member key contains an array of search results, if any were found. Results to a query are sorted by relevance by default in this array. The sorting of the array can be controlled with the sort query parameter.

path Parameters
name
required
string
Example: western-medieval-manuscripts

The name of the collection

query Parameters
q
string
Enum: "binding" "collections" "contents" "date" "decorations" "description" "hands" "holding-institution" "inscriptions" "languages" "materials" "musical-notation" "provenance" "shelfmark" "titles" "architects" "people" "artists" "authors" "cartographers" "commentators" "composers" "compilers" "draughtsmen" "editors" "engravers" "former-owners" "illustrators" "origins" "patrons" "photographers" "printers" "publishers" "sitters" "translators" "performers"
Example: q=unicorns

A fulltext search query. This supports some Lucene search syntax, such as the fuzzy operator (~). Phrases can be searched by surrounding them in quotation marks. Field-specific queries from the list above work, as do the boolean operators AND, OR, and NOT, e.g., ?q=talmud NOT collections:"Arabic" AND date:[1700 TO *].

page
integer
Example: page=10

The page number.

fq
string
Enum: "collections" "completeness" "origins" "languages" "has-musical-notation"
Example: fq=collections:"Arabic"&fq=(collections:"Arabic" OR collections:"Western)&fq=date:[700 TO 900]

A filter to apply to the query. Use this with Lucene syntax to filter on a given value, e.g., completeness:Yes for completely digitised objects or has-musical-notation:No for objects without musical notation. Fields from the list above are supported. Multiple fq parameters provided will be treated as AND statements. For dates, date:[1250 TO 1350] represents the inclusive range 1250-01-01 to 1350-12-31, and date:[* TO 1350] means 'up to and including 1350'. Note that these ranges are inclusive on both ends.

sort
string
Enum: "relevance" "shelfmark" "published" "date"
Example: sort=date desc

Controls the sort order of the results. relevance desc (default) will sort the results in order from most to least relevant. shelfmark will sort the results first by institution, then by shelfmark in alphanumeric order. published desc will sort by most recently digitized first. date asc will sort by creation date. Each of these can be reversed using asc or desc.

rows
string
Enum: "20" "40" "100"

The number of results per page.

Responses

Response samples

Content type
application/ld+json
{}

Partners

Retrieve a Partner's Collection

Partner collections are retrieved by accessing this route using a GET request and submitting a string containing the partner name, e.g., /partners/balliol.

path Parameters
name
required
string
Example: balliol

The name of the partner

Responses

Response samples

Content type
application/ld+json
{}

Search a Partner's Collection

Fulltext queries can be performed on collections by accessing this route using a GET request and submitting a string containing the partner's name and setting the value of the q parameter in the querystring.

Complex operations for filtering can be accomplished by using Lucene query syntax in the fq parameter, e.g., fq=(languages:English). This has been tested with AND, OR, and NOT operators. Multiple fq parameters provided will be treated as AND statements.

The response is an object that can be parsed for a page of search results. The member key contains an array of search results, if any were found. Results to a query are sorted by relevance by default in this array. The sorting of the array can be controlled with the sort query parameter.

path Parameters
name
required
string
Example: balliol

The name of the partner

query Parameters
q
string
Enum: "binding" "collections" "contents" "date" "decorations" "description" "hands" "holding-institution" "inscriptions" "languages" "materials" "musical-notation" "provenance" "shelfmark" "titles" "architects" "people" "artists" "authors" "cartographers" "commentators" "composers" "compilers" "draughtsmen" "editors" "engravers" "former-owners" "illustrators" "origins" "patrons" "photographers" "printers" "publishers" "sitters" "translators" "performers"
Example: q=unicorns

A fulltext search query. This supports some Lucene search syntax, such as the fuzzy operator (~). Phrases can be searched by surrounding them in quotation marks. Field-specific queries from the list above work, as do the boolean operators AND, OR, and NOT, e.g., ?q=talmud NOT collections:"Arabic" AND date:[1700 TO *].

page
integer
Example: page=10

The page number.

fq
string
Enum: "collections" "completeness" "origins" "languages" "has-musical-notation"
Example: fq=collections:"Arabic"&fq=(collections:"Arabic" OR collections:"Western)&fq=date:[700 TO 900]

A filter to apply to the query. Use this with Lucene syntax to filter on a given value, e.g., completeness:Yes for completely digitised objects or has-musical-notation:No for objects without musical notation. Fields from the list above are supported. Multiple fq parameters provided will be treated as AND statements. For dates, date:[1250 TO 1350] represents the inclusive range 1250-01-01 to 1350-12-31, and date:[* TO 1350] means 'up to and including 1350'. Note that these ranges are inclusive on both ends.

sort
string
Enum: "relevance" "shelfmark" "published" "date"
Example: sort=date desc

Controls the sort order of the results. relevance desc (default) will sort the results in order from most to least relevant. shelfmark will sort the results first by institution, then by shelfmark in alphanumeric order. published desc will sort by most recently digitized first. date asc will sort by creation date. Each of these can be reversed using asc or desc.

rows
string
Enum: "20" "40" "100"

The number of results per page.

Responses

Response samples

Content type
application/ld+json
{}

Objects

Retrieve a Surface record

A surface represents a page in an object.

path Parameters
surface_id
required
string <uuid>

The ID of the surface

object_id
required
string <uuid>

The ID of the object containing the surface

Responses

Response samples

Content type
application/ld+json
{}

Retrieve a Digital Bodleian object record

An object represents a physical object in the collection. For example, this can be a map, a board game, or a manuscript.

path Parameters
object_id
required
string <uuid>
Example: faeff7fb-f8a7-44b5-95ed-cff9a9ffd198

The ID of the object to retrieve

Responses

Response samples

Content type
application/ld+json
{}

Search over the object's surfaces

Search the surfaces belonging to the given object. This accepts the same parameters as the main search API, except for the sort parameter, since surfaces are expected to be returned in the order in which they appear in the document.

path Parameters
object_id
required
string <uuid>
Example: faeff7fb-f8a7-44b5-95ed-cff9a9ffd198

The ID of the object containing the surfaces

query Parameters
q
string
Enum: "binding" "collections" "contents" "date" "decorations" "description" "hands" "holding-institution" "inscriptions" "languages" "materials" "musical-notation" "provenance" "shelfmark" "titles" "architects" "people" "artists" "authors" "cartographers" "commentators" "composers" "compilers" "draughtsmen" "editors" "engravers" "former-owners" "illustrators" "origins" "patrons" "photographers" "printers" "publishers" "sitters" "translators" "performers"
Example: q=unicorns

A fulltext search query. This supports some Lucene search syntax, such as the fuzzy operator (~). Phrases can be searched by surrounding them in quotation marks. Field-specific queries from the list above work, as do the boolean operators AND, OR, and NOT, e.g., ?q=talmud NOT collections:"Arabic" AND date:[1700 TO *].

page
integer
Example: page=10

The page number.

fq
string
Enum: "collections" "completeness" "origins" "languages" "has-musical-notation"
Example: fq=collections:"Arabic"&fq=(collections:"Arabic" OR collections:"Western)&fq=date:[700 TO 900]

A filter to apply to the query. Use this with Lucene syntax to filter on a given value, e.g., completeness:Yes for completely digitised objects or has-musical-notation:No for objects without musical notation. Fields from the list above are supported. Multiple fq parameters provided will be treated as AND statements. For dates, date:[1250 TO 1350] represents the inclusive range 1250-01-01 to 1350-12-31, and date:[* TO 1350] means 'up to and including 1350'. Note that these ranges are inclusive on both ends.

rows
string
Enum: "20" "40" "100"

The number of results per page.

Responses

Response samples

Content type
application/ld+json
{}

Account

Retrieve Authenticated User Account Data

A GET request can be used on /account to retrieve a response containing the user account data.

Users performing a GET request who are not authenticated will receive a 401 response, indicating that they are not operating as a logged-in user.

The GET response for authenticated users will contain account information including a savedSearches and a savedObjects key containing searches and objects saved by the user.

Responses

Response samples

Content type
application/ld+json
{}

Save a Search

Searches are saved to the user account by accessing this route with a POST request containing a valid JSON object. Searches can be saved from the search page e.g. /search/?q=Shakespeare or via a collection page e.g. /partners/balliol/?q=Shakespeare by changing the route value in the request body to /search/ or /partners/balliol/ etc.

Request Body schema: application/json
name
string

An optional name for the search the user wishes to save. It must be in valid JSON format, e.g., {"name": "Shakespeare in English"}. If left out of the request body the default value will be Unnamed search.

route
required
string

The route for where the search is being saved from. If must be in valid JSON format, e.g., {"route": "/search/"}.

search
required
string

The query string containing the search parameters used for the search the account user wishes to save. The leading question mark must be omitted. It must be in valid JSON format, e.g., {"search": "q=Shakespeare&fq=languages:English"}.

Responses

Request samples

Content type
application/json
{
  • "name": "Shakespeare in English",
  • "route": "/search/",
  • "search": "q=Shakespeare&fq=languages:English"
}

Response samples

Content type
application/json
{
  • "id": "550ff925-d87b-4e8a-a5b7-c9ecd3bef265",
  • "name": "Shakespeare in Western English",
  • "route": "/search/",
  • "search": [
    ],
  • "created": "2019-11-05 14:51:50"
}

Delete a Search

Searches are deleted from the user account by accessing this route using a DELETE request and submitting a primary key in UUID format as a part of the path, e.g., /account/searches/550ff925-d87b-4e8a-a5b7-c9ecd3bef265.

path Parameters
saved_search_id
required
string <uuid>
Example: 550ff925-d87b-4e8a-a5b7-c9ecd3bef265

The value of the ID of a saved search in UUID format

Responses

Save an Object

Objects are saved to the user account by accessing this route with a POST request containing a valid JSON object.

Request Body schema: application/json
object
string

The URL of the object the user wishes to save. It must be in valid JSON format, e.g., {"https://digital.bodleian.ox.ac.uk/objects/390fd0e8-9eae-475d-9564-ed916ab9035"}.

tags
object

The list of tags the user wishes the saved object to be grouped under. It must be in valid JSON format, e.g., {"tags": ["Shakespeare", "Elizabethan Dramas"]}.

surfaces
object

The list of surfaces the user wishes to save from the object. The surfaces listed must all be the URLS of existing surfaces. It must be in valid JSON format, e.g., {"surfaces": ["https://digital.bodleian.ox.ac.uk/objects/390fd0e8-9eae-475d-9564-ed916ab9035/surfaces/a13ee009-596c-4151-8f4c-568b0c2ce2cc", "https://digital.bodleian.ox.ac.uk/objects/390fd0e8-9eae-475d-9564-ed916ab9035/surfaces/a024a538-aef3-44b3-ad11-51c6a8b04ea2"]}.

Responses

Response samples

Content type
application/json
{}

Update a Saved Object

Saved objects are updated by accessing this route with a PUT request containing a valid JSON object and submitting a primary key in UUID format as a part of the path, e.g., /account/objects/390fd0e8-9eae-475d-9564-ed916ab9035c

path Parameters
saved_object_id
required
string <uuid>
Example: 390fd0e8-9eae-475d-9564-ed916ab9035c

The value of the ID of a saved object in UUID format

Request Body schema: application/json
tags
object

The list of tags the user wishes the saved object to be grouped under. It must be in valid JSON format, e.g., {"tags": ["Shakespeare", "Elizabethan Dramas"]}. Ommision of tags in the request body will result in any saved tags for the object being replaced with an empty list, e.g., {"tags": []}.

surfaces
object

The list of surfaces the user wishes to save from the object. The surfaces listed must all be valid UUIDs. It must be in valid JSON format, e.g., {"surfaces": ["a13ee009-596c-4151-8f4c-568b0c2ce2cc", "a024a538-aef3-44b3-ad11-51c6a8b04ea2"]}. Ommision of surfaces will result in any saved surfaces for the object being replaced with an empty list, e.g., {"surfaces": []}.

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ],
  • "surfaces": [
    ]
}

Response samples

Content type
application/json
{}

Update a Saved Object

Saved objects are updated by accessing this route with a PATCH request containing a valid JSON object and submitting a primary key in UUID format as a part of the path, e.g., /account/objects/390fd0e8-9eae-475d-9564-ed916ab9035c.

path Parameters
saved_object_id
required
string <uuid>
Example: 390fd0e8-9eae-475d-9564-ed916ab9035c

The value of the ID of a saved object in UUID format

Request Body schema: application/json
tags
object

The list of tags the user wishes the saved object to be grouped under. It must be in valid JSON format, e.g., {"tags": ["Shakespeare", "Elizabethan Dramas"]}. Ommision of tags in the request body will result in any saved tags for the object being replaced with an empty list, e.g., {"tags": []}.

surfaces
object

The list of surfaces the user wishes to save from the object. The surfaces listed must all be valid UUIDs. It must be in valid JSON format, e.g., {"surfaces": ["a13ee009-596c-4151-8f4c-568b0c2ce2cc", "a024a538-aef3-44b3-ad11-51c6a8b04ea2"]}. Ommision of surfaces will result in any saved surfaces for the object being replaced with an empty list, e.g., {"surfaces": []}.

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ],
  • "surfaces": [
    ]
}

Response samples

Content type
application/json
{}

Delete a Saved Object

Saved objects are deleted from the user account by accessing this route using a DELETE request and submitting a primary key in UUID format as a part of the path, e.g., /account/objects/390fd0e8-9eae-475d-9564-ed916ab9035c.

path Parameters
saved_object_id
required
string <uuid>
Example: 390fd0e8-9eae-475d-9564-ed916ab9035c

The value of the ID of a saved object in UUID format

Responses