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:
- filter : search criteria (via query-string parameter).
- sorting : order criteria (via query-string parameter).
- 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.
- 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
|
Headers |
Description |
|
Date |
Server response date-time * |
|
Content-Range |
Indicate how many items are being returned and how many total items exist. Content-Range: items <FIRST>-<LAST>/<TOTAL> The total number of items is sent only for the first page of results otherwise an asterisk. Content-Range: items 1-50/3954 or items 51-100/* |
|
Content-Type |
Type of representation and character set : application/xml;charset=UTF-8 or application/json;charset=UTF-8 |
|
Cache-Control |
Expiration life-time (7200 seconds) |
|
Expires |
Expiration date-time value |
|
Content-Length |
Size in bytes of the body of the representation |
*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:
|
Headers |
Description |
|
Occurrence |
|
ISAN |
ISAN number of the work |
|
1 |
|
Titles |
Matching titles if title property or shtitle property has been specified in the filtering parameter, original titles otherwise |
|
1 |
|
Year of reference |
Year of reference of the work or year of oldest episode in case of serial header (series) |
|
1 |
|
Duration |
Duration of the work. Not available for Serial headers (series). Applies only if duration property has been submitted in filtering parameter or in sorting parameter |
|
0 or 1 |
|
WorkType |
Work Type code. Not available for Serial headers. Applies only if wktype property has been submitted in filtering parameter or in sorting parameter |
|
0 or 1 |
|
Participants |
Matching participants. Not available for Serial headers (series). Applies only if at least one participant’s roles property has been submitted in filtering parameter |
|
0 or 1 |
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.
|
HTTP CODE |
Description |
|
401, UNAUTHORIZED |
ERROR: THIS OPERATION REQUIRES AUTHENTICATION Applies if no Authorization header have been submitted or If X-ISAN-Authorization header is missing |
|
401, UNAUTHORIZED |
ERROR: USER IS BLOCKED OR CLIENT ACCOUNT IS INACTIVE Applies for X-ISAN-Authorization header verification, if the user account is blocked |
|
400, BAD REQUEST |
ERROR: THE NUMBER OF RESULTS PER PAGE CAN'T BE GREATER THAN %s |
|
400, BAD REQUEST |
ERROR: SEARCH CRITERIA CAN'T BE EMPTY - AT LEAST ONE FILTER IS REQUIRED |
|
400, BAD REQUEST |
ERROR: PARAMETER %s IN SEARCH CRITERIA IS INVALID |
|
400, BAD REQUEST |
ERROR: PARAMETER %s IN SORT CRITERIA IS INVALID |
|
400, BAD REQUEST |
ERROR: THE PAGE NUMBER SHOULD BE GREATER THAN 0 |
|
400, BAD REQUEST |
ERROR: SH (%s) HAS NOT BEEN FOUND |
|
404, NOT FOUND |
ERROR: NO WORKS FOUND |
|
500, INTERNAL SERVER ERROR |
ERROR: AN UNEXPECTED ERROR OCCURED - PLEASE CONTACT sysadmin@isan.org Applies for any other different reasons than previously listed |
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.