Documentation
1. Schéma global
Introduction
- Requête
- Réponse
2. API CQL
Recherche
- Requête
- Réponse
Recherche des valeurs distinctes
- Requête
- Réponse
3. API SCAPIN
Informations générales
- Requête
- Réponse
Equipe
- Requête
- Réponse
Producteurs
- Requête
- Réponse
Documents
- Requête
- Réponse
Tournées
- Requête
- Réponse
APIs : accès open data
Le projet Scapin, plus qu'un moteur de recherche
Comme son nom l'indique, le projet Scapin est centré sur le concept d'API. En effet, son objectif principal est de donner accès à ses données de la mémoire des arts de scène non seulement via un classique search engine, mais aussi directement via diverses APIs.
Contrairement aux moteurs de recherche, les APIs fournissent via des urls spécifiques les données dans un format ouvert, qui n'est pas destiné à la lecture par un être humain, mais par une autre application informatique, bureautique ou web. Tout développeur d'applications desktop ou mobile ou de websites, après avoir enregistré son projet auprès de Scapin, peut donc y utiliser les données en question, au format et dans le design de son choix.
1. Schéma global
Schéma unique, usages multiples
Toutes les APIs nécessaires pour accéder aux données de la mémoire des arts de scène de SCAPIN sont interrogeables via des URLs au schéma identique. Les pages suivantes les exposent en détails.
Structure de la requête :
[site]/[nom]/[service]/[accès]/[méthode]/[paramètre unique]?[paramètres multiples]
[site]
[nom]
Nom de l'API à laquelle on désire accéder. Concrètement, le projet SCAPIN utilise deux APIs : CQL pour les recherches et Scapin proprement dite pour toutes les informations détaillant un spectacle.
[service]
Nom du WebService (extension .svc) auquel on désire accéder.
[accès]
Peut prendre deux valeurs : anon, pour les accès publics, ou auth, pour les accès avec identification préalable (réservés aux partenaires du projet).
[méthode]
Seules les méthodes de lecture de données (commençant par Get) sont accessibles via les accès publics, tandis que les accès avec identification pourront recourir aux méthodes d'écriture de données (Post, Put et Delete).
[paramètre unique]
Les paramètres uniques - typiquement, les IDs uniques de spectacles - sont simplement précédés d'un "/".
[paramètres multiples]
Les méthodes qui attendent plus d'un paramètres sont suivies d'un "?" ; les paramètres eux-mêmes, sous la forme "nom=valeur", sont séparés par "&".
Request Header requis
nom
"AppName"
valeur
Nom de l'application autorisée à utiliser les données de Scapin. Cette autorisation peut être obtenue gratuitement, sur simple demande.
2. API CQL
Recherche
Requête
Structure de la requête :
https://api.aml-cfwb.be/cql/sru.svc/anon/get?db=scapin.s&q=[requête CQL]&resultFields=[informations renvoyées]&sortBy=[tri]&page=[page de résultats]&rows=[nb de résultats par page]
[requête CQL]
Requête selon l'implémentation CQL de Scapin, qui permet, via le protocole SRU, des recherches simples "plein texte", mais aussi multi-critères combinatoires (avec opérateurs AND, OR, NOT, PROX). Les partenaires référencés de SCAPIN ont accès à Phormion, dont l'interface de recherche permet de générer toutes les équations CQL supportées.
[informations renvoyées]
Permet de décider quelles informations doivent être présentes dans les résultats. Ces informations sont identifiées via des abréviations (cf. table ci-dessous reprenant les principaux) séparées par des ",". Pour de meilleurs performances, il est conseillé de limiter les informations à celles nécessaires à l'usage prévu des résultats de recherche. L'ensemble des informations liées à un spectacle sont accessibles via l'API Scapin dédiée (voir ci-dessous).
[tri]
Permet de décider sur quelle information sont triés les résultats. Tri croissant uniquement sur une seule information, via son abréviation. Ce paramètre est sans effet si l'information choisie pour le tri n'est pas présente dans les informations renvoyées.
[page de résultats]
Facultatif ; défaut : 1.
[nb de résultats par page]
Facultatif ; défaut : 1000 ; max. : 1000.
Exemples
https://api.aml-cfwb.be/cql/sru.svc/anon/get?db=scapin.s&format=json&q=(pelléas national)&sortBy=s.a&resultFields=s.a,t,p.d : renvoie tous les spectacles qui contiennent les mots "pelléas" et "national" dans leur description
https://api.aml-cfwb.be/cql/sru.svc/anon/get?db=scapin.s&format=json&q=(t=roméo*)&sortBy=s.a&resultFields=s.a,t,p.d : renvoie tous les spectacles dont le titre commence par "roméo"
https://api.aml-cfwb.be/cql/sru.svc/anon/get?db=scapin.s&format=json&q=(p.d=Théâtre Royal du Parc) AND (s.a=2022-2023)&sortBy=s.a&resultFields=s.a,t,p.d : renvoie tous les spectacles produits par le Théâtre Royal du Parc durant la saison 2022-2023
Sans Request Header, réponse limitée à 10 résultats.
Réponse
| Intitulé | Type | Commentaire | Abréviation |
|---|---|---|---|
| ID | int | Identifiant unique du spectacle ; max. 2^63 | id |
| Texte1 | string | Titre ; max. 255 ca | t |
| Texte2 | string | Producteurs, séparés par " - ", triés par implication (principal, secondaire, soutien) | p.d |
| Texte3 | string | Membres créatifs, format "Fonction: Prénom Nom", séparés par " - ", triés par fonction (auteur, d'après, conception, traduction, adaptation, écriture, mise en scène, mise en voix, scénographie, chorégraphie, compositeur) | e.cr |
| Texte4 | string | Saison ; format AAAA-AAAA | s.a |
| Texte5 | string | Nombre de représentatations total, toutes saisons confondues | r.nbt |
| Texte6 | string | Saison de la dernière reprise du spectacle ; format AAAA-AAAA | s.der |
| Texte10 | string | Date première ; format AAAA/MM/JJ ; première représentation toutes saisons confondues | d.p |
| Texte11 | string | Date reprise ; format AAAA/MM/JJ ; première représentation pour la saison en cours | d.r |
| Texte13 | string | Nombre de représentations durant la saison | r.nbs |
Recherche des valeurs distinctes
Requête
Structure de la requête :
https://api.aml-cfwb.be/cql/sru.svc/anon/getdistinct?db=scapin.s&q=[requête CQL]&field=[information visée]
[requête CQL]
Requête selon l'implémentation CQL de Scapin, qui permet, via le protocole SRU, des recherches simples "plein texte", mais aussi multi-critères combinatoires (avec opérateurs AND, OR, NOT, PROX). Les partenaires référencés de SCAPIN ont accès à Phormion, dont l'interface de recherche permet de générer toutes les équations CQL supportées.
[information visée]
Information dont sont attendues les valeurs distinctes dans les résultats de la requête. L'information est identifiée par son abréviation.
Exemple
https://api.aml-cfwb.be/cql/sru.svc/anon/getdistinct?db=scapin.s&q=(p.d=Théâtre du Papyrus)&field=s.a : renvoie les saisons distinctes durant lesquelles le Théâtre du Papyrus a produit des spectacles
Sans Request Header, réponse vide.
Réponse
| Intitulé | Type | Commentaire |
|---|---|---|
| Field | string | Valeur distincte de l'information choisie. |
| DistinctCount | int | Nombre d'occurrences de la valeur distincte parmi les résultats de la requête CQL. |
3. API SCAPIN
Informations générales
Requête
Structure de la requête :
https://api.aml-cfwb.be/scapin/spectacle.svc/anon/get/[IDspectacle]
[IDspectacle]
L'identifiant unique du spectacle, généralement obtenu après une requête.
Réponse
| Intitulé | Type | Commentaire |
|---|---|---|
| ID | int | Identifiant unique du spectacle ; max. 2^63 |
| Titre | string | Max. 255 ca |
| ComplementTitre | string | Nb de ca illimité |
| CommentairesResume | string | Nb de ca illimité |
| Saison | string | Format AAAA-AAAA |
| Aides | string | Nb de ca illimité |
| Notes | string | Nb de ca illimité |
| LieuPremiere | string | Max. 255 ca |
| DatePremiere | string | Format AAAA/MM/JJ |
| LieuReprise | string | Max. 255 ca |
| DateReprise | string | Format AAAA/MM/JJ |
| NotesCachees | string | Nb de ca illimité |
| Duree | string | Nb de ca illimité |
| Tags | string | Tags, séparés par " - " |
| SerieID | int | Si > 0, identifiant unique de la série à laquelle appartient le spectacle ; max. 2^63 |
Equipe
Requête
Structure de la requête :
https://api.aml-cfwb.be/scapin/spectacle.svc/anon/getequipe/[IDspectacle]
[IDspectacle]
L'identifiant unique du spectacle, généralement obtenu après une requête.
Sans Request Header, réponse limitée à 5 membres.
Réponse
| Intitulé | Type | Commentaire |
|---|---|---|
| ID | int | Identifiant unique de la ligne ; max. 2^63 |
| TempSpectaclesID | int | Identifiant unique du spectacle ; max. 2^63 |
| Classement | int | Max. 2^15 ; défaut : 0 |
| NomPrenom | string | Format "Nom, Prénom" ; max. 512 ca |
| Nom | string | Max. 255ca |
| Prenom | string | Max. 255ca |
| MembreEquipeID | int | Max. 2^63 |
| ISNI | string | 16ca ; International Standard Name Identifier |
| MentionLibre | string | Max. 255ca |
| Fonction | string | Max. 255 ca |
| FonctionID | int | Max. 2^31 |
| FonctionLibre | string | Max. 255ca |
| Interprete | bool | 1 si sur scène ; 0 pour toutes les autres fonctions |
| Notes | string | Nb de ca illimité |
| RoleDansSpectacle | string | Max. 255 ca |
| RolePartage | int | Max. 255 ; défaut : 0 ; identique pour tous les membres qui ont partagé le même rôle |
Producteurs
Requête
Structure de la requête :
https://api.aml-cfwb.be/scapin/spectacle.svc/anon/getproduction/[IDspectacle]
[IDspectacle]
L'identifiant unique du spectacle, généralement obtenu après une requête.
Réponse
| Intitulé | Type | Commentaire |
|---|---|---|
| ID | int | Identifiant unique de la ligne ; max. 2^63 |
| TempSpectaclesID | int | Identifiant unique du spectacle ; max. 2^63 |
| DenominationOrganisme | string | Max. 255 ca |
| OrganismeID | int | Max. 2^63 |
| Implication | int | 0 : principal ; 1 : secondaire ; 2 : soutien |
| Notes | string | Nb de ca illimité |
Documents
Requête
Structure de la requête :
https://api.aml-cfwb.be/scapin/spectacle.svc/anon/getdocs/[IDspectacle]?withUrl=[avec url]&withSerie=[avec liens sériels]
[IDspectacle]
L'identifiant unique du spectacle, généralement obtenu après une requête.
[avec url]
Valeur : yes/no ; facultatif ; défaut : yes. Si "yes", renvoie tous les fichiers numériques liés aux cotes ; si "no", renvoie toutes les cotes liées.
[avec liens sériels]
Valeur : 0/1 ; facultatif ; défaut : 0. Si 1, renvoie aussi les fichiers numériques liés aux cotes liées aux spectacles de la même série (à l'exclusion des affiches).
Sans Request Header, réponse limitée à la première cote.
Réponse
| Intitulé | Type | Commentaire |
|---|---|---|
| ID | int | Identifiant unique de la ligne ; max. 2^63 |
| TempSpectaclesID | int | Identifiant unique du spectacle ; max. 2^63 |
| Notes | string | Nb de ca illimité |
| Cote | string | Max. 255 ca |
| Url | string | Url complet du fichier numérique lié |
| Extension | string | Extension du fichier numérique, avec le point |
| Support | string | Max. 50 ca ; désigne le support de la cote liée (photo, affiche, livre, vidéo...) ; si 'permalink', l'url renvoie à une page web |
| IsAffiche | bool | 1 pour la cote désignée comme l'affiche principale du spectacle ; 0 pour les autres |
| IsImage | bool | 1 si fichier image (jpg, png...) ; 0 pour les autres |
| AVPNom | string | Spécial vidéo : nom de la plateforme (Youtube, Viméo, DailyMotion) |
| AVPID | string | Spécial vidéo : identifiant unique de la vidéo spécifique à la plateforme |
Tournées
Requête
Structure de la requête :
https://api.aml-cfwb.be/scapin/spectacle.svc/anon/gettournee/[IDspectacle]
[IDspectacle]
L'identifiant unique du spectacle, généralement obtenu après une requête.
Sans Request Header, réponse limitée à la première ligne.
Réponse
| Intitulé | Type | Commentaire |
|---|---|---|
| ID | int | Identifiant unique de la ligne ; max. 2^63 |
| TempSpectaclesID | int | Identifiant unique du spectacle ; max. 2^63 |
| Rang | int | Classement de la ligne ; max. 2^15 |
| Nombre | int | Nombre de représentations pour le groupe défini par la ligne ; max. 2^15 |
| Dates | string | Texte libre, non formatté ; max. 255ca |
| Salle | string | Max. 255ca |
| Lieu | string | Max. 255ca |
| Villes | string | Noms des villes en français séparés par " - " |
| Pays | string | Nom du pays en français ; max. 50ca |
| PaysISO | string | Code ISO 3166-2 du pays |
| Cadre | string | Max. 255ca |
| Organisateurs | string | Organisateurs séparés par " - " |
| Notes | string | Nb de ca illimité |