Digital Muret & Collection Muret

Utiliser l'API du Digital Muret

Afin de faciliter la réutilisation des données du Digital Muret, le site dispose d’une API (Application Programming Interface ou Interface de Programmation).

Cette API permet d’interroger et de télécharger les données du site Digital Muret. Il s'agit de l'API par défaut de Omeka-S, le CMS avec lequel Digital Muret a été développé.

Plan de la page

• URL racine de l'API
• Formuler une requête simple
• Formuler une requête complexe à un seul critère
• Formuler une requête complexe à plusieurs critères
• Intérpréter le résultat de la requête (convertir le JSON en CSV)
• Exemples de requêtes

URL racine de l'API

L’adresse de l’API commencera toujours avec le préfixe : https://digitalmuret.inha.fr/api/

Cette adresse vous affichera un message d’erreur :

«The API request resource… Type \"NULL\" given. »

Il faut donc construire une requête pour interroger les données.

Formuler une requête simple

Toutes les données (planches et objets, tout confondu) : https://digitalmuret.inha.fr/api/items

Changer le nombre d'objets à afficher

La page du résultat de recherche affichera 200 objets au format json (en effet, par défaut, le site n’affiche pas plus de 200 résultats de recherche)

Si vous souhaitez afficher davantage de résultats, vous pouvez augmenter les nombres d’objets affichés avec : per_page=500 (il faut le lier à l’adresse avec un « ? »), comme ceci : https://digitalmuret.inha.fr/api/items?per_page=500

Vous pouvez ainsi afficher autant d’objets que vous souhaitez : https://digitalmuret.inha.fr/api/items?per_page=2000

Attention, plus le nombre d’objets à afficher est élevé, plus la page sera longue à charger.

Formuler une requête complexe

Syntaxe générale

L’interrogation de l’API avec des requêtes complexes nécessite le respect d’une syntaxe précise :

• property[0][property] -> le code du champ à interroger
• property[0][type] -> le type de recherche à effectuer
• property[0][text] -> la valeur recherchée

Les éléments doivent être liés par des esperluettes (« & ») ; donc :

property[0][property]={code du champ à interroger}&property[0][type]={type de recherche}&property[0][text]={valeur recherchée}

Les valeurs à utiliser dans la requête

Pour formuler la requête, il faut donc indiquer : le code du champ à interroger (property), le type de recherche à effectuer (type), et la valeur à rechercher (text).

Dans Digital Muret, les notices objets et les notices planches étant construites différement, il faudra utiliser les bon codes de propriété pour interroger l'un des deux types.

Pour les notices « Objets », les codes des propriétés sont les suivants :

Pour les notices « Planches », les codes des propriétés sont les suivants :

Types de recherches

Sur chaque propriété, il est possible de faire des recherches de types différents. Prenons comme exemple une recherche qui porterait sur la valeur textuelle « fleur ». Il est possible de typer la recherche ainsi :

• eq: correspondance exacte (résultat : champs qui contient « fleur » et non « fleuri » ou « fleurs »)
• neq: « non correspondance » exacte (résultat : champs qui contient « fleuri », « fleurs » et non ceux qui contient « fleur »)
• in: contient (résultat : champs qui contient « fleur », « fleuri » et « fleurs »)
• nin: ne contient pas (résultat : champs qui ne contient ni « fleur », ni « fleuri », ni « fleurs »)
• ex: le champ n’est pas vide (résultat : tous les champs ayants au moins une valeur)
• nex: le champ est vide (résultat : tous les champs ayants pas de valeurs)

Valeur recherchée

Enfin, il faut renseigner la valeur textuelle recherchée. Par exemple : bronze, fleur, bijou

Pour connaître la liste des termes employés dans Digital Muret, il faut se reporter aux index, disponibles à partir de cette page.

Construire sa requête

Vous pouvez maintenant construire votre requête, en ajoutant la formule au préfixe de l’URL :

https://digitalmuret.inha.fr/api/items?property[0][property]={code du champ à interroger}&property[0][type]={type de recherche}&property[0][text]={valeur recherchée}

et en substituant les valeurs dans des {} avec des bonnes valeurs,  ici une recherche sur les objets ayant pour Matériau (653) la valeur exacte (eq) la valeur textuelle "bronze" :

https://digitalmuret.inha.fr/api/items?property[0][property]=653&property[0][type]=eq&property[0][text]=bronze

NB : Avant chaque élément il faut toujours mettre une esperluette « & » pour séparer les différentes parties de la requête :

https://digitalmuret.inha.fr/api/items?property[0][property]=653&property[0][type]=eq&property[0][text]=bronze

La requête nous repondera avec les 200 éléments par default ; si nous souhaitons en avoir plus il faut toujours ajouter  &per_page={numéro} ex. &per_page=500

Formuler une requête complexe à plusieurs critères

Nous pouvons aussi effectuer des recherches encore plus complexes, en ajoutant d’autres éléments à la requête ; si vous souhaitez interroger tous les bijoux qui sont fait en or.

Il vous faudra concaténer deux requêtes :
property[0][property]=8&property[0][type]=eq&property[0][text]=bijou
et
property[0][property]=653&property[0][type]=eq&property[0][text]=or

Pour faire cela, le numéro de la deuxième requête sera augmenté de 1, passant donc de 0 à 1 :
property[0][property]=8&property[0][type]=eq&property[0][text]=bijou
et
property[1][property]=653&property[1][type]=eq&property[1][text]=or

Il faut également lier les deux requêtes, en utilisant une  « jointure », donc ajouter property[1][joiner]={« and » ou « or »} entre la première et la deuxième requête (dans ce cas-là vous utiliserez le « and » parce-que vous souhaitez avoir seulement les bijoux en or !) :
property[0][property]=8&property[0][type]=eq&property[0][text]=bijou
property[1][joiner]=and
property[1][property]=653&property[1] [type]=eq&property[1] [text]=or

Donc :
property[0][property]=8&property[0][type]=eq&property[0][text]=bijou&property[1][joiner]=and&property[1][property]=653&property[1] [type]=eq&property[1] [text]=or

Ce qui donne :

https://digitalmuret.inha.fr/api/items?property[0][property]=8&property[0][type]=eq&property[0][text]=bijou&property[1][joiner]=and&property[1][property]=653&property[1][type]=eq&property[1][text]=or

Comme déjà vu, pour augmenter les nombres d’objets, il faut ajouter &per_page={numéro}

https://digitalmuret.inha.fr/api/items?property[0][property]=8&property[0][type]=eq&property[0][text]=bijou&property[1][joiner]=and&property[1][property]=653&property[1][type]=eq&property[1][text]=or&per_page=1000

Si tout s’est bien passé, vous devriez avoir 243 résultats (NB : le compteur commence par 0, donc le dernier résultat sera numéroté 242).

Vous pouvez ajouter autant de critères de recherche que vous le souhaitez.

Intérpréter le résultat de la requête (convertir le JSON en CSV)

Le résultat de votre requête vous est renvoyé au format JSON, qui n'est pas très déchiffrable pour un humain.

Si vous souhaitez voir votre résultat affiché dans un « tableur » vous pouvez utiliser un outil en ligne pour la conversion du json en csv :
http://convertcsv.com/json-to-csv.htm

Il faut tout simplement copier TOUT le texte présent dans la page de votre requête :
[{"@context":"https:\/\/digitalmuret.inha.fr\/api-context","@id":"https:\/\/digitalmuret.inha.fr\/api\/items\/18631","@type":["o:Item","dctype:PhysicalObject"],"o:id":18631,"o:is_public":true,"o:owner":{"@id":"https:\/\/digitalmuret.inha.fr\/api\/users\/5","o:id":5},"o:resource_class":{"@id":"https:\/\/digitalmuret.inha.fr\/api\/resource_classes\/32","o:id":32},"o:resource_template":{"@id":"https:\/\/digitalmuret.inha.fr\/api\/resource_templates\/12","o:id":12},"o:thumbnail":null,"o:created":{"@value":"2019-04-11T07:22:46+00:00","@type"……

(NB : ne copiez pas te texte ci-dessus, il s’agit d’un exemple coupé, donc il ne marchera pas !)

et le coller dans la page du « converter » dans la fenêtre :
Step 1: Select your input
Enter Data

Ensuite cliquez sur « Convert JSON to CSV »

Vous pouvez télécharger votre tableau en cliquant sur « Download Result »