1. Introduction

The query search services enables to perform a user defined query that is build on a combination of work metadata properties (ex: search for a documentary with a title containing "global warming" and produced between 2019 and 2020), expressed in a defined format (ex: filter=wktype::DO|title::global warming|yor::[2019-2020]).

The query search service is based on an HTTP GET request. Users must authenticate with ISAN API credentials in addition to ISAN Registry credentials, i.e. by the mean of an HTTP Authorization header and a custom X-ISAN-Authorization header.

The query search is made of 4 elements:

1. filter : search criteria (via query-string parameter).
2. sorting : order criteria (via query-string parameter).
3. page : the page number (via query-string parameters). The full list of results is divided in pages, each page contain a number of results defined in the element limit below.
4. limit: maximum number of results per page (via query-string parameters).

Note that the query search service is NOT case sensitive.

Refer to the API search service guide for obtaining the best results when searching content in the ISAN Registry.

2. Request

2.1. Syntax

#Request 
GET /api/works?filter=string&sorting=string&limit=n&page=i

2.2. Parameters

2.2.1. filter parameter

The filter parameter contains the search criteria string, made of one or more search properties. It is built on the following model: filter=property1::value|property2::value|property3::value .etc...

Refer to Building a query for details how to create a filter string for a specific query.

2.2.2. sorting parameter

[Known Bug: we are currently experiencing a bug with the sorting parameter, it won't work properly if you are using it.]

Description: Order by which search results are sorted. 

Required: No

Default: The default sorting is by descending result score (-score), i.e. from the highest to the lowest score.

Type: Query Parameter (String)

Authorized values: the following query properties : wktype, yor, duration. Several properties are allowed, separated by a pipe character ("|"). By default, properties are sorted in ascending order. When a property is prefixed by a minus sign ("-") then the property is sorted in descending order.

Example : sort by descending year and ascending title sort=-yor|duration 

2.2.3 page parameter

Description: The page number. The full list of results is divided in pages, each page contain a number of results defined in the element limit below. 

Required: No

Default: The default value is 0, it refers to the first page of results.

Type: Query Parameter (Positive Integer)

2.2.4 limit paramater

Description: Maximum number of results per page. 

Required: No

Default: The default value is 50. The maximum allowed value is 100.

Type: Query Parameter (Positive Integer)

Example:  To retrieve the 10th page of results with 100 results par page page=9&limit=100

3. Response

3.1. Response Headers

*All dates are formatted as follow: Fri, 07 Jun 2013 09:14:19 GMT

3.2. Response Elements

The response is an ISANDataListType (i.e. array of ISANDataType).

#XML example
<common:isanDataListType>
    <common:ISANData></common:ISANData>
    <common:ISANData></common:ISANData>
    …
</common:isanDataListType

#JSON example
{"isandatas": [
   "java.util.ArrayList",
    [ {   },
      {   },
       …]]
}

The following table lists the descriptive metadata returned for each ISANDataType retrieved:

Detailed information about a work can be obtained with the lookup service.

3.4. Errors

In case of error, the body response contains an error status. For all errors, further details are available in the description field of the error status.

The following table lists the possible errors that can be generated.

4. Examples

Retrieve all works where the title contains "ice age", sort the results by the highest to the lowest score

curl --request GET \
--url 'https://api.isan.org/api/works?filter=title%3A%3Aice%20age&page=0&limit=20&get_all_fields=true' \
--header 'accept: application/json' \
--header 'authorization: Basic bXlBcGlMb2dpbi5hcGk6bXlBcGlQYXNzd29yZA==' \
--header 'content-type: application/FormUrlEncoded' \
--header 'x-isan-authorization: ISANUSER bXlSZWdpc3RyeUxvZ2luOmM2ZDM4MGVlODVlYjUzMGY3NTQzOTdjNTlmNGNlYWEy' \

Retrieve all films or documentaries where Clint Eastwood has participated as an actor, sort the results from the newest to oldest.

curl --request GET \
--url 'https://api.isan.org/api/works?filter=act%3A%3AClint%20Eastwood%7Cwktype%3A%3ADO%2CFF%26sorting%3D-yor%26page%3D0%26limit%3D50&page=0&limit=20&get_all_fields=true' \
--header 'accept: application/json' \
--header 'authorization: Basic bXlBcGlMb2dpbi5hcGk6bXlBcGlQYXNzd29yZA==' \
--header 'content-type: application/FormUrlEncoded' \
--header 'x-isan-authorization: ISANUSER bXlSZWdpc3RyeUxvZ2luOmM2ZDM4MGVlODVlYjUzMGY3NTQzOTdjNTlmNGNlYWEy' \

Refer to the API search service guide for obtaining the best results when searching content in the ISAN Registry.