ISAN API 3.0 - queries service

/queries service enables to query the ISAN Registry for retrieving existing ISAN and corresponding data. This service is available to all API users (reader or registrant roles)

ISAN API 3.0 offers two methods to query the ISAN registry

1. Query based search (GET /queries): the developper can build the search query by selecting a combination of fields. 
2. Record based search (POST /queries): the search  query is build automatically by the search engine based on the record data that is provided.

The service returns a list of results that match with the query. Results are sorted by relevancy (search engine score), but other sorting methods are supported.

By default, the service returns all data fields for each result ISAN, nevertheless it is possible to  customise the fields to return with the filter argument. This is particularly useful to speedup applications (query and response parsing) and to reduce the bandwidth.

Query based search

GET /queries Build your search and query the ISAN Registry

Refer to ISAN swagger interface for details and examples in json and xml

Arguments can be repeated when building the query, in order to form an OR condition between identical arguments (i.e. title 1 OR title 2 OR title 3). 

⚠️ Too long search queries might create invalid URLs. It is therefore recommended to use the Record based  search (POST /queries) for complex search that involve many arguments.

Record based search

POST /queries Query the ISAN Registry using the record data that is provided

Refer to the ISAN swagger interface for details and examples in json and xml

This is the preferred query method for complex search that involve many arguments.

⚠️ Too many arguments can lead to proor search results. For exemple if the query contains arguments of 'minor' importance for retrieving the content (e.g. a title kind) and if this search information differs from what is registered with ISAN, you might miss the target.

Body enclosed data

The service support several values or range of values for fields, even for not-repeatable fields. When fields are repeated (ex: titles) it forms a OR condition (i.e. title 1 OR title 2 OR title 3).

Consequently, the schema of data enclosed in the body of the request differs slightly with with the schema used in the service POST /records. The following changes apply: 

• Not-repeatable fields: The service expect a list of values even if a sigle value is provided e.g. "recordKinds": ["episode"] (do not forget the [ ] in JSON)!!
• referenceYear and releaseDate: referenceYear and releaseDate are composed fields that can contain a single element (exact value) or a pair of min/max elements (range of years / dates). See examples below
• Duration: duration is a composed field that can contain a single element (exact value) or a pair of min/max elements (range of durations) plus the duration unit (min or sec). See examples below.
  
  • example 1: range of referenceYear, releaseDate & durations

XML

<isanSearchQuery>
  <title>We Still Have The Deep Black Night</title>
  <referenceYear min="2019" max="2022"/>
  <releaseDate min="2019-01-01" max="2022-01-01"/>
  <duration unit="sec" min="175" max="190"/>
</isanSearchQuery>

JSON

{
  "title": [{"value": "We Still Have The Deep Black Night"}],
  "referenceYear": {
    "min": 2019,
    "max": 2022
  }
  "releaseDate": {
    "min": "2019-01-01",
    "max": "2022-01-01"
  }  
  "duration": {
    "unit": "sec", 
    "min": 175, 
    "max": 190
  },
}

• •  example 2: exact referenceYear, releaseDate & duration value

XML

<isanSearchQuery>
  <title>We Still Have The Deep Black Night</title>
  <referenceYear>2019</referenceYear>
  <releaseDate>2019-05-23</releaseDate>
  <duration unit="min">60</duration>
</isanSearchQuery>

JSON

{
  "title": [{ "value": "We Still Have The Deep Black Night"}],
  "referenceYear": {
    "value": 2019
  },
  "releaseDate": {
    "value": "2019-05-23"
 },
 "duration": {
    "unit": "sec", 
    "value": 60
  }
}

• • exemple 3: find a movie with a year of production (2018) that differs from the year of release (2021).

{

    "recordKinds": ["single"], 
    "titles": [{"value": "OS 117"}], 
    "duration": {"min": 90, "max": 130}, 
    "colorKinds": ["color"],
    "referenceYear": {"min": 2017, "max":2019}, 
    "participants": [{"role": "director", "value": "Nicolas Bedos"}], 
    "sortBy": "relevance", 
    "order": "desc", 
    "page": 0, 
    "size": 25, 
    "fields": ["allRecordData"]
}