Difference between revisions of "hierarchyEadAncestors"

From Archives Portal Europe Wiki
Jump to: navigation, search
 
(3 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
This service is a POST-request.
 
This service is a POST-request.
  
−
This hierarchy service delivers a list of all archival descriptions in the path from root to {id} in the hierarchy of the archival description. A web developer can use this service to create a tree-like presentation of a finding aid.  
+
This hierarchy-service delivers a list of all archival descriptions in the path from root to {id} of an archival description in the hierarchy of finding aid, a holdings guide or a source guide. A web developer can use this service to create a tree-like presentation of a finding aid, holdings guide or source guide.  
  
  
 
<div><br/>__TOC__<br/></div>
 
<div><br/>__TOC__<br/></div>
 
= Request parameters =
 
= Request parameters =
−
Two request parameters can be used to do a search in archival descriptions.
+
Only one request parameter is required: the internal APE identifier of the descriptive unit for which a list of higher level ancestors is needed.
  
−
eg.
+
On [base_url]/hierarchy/ead/{id}/ancestors, all the clevel descriptive units that are on the path from {id} to the root in the hierarchy of a finding aid, holdings guide or source guide are given.
  
−
<pre>
+
''N.B.: you can find the (internal APE) identifier of a descriptive unit (always starting with a "C") which is necessary for using this service via the [[searchEad | /search/ead]] service''
−
{
+
−
  "count": "5",
+
−
  "startIndex": 0
+
−
}
+
−
</pre>
+
−
 
+
−
On [base_url]/hierarchy/ead/{id}/ancestors, it gives all the clevel descriptive units of finding aid identified with "{id}" that are on the path from {id} to the root of the hierarchy of the finding aid.
+
−
 
+
−
== count ==
+
−
The resultlist is delivered in chunks of a certain size. Request parameter "count" describes the number of results that are in one chunk. Optional. Default value is 5.
+
−
 
+
−
== startIndex ==
+
−
Request parameter "startIndex" enables you to select the results that you want to have. Counting starts at zero. If "count" = 5, the second chunk starts with startIndex 5, the following at startIndex 10, etc. Optional. Default value is 0.
+
  
 
= Response parameters =
 
= Response parameters =
−
The response contains a list of the descriptions where the requested search-term(s) was/were found.
+
The response contains a list of the descriptions that were found, from the descriptive unit for which an identifier was provided up till the root of the finding aid, holding guide or source guide.
  
−
eg.
+
== Empty Response example ==
−
<pre>
+
<pre style="white-space:-moz-pre-wrap; white-space:-pre-wrap; white-space:-o-pre-wrap; white-space:pre-wrap; word-wrap:break-word;">
 
{
 
{
 
   "totalResults": 0,
 
   "totalResults": 0,
 
   "startIndex": 0,
 
   "startIndex": 0,
 
   "totalPages": 0,
 
   "totalPages": 0,
−
   "ancestors": [
+
   "results": [
 
     {
 
     {
 
       "id": "string",
 
       "id": "string",
−
       "fondsUnitTitle": "string",
+
       "findingAidTitle": "string",
−
       "fondsUnitId": "string",
+
       "findingAidNo": "string",
 
       "repository": "string",
 
       "repository": "string",
 
       "country": "string",
 
       "country": "string",
Line 47: Line 34:
 
       "repositoryCode": "string",
 
       "repositoryCode": "string",
 
       "hasDigitalObject": false,
 
       "hasDigitalObject": false,
 +
      "numberOfDigitalObjects": 0,
 +
      "numberOfDigitalObjectsInDescendents": 0,
 +
      "numberOfDescendents": 0,
 
       "docType": "string",
 
       "docType": "string",
 
       "docTypeId": "string",
 
       "docTypeId": "string",
Line 54: Line 44:
 
       "unitTitle": "string",
 
       "unitTitle": "string",
 
       "scopeContent": "string",
 
       "scopeContent": "string",
−
       "siblingPosition": "string",
+
       "siblingPosition": 0,
−
       "treeDepth": "string"
+
       "ancestorLevel": 0
 
     }
 
     }
 +
  ]
 +
}
 +
</pre>
 +
 +
== Basic Response example ==
 +
For identifier C376209320:
 +
<pre style="white-space:-moz-pre-wrap; white-space:-pre-wrap; white-space:-o-pre-wrap; white-space:pre-wrap; word-wrap:break-word;">
 +
{
 +
  "totalResults": 2,
 +
  "startIndex": 0,
 +
  "totalPages": 1,
 +
  "results": [
 +
    {
 +
      "id": "F1049165",
 +
      "findingAidTitle": "Inventaris van de collectie archieven Strijdkrachten in Nederlands-Indië, (1938 - 1939) 1941 - 1957 [1960]",
 +
      "findingAidNo": "2.13.132",
 +
      "repository": "Nationaal Archief",
 +
      "country": "NETHERLANDS",
 +
      "language": "",
 +
      "langMaterial": "",
 +
      "unitDate": "1938-1960",
 +
      "repositoryCode": "NL-HaNA",
 +
      "hasDigitalObject": false,
 +
      "numberOfDigitalObjects": 0,
 +
      "numberOfDigitalObjectsInDescendents": 23297,
 +
      "numberOfDescendents": 5627,
 +
      "docType": "Finding Aid",
 +
      "docTypeId": "fa",
 +
      "level": "archdesc",
 +
      "indexDate": "",
 +
      "unitId": "2.13.132",
 +
      "unitTitle": "Ministerie van Defensie: Strijdkrachten in Nederlands-Indië",
 +
      "scopeContent": "In het archief zijn de onder meer opgenomen de archieven van het Hoofdkwartier van de Generale Staf in Nederlands-Indië (HKGS-NI) (1945-1950), de Centrale Militaire Inlichtingendienst (1941-1949), de Commandant \"7 December\" Divisie, de Adjudant-Generaal in Nederlands-Indië/Indonesië (1945-1952), de staven van de T t/m Z Brigade, de Compagnieën Aan- en Afvoertroepen, de Kwartiermeester-Generaal en het Afwikkelingscommando in Indonesië (1950-1951). Tenslotte bevat het archief ook een collectie onderdeelsverslagen van Koninklijke Landmacht en het KNIL. Daaronder bevinden zich ook verslagen van het Korps Speciale Troepen en Korps Militaire Politie/Koninklijke Marechaussee.  Inhoud Onderzoek toonde aan dat bij het Bureau Centraal Archievendepot (BCAD) van het Defensie, Archieven-, Registratie- en Informatiecentrum een aantal archieven aanwezig was die door militaire instanties/onderdelen gevormd waren in het voormalige Nederlands-Indië. In overleg met het Nationaal Archief is besloten om deze in de \"Collectie archieven Strijdkrachten in Nederlands-Indië, (1938-1939) 1941-1957 [1960]\" samen te brengen, te inventariseren en over te dragen aan het Nationaal Archief. Het betreft hier de volgende archieven: Beleidsterrein Operatiën: Hoofdkwartier van de Generale Staf in Nederlands-Indië, 1945 - 1950; Hoofdkwartier van de Generale Staf in Nederlands-Indië, Sectie Krijgsgeschiedenis, 1945 - 1949; Kabinet van de Legercommandant in Nederlands-Indië, 1945 - 1950; Netherlands Forces Intelligence Service/Centrale Militaire Inlichtingendienst, 1941 - 1949; Hoofdkwartier Militaire Luchtvaart van het KNIL, Kantoor Inlichtingen in Nederlands-Indië, (1938-1939) 1942 - 1950; Collectie verspreide archivalia van de strijdkrachten in Indonesië, speciaal Oost-Java, 1945 - 1949; Collectie archiefbescheiden van de Commandant \"7 December\" Divisie en de onder zijn bevel ressorterende onderdelen in Nederlands-Indië, 1945 - 1950; Staven van de T t/m Z-Brigade en de Staf Bataljon 2-13 Regiment Infanterie in Nederlands-Indië, [1945] 1946 - 1950; Collectie onderdeelsverslagen in Nederlands-Indië, 1945 - 1950; Bataljons behorende tot Regimenten Infanterie in Nederlands-Indië, 1945 - 1950; Compagnieën Aan- en Afvoertroepen, 1945 - 1950; 6, 10 en 14 Genie Veldcompagnie Indië, 1947 - 1950. Beleidsterrein Personeel: Korps Militaire Politie/Koninklijke Marechaussee KNIL, 1947 - 1951; Hoofdkwartier Adjudant-Generaal in Indonesië, 1945 - 1952; Afwikkelingscommando in Indonesië, 1950 - 1951; Hoofdkwartier Militaire Luchtvaart, Kantoor Personeel, 1945 - 1949; Hoofd van de Militaire Geneeskundige Dienst te Batavia, 1948 - 1949; Subsistentenbataljon, 1946 - 1951; Persoonlijk archief van reserve luitenant-kolonel mr. J.F. Scheers, 1946 - 1948, 1952 - 1957 [1960]. Beleidsterrein Materieel: Kwartiermeester-Generaal/Territorium Nieuw-Guinea, 1949; Kwartiermeester-Generaal/Legermaterieeldienst, 1947 - 1950; Kwartiermeester-Generaal/Assistent Directeur Leger Materieeldienst - 3, [1947] 1949; Commissie van Proefneming in Nederlands-Indië, 1946 - 1950. Het totaal van de collectie heeft een omvang van 125m.",
 +
      "siblingPosition": 0,
 +
      "ancestorLevel": 0
 +
    },
 +
    {
 +
      "id": "C376208583",
 +
      "findingAidTitle": "Inventaris van de collectie archieven Strijdkrachten in Nederlands-Indië, (1938 - 1939) 1941 - 1957 [1960]",
 +
      "findingAidNo": "2.13.132",
 +
      "repository": "Nationaal Archief",
 +
      "country": "NETHERLANDS",
 +
      "language": "",
 +
      "langMaterial": "",
 +
      "unitDate": "",
 +
      "repositoryCode": "NL-HaNA",
 +
      "hasDigitalObject": false,
 +
      "numberOfDigitalObjects": 0,
 +
      "numberOfDigitalObjectsInDescendents": 0,
 +
      "numberOfDescendents": 831,
 +
      "docType": "Descriptive Unit",
 +
      "docTypeId": "du",
 +
      "level": "clevel",
 +
      "indexDate": "",
 +
      "unitId": "2.13.132 - B",
 +
      "unitTitle": "Beleidsterrein Personeel",
 +
      "scopeContent": "",
 +
      "siblingPosition": 2,
 +
      "ancestorLevel": 1
 +
    }
 +
  ]
 
}
 
}
 
</pre>
 
</pre>
Line 69: Line 120:
 
The response parameter "totalPages" gives the number of chunks.
 
The response parameter "totalPages" gives the number of chunks.
  
−
== ancestors ==
+
== results ==
−
Enumeration of the results. A result could be a holdings guide, a source guide, a finding aid, or a descriptive unit (ie. a sublevel component). They are all optional except "id".
+
Enumeration of the results. A result could be a holdings guide, a source guide, a finding aid, or a descriptive unit (ie a sublevel component). They are all optional except "id".
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 76: Line 127:
 
| Internal APE identifier of the result
 
| Internal APE identifier of the result
 
|-
 
|-
−
| unitId
+
| findingAidTitle
−
| Identifier of the result provided by the repository
+
| Title of the finding aid, holdings guide or source guide
 
|-
 
|-
−
| unitTitle
+
| findingAidUnitId
−
| Description of the result
+
| Identifier of the fonds provided by the repository
 
|-
 
|-
−
| unitTitleWithHighlighting
+
| repository
−
| Description of the result, with the mark "<nowiki><em></nowiki>" to emphasize the search term that was used in the search request.
+
| Name of the repository holding the fonds
 
|-
 
|-
−
| unitDate
+
| country
−
| Date of creation of the result.
+
| Name of the country where the repository is, in English
 
|-
 
|-
−
| scopeContent
+
| language
−
| More descriptive information about the result.
+
| Language of the description of the result
 
|-
 
|-
−
| scopeContentWithHighlighting
+
| langMaterial
−
| More descriptive information about the result, with the mark "<nowiki><em></nowiki>" to emphasize the search term that was used in the search request.
+
| Language in which the result is created
 +
|-
 +
| unitDate
 +
| Date of creation of the result
 +
|-
 +
| repositoryCode
 +
| Code of the repository holding the fonds, preferably, but not necessarily [https://en.wikipedia.org/wiki/International_Standard_Identifier_for_Libraries_and_Related_Organizations ISIL]
 
|-
 
|-
 
| hasDigitalObject  
 
| hasDigitalObject  
 
| TRUE/FALSE
 
| TRUE/FALSE
 
|-
 
|-
−
| langMaterial
+
| numberOfDigitalObjects
−
| Language in which the result is created.
+
| Amount of digital objects available for the search result (is always 0 in case 'hasDigitalObject' = FALSE)
 
|-
 
|-
−
| language
+
| numberOfDigitalOjectsInDescendents
−
| Language of the description of the result.
+
| Amount of digital objects available for descendents of the search result (can be > 0 in case 'hasDigtalObject' = FALSE)
 +
|-
 +
| numberOfDescendents
 +
| Amount of descendents of the search result
 
|-
 
|-
 
| docType  
 
| docType  
−
| Type of archives describing document where the result is found : "Finding Aid", "Holdings Guide", "Source Guide" or "Descriptive Unit".
+
| Type of document in which the result is found: "Finding Aid", "Holdings Guide", "Source Guide" or "Descriptive Unit"
 +
|-
 +
| docTypeId
 +
| Acronym for the type of document: "fa" for "Finding Aid", "hg" for "Holdings Guide", "sg" for "Source Guide" or "du" for "Descriptive unit"
 
|-
 
|-
 
| level
 
| level
 
| Type of result: "archdesc" for highest level description or "clevel" for subordinate components
 
| Type of result: "archdesc" for highest level description or "clevel" for subordinate components
 
|-
 
|-
−
| fondsUnitId
+
| indexDate
−
| Identifier of the fonds provided by the repository.
+
| Date showing when the result was ingested/updated and indexed in the Archives Portal Europe (ie last change date)
 
|-
 
|-
−
| fondsUnitTitle
+
| unitId
−
| Title of the finding aid.
+
| Identifier of the result provided by the repository
 
|-
 
|-
−
| repository
+
| unitTitle
−
| Name of the repository holding the fonds
+
| Description of the result
 
|-
 
|-
−
| repositoryCode
+
| scopeContent
−
| Code of the repository holding the fonds. Preferably, but not necessarily [https://en.wikipedia.org/wiki/International_Standard_Identifier_for_Libraries_and_Related_Organizations ISIL].
+
| More descriptive information about the result
 
|-
 
|-
−
| country
+
| siblingPosition
−
| Name of the country where the repository is. In English.
+
| Position of the result in the order of children in the level beneath the descriptive unit of the identifier in the request
 +
|-
 +
| ancestorLevel
 +
| Position of the descriptive unit of the identifier in the request in the higher hierarchy of the document it belongs to 
 
|}
 
|}
  
 
[[Category:Technical_documentation]]
 
[[Category:Technical_documentation]]

Latest revision as of 14:44, 30 August 2017

Request url: https://api.archivesportaleurope.net/services/hierarchy/ead/{id}/ancestors. This service is a POST-request.

This hierarchy-service delivers a list of all archival descriptions in the path from root to {id} of an archival description in the hierarchy of finding aid, a holdings guide or a source guide. A web developer can use this service to create a tree-like presentation of a finding aid, holdings guide or source guide.




Request parameters

Only one request parameter is required: the internal APE identifier of the descriptive unit for which a list of higher level ancestors is needed.

On [base_url]/hierarchy/ead/{id}/ancestors, all the clevel descriptive units that are on the path from {id} to the root in the hierarchy of a finding aid, holdings guide or source guide are given.

N.B.: you can find the (internal APE) identifier of a descriptive unit (always starting with a "C") which is necessary for using this service via the /search/ead service

Response parameters

The response contains a list of the descriptions that were found, from the descriptive unit for which an identifier was provided up till the root of the finding aid, holding guide or source guide.

Empty Response example

{
  "totalResults": 0,
  "startIndex": 0,
  "totalPages": 0,
  "results": [
    {
      "id": "string",
      "findingAidTitle": "string",
      "findingAidNo": "string",
      "repository": "string",
      "country": "string",
      "language": "string",
      "langMaterial": "string",
      "unitDate": "string",
      "repositoryCode": "string",
      "hasDigitalObject": false,
      "numberOfDigitalObjects": 0,
      "numberOfDigitalObjectsInDescendents": 0,
      "numberOfDescendents": 0,
      "docType": "string",
      "docTypeId": "string",
      "level": "string",
      "indexDate": "string",
      "unitId": "string",
      "unitTitle": "string",
      "scopeContent": "string",
      "siblingPosition": 0,
      "ancestorLevel": 0
    }
  ]
}

Basic Response example

For identifier C376209320: 

{
  "totalResults": 2,
  "startIndex": 0,
  "totalPages": 1,
  "results": [
    {
      "id": "F1049165",
      "findingAidTitle": "Inventaris van de collectie archieven Strijdkrachten in Nederlands-Indië, (1938 - 1939) 1941 - 1957 [1960]",
      "findingAidNo": "2.13.132",
      "repository": "Nationaal Archief",
      "country": "NETHERLANDS",
      "language": "",
      "langMaterial": "",
      "unitDate": "1938-1960",
      "repositoryCode": "NL-HaNA",
      "hasDigitalObject": false,
      "numberOfDigitalObjects": 0,
      "numberOfDigitalObjectsInDescendents": 23297,
      "numberOfDescendents": 5627,
      "docType": "Finding Aid",
      "docTypeId": "fa",
      "level": "archdesc",
      "indexDate": "",
      "unitId": "2.13.132",
      "unitTitle": "Ministerie van Defensie: Strijdkrachten in Nederlands-Indië",
      "scopeContent": "In het archief zijn de onder meer opgenomen de archieven van het Hoofdkwartier van de Generale Staf in Nederlands-Indië (HKGS-NI) (1945-1950), de Centrale Militaire Inlichtingendienst (1941-1949), de Commandant \"7 December\" Divisie, de Adjudant-Generaal in Nederlands-Indië/Indonesië (1945-1952), de staven van de T t/m Z Brigade, de Compagnieën Aan- en Afvoertroepen, de Kwartiermeester-Generaal en het Afwikkelingscommando in Indonesië (1950-1951). Tenslotte bevat het archief ook een collectie onderdeelsverslagen van Koninklijke Landmacht en het KNIL. Daaronder bevinden zich ook verslagen van het Korps Speciale Troepen en Korps Militaire Politie/Koninklijke Marechaussee.  Inhoud Onderzoek toonde aan dat bij het Bureau Centraal Archievendepot (BCAD) van het Defensie, Archieven-, Registratie- en Informatiecentrum een aantal archieven aanwezig was die door militaire instanties/onderdelen gevormd waren in het voormalige Nederlands-Indië. In overleg met het Nationaal Archief is besloten om deze in de \"Collectie archieven Strijdkrachten in Nederlands-Indië, (1938-1939) 1941-1957 [1960]\" samen te brengen, te inventariseren en over te dragen aan het Nationaal Archief. Het betreft hier de volgende archieven: Beleidsterrein Operatiën: Hoofdkwartier van de Generale Staf in Nederlands-Indië, 1945 - 1950; Hoofdkwartier van de Generale Staf in Nederlands-Indië, Sectie Krijgsgeschiedenis, 1945 - 1949; Kabinet van de Legercommandant in Nederlands-Indië, 1945 - 1950; Netherlands Forces Intelligence Service/Centrale Militaire Inlichtingendienst, 1941 - 1949; Hoofdkwartier Militaire Luchtvaart van het KNIL, Kantoor Inlichtingen in Nederlands-Indië, (1938-1939) 1942 - 1950; Collectie verspreide archivalia van de strijdkrachten in Indonesië, speciaal Oost-Java, 1945 - 1949; Collectie archiefbescheiden van de Commandant \"7 December\" Divisie en de onder zijn bevel ressorterende onderdelen in Nederlands-Indië, 1945 - 1950; Staven van de T t/m Z-Brigade en de Staf Bataljon 2-13 Regiment Infanterie in Nederlands-Indië, [1945] 1946 - 1950; Collectie onderdeelsverslagen in Nederlands-Indië, 1945 - 1950; Bataljons behorende tot Regimenten Infanterie in Nederlands-Indië, 1945 - 1950; Compagnieën Aan- en Afvoertroepen, 1945 - 1950; 6, 10 en 14 Genie Veldcompagnie Indië, 1947 - 1950. Beleidsterrein Personeel: Korps Militaire Politie/Koninklijke Marechaussee KNIL, 1947 - 1951; Hoofdkwartier Adjudant-Generaal in Indonesië, 1945 - 1952; Afwikkelingscommando in Indonesië, 1950 - 1951; Hoofdkwartier Militaire Luchtvaart, Kantoor Personeel, 1945 - 1949; Hoofd van de Militaire Geneeskundige Dienst te Batavia, 1948 - 1949; Subsistentenbataljon, 1946 - 1951; Persoonlijk archief van reserve luitenant-kolonel mr. J.F. Scheers, 1946 - 1948, 1952 - 1957 [1960]. Beleidsterrein Materieel: Kwartiermeester-Generaal/Territorium Nieuw-Guinea, 1949; Kwartiermeester-Generaal/Legermaterieeldienst, 1947 - 1950; Kwartiermeester-Generaal/Assistent Directeur Leger Materieeldienst - 3, [1947] 1949; Commissie van Proefneming in Nederlands-Indië, 1946 - 1950. Het totaal van de collectie heeft een omvang van 125m.",
      "siblingPosition": 0,
      "ancestorLevel": 0
    },
    {
      "id": "C376208583",
      "findingAidTitle": "Inventaris van de collectie archieven Strijdkrachten in Nederlands-Indië, (1938 - 1939) 1941 - 1957 [1960]",
      "findingAidNo": "2.13.132",
      "repository": "Nationaal Archief",
      "country": "NETHERLANDS",
      "language": "",
      "langMaterial": "",
      "unitDate": "",
      "repositoryCode": "NL-HaNA",
      "hasDigitalObject": false,
      "numberOfDigitalObjects": 0,
      "numberOfDigitalObjectsInDescendents": 0,
      "numberOfDescendents": 831,
      "docType": "Descriptive Unit",
      "docTypeId": "du",
      "level": "clevel",
      "indexDate": "",
      "unitId": "2.13.132 - B",
      "unitTitle": "Beleidsterrein Personeel",
      "scopeContent": "",
      "siblingPosition": 2,
      "ancestorLevel": 1
    }
  ]
}

totalResults

The response parameter "totalResults" gives the number of results.

startIndex

The response parameter "startIndex" gives the number of the chunk you requested.

totalPages

The response parameter "totalPages" gives the number of chunks.

results

Enumeration of the results. A result could be a holdings guide, a source guide, a finding aid, or a descriptive unit (ie a sublevel component). They are all optional except "id".

id Internal APE identifier of the result
findingAidTitle Title of the finding aid, holdings guide or source guide
findingAidUnitId Identifier of the fonds provided by the repository
repository Name of the repository holding the fonds
country Name of the country where the repository is, in English
language Language of the description of the result
langMaterial Language in which the result is created
unitDate Date of creation of the result
repositoryCode Code of the repository holding the fonds, preferably, but not necessarily ISIL
hasDigitalObject TRUE/FALSE
numberOfDigitalObjects Amount of digital objects available for the search result (is always 0 in case 'hasDigitalObject' = FALSE)
numberOfDigitalOjectsInDescendents Amount of digital objects available for descendents of the search result (can be > 0 in case 'hasDigtalObject' = FALSE)
numberOfDescendents Amount of descendents of the search result
docType Type of document in which the result is found: "Finding Aid", "Holdings Guide", "Source Guide" or "Descriptive Unit"
docTypeId Acronym for the type of document: "fa" for "Finding Aid", "hg" for "Holdings Guide", "sg" for "Source Guide" or "du" for "Descriptive unit"
level Type of result: "archdesc" for highest level description or "clevel" for subordinate components
indexDate Date showing when the result was ingested/updated and indexed in the Archives Portal Europe (ie last change date)
unitId Identifier of the result provided by the repository
unitTitle Description of the result
scopeContent More descriptive information about the result
siblingPosition Position of the result in the order of children in the level beneath the descriptive unit of the identifier in the request
ancestorLevel Position of the descriptive unit of the identifier in the request in the higher hierarchy of the document it belongs to
Retrieved from "https://wiki-deprecated.archivesportaleurope.net/index.php?title=hierarchyEadAncestors&oldid=1681"