Hierarchical records

Retrieve information on records which are part of a hierarchical relationship with other records.

The hierarchical API methods allow you to travese through a hierarchical set of records. Some records in Europeana are part of such a hierarchy. A good example is the Wiener Zeitung from the Austrian National Library, a newspaper where the different editions are represented in a hierarchical structure. The hierarchical structure is shown on the record page next to "Related items". This structure and navigation is generated with the hierarchical API methods as documented on this page.

Hierarchical API methods

All API methods reside in the record namespace:

https://www.europeana.eu/api/v2/record/[recordID]/[method].json

self.json

Returns information on the record as part of a hierarchy.

/api/v2/record/9200300/BibliographicResource_3000052917527/self.json?wskey=xxxxx

Request

ParameterDatatypeDescription
callbackStringName of a client side callback function.

Response

Returns a "self" response element with information on the hierarchy with the title, description, type (media type), index (ordered position with respect to the siblings (if any), starting with 1), childrenCount (number of child elements, only if hasChildren is true) and whether it has children (boolean):

{
  "success": true,
  "self": {
    "id": "/9200300/BibliographicResource_3000052917527",
    "title": {
      "def": [
       "Wiener Zeitung"
      ]
    },
    "type": "TEXT",
    "index": 1,
    "childrenCount": 30817,
    "hasChildren": true
  }
}

If the record is not part of a hierarchy, the success field will be false and the error message will state that the record ID is not a valid identifier.

parent.json

Returns information on the parent record of this record in the hierarchy. This call also retrieves the information as present in the "self.json" method.

/api/v2/record/9200300/BibliographicResource_3000116310788/parent.json?wskey=xxxxx

Request

ParameterDatatypeDescription
callbackStringName of a client side callback function.

Response

Returns a "self" response element (see above) along with a "parent" element with the information on the parent record:

{
  "success": true,
  "self": { .. }
  "parent": {
    "id": "/9200300/BibliographicResource_3000052917527",
    "title": {
      "def": [
       "Wiener Zeitung"
      ]
    },
    "type": "TEXT",
    "index": 1,
    "childrenCount": 30817,
    "hasChildren": true
  }
}

If the record has no parent (e.g. it is by itself a parent), the success field will be false and the message field will contain the message "This record has no parent". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

children.json

Returns the children of the record in the hierarchical structure.

/api/v2/record/9200300/BibliographicResource_3000052917527/children.json?wskey=xxxxx&offset=10&limit=10

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "children" element with the children. Each child has a field named relbefore (a boolean, whether there are preceding siblings) and hasChildren (a boolean, to indicate whether this child has other children in a sub-hierarchy):

{
  "success": true,
  "self": { .. }
  "children": [
    {
      "id": "/9200300/BibliographicResource_3000116311348",
      "title": {
        "def": [
          "Wiener Zeitung - 1703-09-17"
        ]
      },
      "type": "TEXT",
      "parent": "/9200300/BibliographicResource_3000052917527",
      "index": 11,
      "relBefore": true,
      "hasChildren": false
    },
    { .. }
  ]
}

If the record has no children, the success field will be false and the message field will contain the message "This record has no children". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

preceding-siblings.json

Returns the preceding sibling of the record in the hierarchical structure.

/api/v2/record9200300/BibliographicResource_3000116311348/preceding-siblings.json?wskey=xxxxx

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "preceding-siblings" element with the preceding children. The fields are the same as for the "children" element in the children.json method.

{
  "success": true,
  "self": { .. }
  "preceding-siblings": [
    { .. },
    { .. }
  ]
}

If the record has no preceding siblings, the success field will be false and the message field will contain the message "This record has no preceding siblings". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

following-siblings.json

Returns the following siblings of the record in the hierarchical structure.

/api/v2/record/9200300/BibliographicResource_3000116311348/following-siblings.json?wskey=xxxxx

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "following-siblings" element with the following children. The fields are the same as for the "children" element in the children.json method.

{
  "success": true,
  "self": { .. }
  "following-siblings": [
    { .. },
    { .. }
  ]
}

If the record has no following siblings, the success field will be false and the message field will contain the message "This record has no following siblings". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

ancestor-self-siblings.json

Returns the parent and siblings of the record in the hierarchical structure.

/api/v2/record/9200300/BibliographicResource_3000116310788/ancestor-self-siblings.json?wskey=xxxxx

Request

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "following-siblings" element with the following siblings, a "preceding-siblings" element with the preceding sibling and an "ancestors" element with the ancestors. See the other methods for the output and elements of these fields.

If the record has no parent or sibling, the success field will be false and the message field will contain the message "This record has no parent or siblings". If any of the fields are empty (e.g. no preceding siblings), this field will be omitted from the response. If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.