Skip to main content
Sign in

ISAN API 3.0 query samples

Régis Flad
  • Updated

This article contains some query samples in the ISAN Registry. It covers the following topics:

  1. How to list children of an ISAN?
  2. Series Episodes Search
  3. more to come...

1. How to list children of an ISAN?

ISAN API Path: /queries

List all groups of a series

{ 
  "parentIsan": { 
    "root": "0000-0000-0000" 
  }, 
  "recordKinds": ["group"] 
}

List all episodes of a series

{ 
  "parentIsan": { 
    "root": "0000-0000-0000" 
  }, 
  "recordKinds": ["episode"] 
}

List all episodes of a group

{ 
  "parentIsan": { 
    "root": "0000-0000-0000", 
    "episodeOrPart": "F001"
  }, 
  "recordKinds": ["episode"] 
}

List child versions

All child versions

{ 
  "parentIsan": { 
    "root": "0000-0000-0000", 
    "episodeOrPart": "0000"
    "check1": "1", 
    "version": "0000-0000", 
    "check2": "2"
  }, 
}

or

{ 
    "parentIsan": { 
        "value": "0000-0000-0000-0000-1-0000-0000-2" 
    } 
}

Specific recordKind in child versions 

{ 
    "parentIsan": { 
        "value": "0000-0000-0000-0000-1-0000-0000-2" 
    } 
    "recordKinds": ["manifestation", "related_item"]
}

 

 

2. Series Episode Search

Workaround for Unstable Series Episode Search Results

Current Issue: Search Instability

Users may currently experience inconsistent or unstable results when searching for episodes of a series using a single query.

Root Cause:

We have identified a bug in the currently deployed version of our search engine, Apache Solr in Cloud Mode (distributed across multiple instances). The specific version in use exhibits instability when processing queries containing "joins" (e.g., linking episodes to their parent series in a single request). This is caused by an index replication bug across the distributed database instances.

Status:

While a newer version of Solr exists that resolves this issue, the impact and complexity of migrating our production environment are significant. Consequently, we cannot yet provide a definitive schedule for this migration.

We apologize for this inconvenience and are working to schedule the necessary infrastructure upgrade as soon as feasible. In the meantime you will find a workaround below.

❌ The Unstable Approach (Single Query with Join)

The following method attempts to find an episode by specifying both the parent series title(parentTitles) and the episode title (titles) in a single request. This relies on an internal "join" operation to link the episode to its parent series.

⚠️ Warning: Due to the known bug, this query may return incomplete results, duplicate entries, or no results at all, even if the data exists. The replication lag between Solr instances causes the join to fail intermittently.

Unstable Request Example:

json
{
  "parentTitles": [
    {
      "value": "Hawaii 5-0"
    }
  ],
  "titles": [
    {
      "value": "Kanalua"
    }
  ],
  "recordKinds": [
    "episode"
  ],
  "sortBy": "relevance",
  "order": "desc",
  "page": 0,
  "size": 25,
  "fields": [
    "allRecordData"
  ]
}

Note: While this query structure is logically correct, the underlying Solr Cloud infrastructure currently fails to execute the join between parentTitles and titles reliably.


✅ Recommended Workaround: Two-Step Search

Until the migration is completed, we strongly recommend performing episode searches in two distinct steps. This approach bypasses the problematic "join" operation by first isolating the Series ISAN and then querying for episodes linked to that specific root.

Step 1: Identify the Series ISAN

First, search for the series itself to retrieve its unique ISAN. Using specific parameters (such as titles, reference year) is highly recommended to distinguish between reboots or series with identical titles.

Example Scenario:

Searching for "Hawaii Five-0" returns multiple results (the 1968 original and the 2010 reboot). You must identify the correct ISAN for the specific series you are targeting.

Request Example (POST /query):

json
{
  "titles": [
    {
      "value": "Hawaii Five-0"
    }
  ],
  "recordKinds": [
    "series"
  ],
  "sortBy": "relevance",
  "order": "desc",
  "page": 0,
  "size": 25,
  "fields": [
    "allRecordData"
  ]
}

Result Analysis:

The query may return multiple series. In this example, three results are returned. You must verify the metadata (e.g., reference year) to select the correct ISAN.
Target ISAN identified: 0000-0002-C87E (Example for the 2010 series).

Step 2: Search for Episodes using the Root ISAN

Once the Series ISAN is confirmed, perform a second query specifically for episodes. Use the root field of the ISAN structure to filter episodes that belong strictly to that series.

ISAN Structure Context:

An Episode ISAN is structurally linked to its Series ISAN. The Series ISAN serves as the "Root" for all its episodes. By filtering on recordIsan.root, you avoid the need for a complex join operation.

Request Example (POST /query):

json
{
  "recordIsan": {
    "root": "0000-0002-C87E"
  },
  "titles": [
    {
      "value": "Kanalua"
    }
  ],
  "recordKinds": [
    "episode"
  ],
  "sortBy": "relevance",
  "order": "desc",
  "page": 0,
  "size": 25,
  "fields": [
    "allRecordData"
  ]
}

Outcome:

This method ensures stable and accurate results by relying on direct index lookups rather than distributed joins.





 

Related articles