Theatre.info met à disposition une API permettant d'obtenir des informations sur les spectacles et textes associés qui se trouvent à l'affiche. Si vous ne possédez pas encore de clé et désirez en obtenir une, veuillez faire votre demande en utilisant ce formulaire.
Une fois créée, votre clé sera disponible dans votre compte utilisateur, qu'il vous faudra donc avoir créé préalablement à votre demande via le formulaire.
Lorsque vous êtes identifié sur le site et que vous avez un accès autorisé à l'API, vous avez également des informations supplémentaires disponibles dans une fiche spectacle, une fiche texte, une fiche structure et une fiche personne : l'identifiant d'objet que vous pouvez utiliser ensuite comme critère ou filtre optionnel dans votre requête sur l'API.
Les identifiants d'objet sont définis ainsi, nnn
représentant un numéro unique pour le type d'objet :
- pour un spectacle :
show:nnn
- pour un texte :
text:nnn
- pour une structure (éditeur, producteur, lieu, soutien) :
structure:nnn
- pour une personne (auteur·e, metteur·e en scène...) :
person:nnn
Le principe d'accès aux données est ensuite le suivant :
https://theatre.info/api/point d'entrée/critère[filtres optionnels]?api-key=votre clé
Les données sont renvoyées au format JSON.
Les points d'entrée sont répartis en 2 familles : spectacles et textes.
Généralement, un seul critère est utilisé, mais il est possible dans certains cas (détail plus loin) d'utiliser un deuxième critère. Par exemple, filtrer les textes à l'affiche dans un lieu et pour un auteur en particulier.
Filtres optionnels
Selon le contexte (point d'entrée), les filtres optionnels ne sont pas tous disponibles.
Les filtres sont définis entre crochets []
dans la requête et séparés par une virgule s'il y en a plusieurs : [filtre1=valeur,filtre2=valeur]
Date de début
Description : la date de début du calendrier des résultats. Par défaut si filtre non défini : c'est la date du jour qui est utilisée.
Filtre : from
Valeur : une date au format aaaa-mm-jj
Date de fin
Description : la date de fin du calendrier des résultats. Par défaut si filtre non défini : il n'y a pas de limite dans le futur.
Filtre : to
Valeur : une date au format aaaa-mm-jj
Zone de localisation
Description : permet de restreindre les résultats à une région française ou un pays. Par défaut si filtre non défini : aucune restriction de localisation.
Filtre : area
Valeur : un numéro (liste ci-dessous) pour une région ou un code ISO 3166-1 alpha-2 pour un pays.
Liste des numéros de région : Grand-Est = 1
, Nouvelle-Aquitaine = 2
, Rhône-Alpes = 3
, Bourgogne Franche-Comté = 4
, Bretagne = 5
, Centre-Val de Loire = 6
, Corse = 7
, Île-de-France = 8
, Occitanie = 9
, Hauts-de-France = 10
, Normandie = 11
, Pays de la Loire = 12
, Provence-Alpes-Côte d'Azur = 13
, Guadeloupe = 14
, Guyane = 15
, Martinique = 16
, Mayotte = 17
, La Réunion = 18
Rôle
Description : permet dans certains cas de préciser le rôle de la personne utilisée en 2ème critère de filtre. Inutile et non pris en compte si pas de 2ème critère.
Filtre : role
Valeur : author
pour l'auteur d'un texte, director
pour une personne de la direction du spectacle
Entrée spectacles
Les résultats ne comportent aucune mention de texte(s) associé(s). Cela permet donc de récupérer tous les spectacles à l'affiche, qu'ils s'appuient sur un texte édité ou non.
Un spectacle précis
Point d'entrée : spectacles/spectacle-affiche
Critère : show:nnn
Filtres optionnels : from
, to
, area
Exemples de requête :
Toutes les représentations d'un spectacle donné à partir d'aujourd'hui :https://theatre.info/api/spectacles/spectacle-affiche/show:nnn?api-key=XXX
Même résultat, mais filtré sur la France uniquement :https://theatre.info/api/spectacles/spectacle-affiche/show:nnn[area=FR]?api-key=XXX
Structure du résultat
title
= titre du spectacleobject
= objet API du spectacle (show:nnn
)permanent_url
= URL du spectacle sur theatre.infodirectors {
= de 1 à plusieurs personnes"nnn = id": {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
}
poster
= URL de l'image du spectacle sur theatre.info au format paysage 300×200poster_crop
= URL de l'image du spectacle sur theatre.info au format carré 100×100 (découpage automatique)start
= date globale de début (toutes les représentations) auformat aaaa-mm-jj
end
= date globale de fin (toutes les représentations) au formataaaa-mm-jj
ounull
si date uniquestart_end
= dates globale de début et fin au formatjj moi. > jj moi. aaaa
oujj moi. aaaa
(si date unique)schedules [
= 1 ou plusieurs représentations (représentation = dates + lieu){
start
= date de début au format aaaa-mm-jjend
= date de fin au format aaaa-mm-jj ou null si date uniquestart_end
= dates de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)dates [
= 1 ou plusieurs datesaaaa-mm-jj
]
city
= villezipcode
= code postalcountry
= code du pays sur 2 lettresplace {
= lieu de la représentationname
= nom de la structure/théâtreobject
= objet API de la structure (structure:nnn
)permanent_url
= URL de la structure sur theatre.infogeocode {
= coordonnées gps du lieux
= longitudey
= latitude}
}
}
]
Les spectacles à l'affiche d'un lieu
Point d'entrée : spectacles/affiche-lieu
Critère : structure:nnn
Critère supplémentaire facultatif : person:nnn
Filtres optionnels : from
, to
Exemples de requête :
Toutes les représentations d'un lieu donné à partir d'aujourd'hui :https://theatre.info/api/spectacles/affiche-lieu/structure:nnn?api-key=XXX
Même résultat, mais limité à une personne précise de la direction de spectacle, depuis aujourd'hui jusqu'à une date définie :https://theatre.info/api/spectacles/affiche-lieu/structure:nnn,person:nnn[to=2025-12-12]?api-key=XXX
Structure du résultat
[
= 0 ou plusieurs spectaclestitle
= titre du spectacleobject
= objet API du spectacle (show:nnn
)permanent_url
= URL du spectacle sur theatre.infodirectors {
= de 1 à plusieurs personnes"nnn = id": {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
}
poster
= URL de l'image du spectacle sur theatre.info au format paysage 300×200poster_crop
= URL de l'image du spectacle sur theatre.info au format carré 100×100 (découpage automatique)start
= date globale de début (toutes les représentations) auformat aaaa-mm-jj
end
= date globale de fin (toutes les représentations) au formataaaa-mm-jj
ounull
si date uniquestart_end
= dates globale de début et fin au formatjj moi. > jj moi. aaaa
oujj moi. aaaa
(si date unique)schedules [
= 1 ou plusieurs représentations (représentation = dates){
start
= date de début au format aaaa-mm-jjend
= date de fin au format aaaa-mm-jj ou null si date uniquestart_end
= dates de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)dates [
= 1 ou plusieurs datesaaaa-mm-jj
]
}
]
]
Les spectacles à l'affiche liés à une structure producteur/coproducteur
Point d'entrée : spectacles/affiche-production
Critère : structure:nnn
Critère supplémentaire facultatif : person:nnn
Filtres optionnels : from
, to
, area
Exemples de requête :
Toutes les représentations produites/coproduites par une structure donnée à partir d'aujourd'hui :https://theatre.info/api/spectacles/affiche-production/structure:nnn?api-key=XXX
Même résultat, mais filtré sur la France uniquement, limité à une personne précise de la direction de spectacle, depuis aujourd'hui jusqu'à une date définie :https://theatre.info/api/spectacles/affiche-production/structure:nnn,person:nnn[to=2025-12-12,area=FR]?api-key=XXX
Structure du résultat
[
= 0 ou plusieurs spectaclestitle
= titre du spectacleobject
= objet API du spectacle (show:nnn
)permanent_url
= URL du spectacle sur theatre.infodirectors {
= de 1 à plusieurs personnes"nnn = id": {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
}
poster
= URL de l'image du spectacle sur theatre.info au format paysage 300×200poster_crop
= URL de l'image du spectacle sur theatre.info au format carré 100×100 (découpage automatique)start
= date globale de début (toutes les représentations) auformat aaaa-mm-jj
end
= date globale de fin (toutes les représentations) au formataaaa-mm-jj
ounull
si date uniquestart_end
= dates globale de début et fin au formatjj moi. > jj moi. aaaa
oujj moi. aaaa
(si date unique)schedules [
= 1 ou plusieurs représentations (représentation = dates){
start
= date de début au format aaaa-mm-jjend
= date de fin au format aaaa-mm-jj ou null si date uniquestart_end
= dates de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)dates [
= 1 ou plusieurs datesaaaa-mm-jj
]
city
= villezipcode
= code postalcountry
= code du pays sur 2 lettresplace {
= lieu de la représentationname
= nom de la structure/théâtreobject
= objet API de la structure (structure:nnn
)permanent_url
= URL de la structure sur theatre.infogeocode {
= coordonnées gps du lieux
= longitudey
= latitude}
}
}
]
]
Les spectacles à l'affiche soutenus par une structure
Point d'entrée : spectacles/affiche-soutien
Critère : structure:nnn
Critère supplémentaire facultatif : person:nnn
Filtres optionnels : from
, to
, area
Exemples de requête :
Toutes les représentations soutenues par une structure donnée à partir d'aujourd'hui :https://theatre.info/api/spectacles/affiche-soutien/structure:nnn?api-key=XXX
Même résultat, mais filtré sur la France uniquement, et limité à une personne précise de la direction de spectacle :https://theatre.info/api/spectacles/affiche-soutien/structure:nnn,person:nnn[area=FR]?api-key=XXX
Structure du résultat
Le résultat possède la même structure que celui généré pour les spectacles liés à un producteur.
Dans le cas où l'utilisateur API possède également une fonction supplémentaire "école", les informations suivantes sont intégrées dans le résultat, pour chaque spectacle :
[
= 0 ou plusieurs spectacles ...distribution [
= 0 ou plusieurs personnes ajoutées dans un champ distribution dans la fiche spectacle, accessible à la fonction école{
person {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
role
= fonction de la personne dans la distribution (comédien, régisseur...)comment
= un commentaire (texte court) ounull
}
]
]
Entrée Textes
L'entrée textes permet de lister les spectacles liés à des textes édités. Elle possède donc dans le résultat une information spectacle et une information texte.
Un texte précis
Point d'entrée : textes/texte-affiche
Critère : text:nnn
Filtres optionnels : from
, to
, area
Exemples de requête :
Toutes les représentations d'un texte donné à partir d'aujourd'hui :https://theatre.info/api/textes/texte-affiche/text:nnn?api-key=XXX
Même résultat, mais filtré sur la France uniquement :https://theatre.info/api/textes/texte-affiche/text:nnn[area=FR]?api-key=XXX
Structure du résultat
{
text {
= informations du textetitle
= titre du texte sur theatre.infoobject
= objet API du texte (text:nnn
)permanent_url
= URL du texte sur theatre.infoean
= code EAN du texteposter
= URL de l'image du texte sur theatre.info au format portrait 240×360publisher_url
= URL du texte sur le site de l'éditeur ounull
authors {
= de 1 à plusieurs personnes"nnn = id": {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
}
}
shows [
= 1 ou plusieurs spectacles{
... voir le schéma du résultat d'un spectacle précis ...}
]
}
Les textes à l'affiche d'un lieu
Point d'entrée : textes/affiche-lieu
Critère : structure:nnn
Critère supplémentaire facultatif : person:nnn
Filtres optionnels : from
, to
, role
(défaut=director)
Exemples de requête :
Toutes les représentations d'un lieu donné à partir d'aujourd'hui :https://theatre.info/api/textes/affiche-lieu/structure:nnn?api-key=XXX
Même résultat, mais limité à une personne précise de la direction de spectacle, depuis aujourd'hui jusqu'à une date définie :https://theatre.info/api/textes/affiche-lieu/structure:nnn,person:nnn[to=2025-12-12,role=director]?api-key=XXX
Structure du résultat
[
= 0 ou plusieurs spectaclestitle
= titre du spectacleobject
= objet API du spectacle (show:nnn
)permanent_url
= URL du spectacle sur theatre.infodirectors {
= de 1 à plusieurs personnes"nnn = id": {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
}
poster
= URL de l'image du spectacle sur theatre.info au format paysage 300×200poster_crop
= URL de l'image du spectacle sur theatre.info au format carré 100×100 (découpage automatique)start
= date globale de début (toutes les représentations) auformat aaaa-mm-jj
end
= date globale de fin (toutes les représentations) au formataaaa-mm-jj
ounull
si date uniquestart_end
= dates globale de début et fin au formatjj moi. > jj moi. aaaa
oujj moi. aaaa
(si date unique)schedules [
= 1 ou plusieurs représentations (représentation = dates){
start
= date de début au format aaaa-mm-jjend
= date de fin au format aaaa-mm-jj ou null si date uniquestart_end
= dates de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)dates [
= 1 ou plusieurs datesaaaa-mm-jj
]
}
]
texts {
= 1 ou plusieurs textes associés au spectacle"nnn EAN": {
title
= titre du texte sur theatre.infoobject
= objet API du texte (text:nnn
)permanent_url
= URL du texte sur theatre.infoean
= code EAN du texteposter
= URL de l'image du texte sur theatre.info au format portrait 240×360publisher_url
= URL du texte sur le site de l'éditeur ounull
authors {
= de 1 à plusieurs personnes"nnn = id": {
lastname
= nom de famillefirstname
= prénom (peut être vide)object
= objet API de la personne (person:nnn
)permanent_url
= URL de la personne sur theatre.info}
}
}
}
]
Les textes associés à des spectacles à l'affiche liés à une structure producteur/coproducteur
Point d'entrée : textes/affiche-production
Critère : structure:nnn
Critère supplémentaire facultatif : person:nnn
Filtres optionnels : from
, to
, area
, role
(défaut=director)
Exemples de requête :
Toutes les représentations produites/coproduites par une structure donnée à partir d'aujourd'hui :https://theatre.info/api/textes/affiche-production/structure:nnn?api-key=XXX
Même résultat, mais filtré sur la France uniquement, limité à une personne précise de la direction de spectacle, depuis aujourd'hui jusqu'à une date définie :https://theatre.info/api/textes/affiche-production/structure:nnn,person:nnn[to=2025-12-12,area=FR]?api-key=XXX
Structure du résultat
Identique à la requête précédente avec la localisation en plus.
[
= 0 ou plusieurs spectaclestitle
= titre du spectacle ...schedules [
= 1 ou plusieurs représentations (représentation = dates){
...city
= villezipcode
= code postalcountry
= code du pays sur 2 lettresplace {
= lieu de la représentationname
= nom de la structure/théâtreobject
= objet API de la structure (structure:nnn
)permanent_url
= URL de la structure sur theatre.infogeocode {
= coordonnées gps du lieux
= longitudey
= latitude}
}
}
]
texts {
= 1 ou plusieurs textes associés au spectacle ...}
]
Les textes d'un éditeur associés à des spectacles à l'affiche
Point d'entrée : textes/affiche-editeur
Critère : structure:nnn
Critère supplémentaire facultatif : person:nnn
Filtres optionnels : from
, to
, area
, role
(défaut=author)
Exemples de requête :
Toutes les représentations produites/coproduites par une structure donnée à partir d'aujourd'hui :https://theatre.info/api/textes/affiche-editeur/structure:nnn?api-key=XXX
Même résultat, mais filtré sur la France uniquement, limité à une personne précise de la direction de spectacle, depuis aujourd'hui jusqu'à une date définie :https://theatre.info/api/textes/affiche-editeur/structure:nnn,person:nnn[to=2025-12-12,area=FR]?api-key=XXX
Structure du résultat
Identique à la requête précédente.