Pour les développeurs

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 spectacle
object = objet API du spectacle (show:nnn)
permanent_url = URL du spectacle sur theatre.info
directors { = de 1 à plusieurs personnes
  "nnn = id": {
    lastname = nom de famille
    firstname = 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×200
poster_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) au format aaaa-mm-jj
end = date globale de fin (toutes les représentations) au format aaaa-mm-jj ou null si date unique
start_end = dates globale de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)
schedules [ = 1 ou plusieurs représentations (représentation = dates + lieu)
  {
    start = date de début au format aaaa-mm-jj
    end = date de fin au format aaaa-mm-jj ou null si date unique
    start_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 dates
      aaaa-mm-jj
    ]
    city = ville
    zipcode = code postal
    country = code du pays sur 2 lettres
    place {	= lieu de la représentation
      name = nom de la structure/théâtre
      object = objet API de la structure (structure:nnn)
      permanent_url = URL de la structure sur theatre.info
      geocode { = coordonnées gps du lieu
        x = longitude
        y = 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 spectacles
  title = titre du spectacle
  object = objet API du spectacle (show:nnn)
  permanent_url = URL du spectacle sur theatre.info
  directors { = de 1 à plusieurs personnes
    "nnn = id": {
      lastname = nom de famille
      firstname = 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×200
  poster_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) au format aaaa-mm-jj
  end = date globale de fin (toutes les représentations) au format aaaa-mm-jj ou null si date unique
  start_end = dates globale de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)
  schedules [ = 1 ou plusieurs représentations (représentation = dates)
    {
      start = date de début au format aaaa-mm-jj
      end = date de fin au format aaaa-mm-jj ou null si date unique
      start_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 dates
        aaaa-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 spectacles
  title = titre du spectacle
  object = objet API du spectacle (show:nnn)
  permanent_url = URL du spectacle sur theatre.info
  directors { = de 1 à plusieurs personnes
    "nnn = id": {
      lastname = nom de famille
      firstname = 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×200
  poster_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) au format aaaa-mm-jj
  end = date globale de fin (toutes les représentations) au format aaaa-mm-jj ou null si date unique
  start_end = dates globale de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)
  schedules [ = 1 ou plusieurs représentations (représentation = dates)
    {
      start = date de début au format aaaa-mm-jj
      end = date de fin au format aaaa-mm-jj ou null si date unique
      start_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 dates
        aaaa-mm-jj
      ]
      city = ville
      zipcode = code postal
      country = code du pays sur 2 lettres
      place {	= lieu de la représentation
        name = nom de la structure/théâtre
        object = objet API de la structure (structure:nnn)
        permanent_url = URL de la structure sur theatre.info
        geocode { = coordonnées gps du lieu
          x = longitude
          y = 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 famille
        firstname = 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) ou null
    }
  ]
]

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 texte
    title = titre du texte sur theatre.info
    object = objet API du texte (text:nnn)
    permanent_url = URL du texte sur theatre.info
    ean = code EAN du texte
    poster = URL de l'image du texte sur theatre.info au format portrait 240×360
    publisher_url = URL du texte sur le site de l'éditeur ou null
    authors { = de 1 à plusieurs personnes
      "nnn = id": {
        lastname = nom de famille
        firstname = 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 spectacles
  title = titre du spectacle
  object = objet API du spectacle (show:nnn)
  permanent_url = URL du spectacle sur theatre.info
  directors { = de 1 à plusieurs personnes
    "nnn = id": {
      lastname = nom de famille
      firstname = 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×200
  poster_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) au format aaaa-mm-jj
  end = date globale de fin (toutes les représentations) au format aaaa-mm-jj ou null si date unique
  start_end = dates globale de début et fin au format jj moi. > jj moi. aaaa ou jj moi. aaaa (si date unique)
  schedules [ = 1 ou plusieurs représentations (représentation = dates)
    {
      start = date de début au format aaaa-mm-jj
      end = date de fin au format aaaa-mm-jj ou null si date unique
      start_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 dates
        aaaa-mm-jj
      ]
    }
  ]
  texts { = 1 ou plusieurs textes associés au spectacle
   "nnn EAN": {
      title = titre du texte sur theatre.info
      object = objet API du texte (text:nnn)
      permanent_url = URL du texte sur theatre.info
      ean = code EAN du texte
      poster = URL de l'image du texte sur theatre.info au format portrait 240×360
      publisher_url = URL du texte sur le site de l'éditeur ou null
      authors { = de 1 à plusieurs personnes
        "nnn = id": {
          lastname = nom de famille
          firstname = 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 spectacles
  title = titre du spectacle
  ...
  schedules [ = 1 ou plusieurs représentations (représentation = dates)
    {
    ...
      city = ville
      zipcode = code postal
      country = code du pays sur 2 lettres
      place {	= lieu de la représentation
        name = nom de la structure/théâtre
        object = objet API de la structure (structure:nnn)
        permanent_url = URL de la structure sur theatre.info
        geocode { = coordonnées gps du lieu
          x = longitude
          y = 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.