API

ETSO propose une API publique pour consulter les œuvres et les auteurs du catalogue et réutiliser leurs identifiants, titres, attributions, résultats stylométriques et liens.

Les informations sont fournies au format JSON et peuvent servir à intégrer les données d’ETSO dans des catalogues, visualisations, moteurs de recherche ou outils de recherche.

Endpoints

GET /api/obras

Renvoie le catalogue complet des œuvres avec leurs métadonnées publiques.

GET /api/obras/{id-publicId-o-slug}

Renvoie une seule œuvre à partir de son identifiant ou de son slug public.

GET /api/autores

Renvoie la liste complète des auteurs avec leurs métadonnées et les cinq catégories d’œuvres associées.

GET /api/autores/{id-o-key}

Renvoie les métadonnées et les cinq catégories d’œuvres d’un auteur à partir de son identifiant numérique ou de sa clé textuelle.

Sélectionner les champs de la réponse

Les quatre endpoints acceptent le paramètre facultatif fields, avec les noms de champs publics de premier niveau séparés par des virgules. Les tableaux suivants décrivent les champs de chaque ressource. La sélection d’un objet, comme resources, renvoie l’objet public complet.

Sans fields, tous les champs publics sont renvoyés. La sélection conserve les enveloppes authors, author, works ou work et les informations meta applicables. Une sélection vide, un champ inconnu ou privé, ou un chemin imbriqué tel que resources.work renvoie HTTP 400.

https://etso.es/api/obras/690677?fields=publicId,displayTitle

{
  "meta": {
    "contentPolicy": {
      "includesFullText": false,
      "includesSummaries": false,
      "excludedFields": [
        "fullText",
        "text",
        "shortSummary",
        "summaryText",
        "resumen_breve",
        "resumen_largo"
      ]
    }
  },
  "work": {
    "publicId": 690677,
    "displayTitle": "La francesa Laura"
  }
}

Métadonnées des œuvres

Champ	Description
`id`	Identifiant stable de l’œuvre.
`publicId`	Identifiant public numérique stable de l’œuvre.
`slug`	Identifiant lisible utilisé dans les URL publiques.
`title`	Titre tel qu’il figure dans la base de données, avec l’article final le cas échéant.
`displayTitle`	Titre transformé selon le même procédé que celui utilisé sur le site ETSO.
`titleVariants`	Autres titres de l’œuvre tels qu’ils figurent dans la base de données.
`displayTitleVariants`	Autres titres transformés selon le même procédé que celui utilisé sur le site.
`genre`	Genre de l’œuvre.
`origin`	Provenance ou source du texte utilisé par ETSO.
`textState`	État du texte dans le catalogue.
`addedOn`	Date d’incorporation au catalogue, lorsqu’elle est indiquée.
`bitesoPublishedOn`	Date de publication dans BITESO ; null si inconnue.
`summaryPublishedOn`	Date de publication du résumé ; null si inconnue.
`resultado1`	Résultat stylométrique de l’œuvre sous forme de phrase.
`flags`	Indicateurs booléens sur le rapport, le résumé, l’examen d’autorie et l’accès textuel.
`traditionalAttributionText`	Attribution traditionnelle prête à afficher.
`traditionalAttributionPhrase`	Phrase d’attribution traditionnelle avec texte, Markdown, HTML et parties liables.
`stylometryAttributionText`	Attribution stylométrique prête à afficher.
`traditionalAttribution`	Attribution traditionnelle normalisée.
`stylometryAttribution`	Attribution stylométrique normalisée.
`resources`	Liens publics associés dans ETSO.

Dans les objets d’attribution, authorId est l’identifiant public numérique de l’auteur et authorKey est la clé textuelle utilisée dans les URL d’ETSO. Ce sont des propriétés des attributions, et non des champs de premier niveau.

Exemple de réponse complète

Requête pour une œuvre précise et réponse complète :

https://etso.es/api/obras/690677

{
  "meta": {
    "contentPolicy": {
      "includesFullText": false,
      "includesSummaries": false,
      "excludedFields": [
        "fullText",
        "text",
        "shortSummary",
        "summaryText",
        "resumen_breve",
        "resumen_largo"
      ]
    }
  },
  "work": {
    "id": "DESCONOCIDO_FrancesaLaura",
    "publicId": 690677,
    "slug": "la-francesa-laura",
    "title": "Francesa Laura, La",
    "displayTitle": "La francesa Laura",
    "titleVariants": [],
    "displayTitleVariants": [],
    "genre": "Comedia",
    "origin": "El texto procede de la edición crítica de Álvaro Cuéllar y Germán Vega García-Luengos (Gredos, 2023).",
    "textState": "Bueno",
    "addedOn": "2021/03",
    "bitesoPublishedOn": "2026-06-18",
    "summaryPublishedOn": "2026-06-18",
    "resultado1": "Los analisis de estilometria permiten asociar esta obra de forma clara con el perfil autorial de Lope de Vega Carpio.",
    "flags": {
      "inAuthorshipExam": true,
      "hasSummary": true,
      "hasReport": true,
      "hasTextAccess": true
    },
    "traditionalAttributionText": "Lope de Vega Carpio",
    "traditionalAttributionPhrase": {
      "text": "Obra atribuida a Lope de Vega Carpio.",
      "markdown": "Obra atribuida a [Lope de Vega Carpio](https://etso.es/autores/vega_carpio_lope_de).",
      "html": "Obra atribuida a <a href=\"/autores/vega_carpio_lope_de\">Lope de Vega Carpio</a>.",
      "parts": [
        {
          "kind": "text",
          "value": "Obra atribuida a "
        },
        {
          "kind": "author",
          "value": "Lope de Vega Carpio",
          "authorId": 364,
          "authorKey": "vega_carpio_lope_de",
          "href": "/autores/vega_carpio_lope_de",
          "url": "https://etso.es/autores/vega_carpio_lope_de"
        },
        {
          "kind": "text",
          "value": "."
        }
      ]
    },
    "stylometryAttributionText": "Lope de Vega Carpio [Segura]",
    "traditionalAttribution": {
      "groups": [
        {
          "members": [
            {
              "authorId": 364,
              "authorKey": "vega_carpio_lope_de",
              "authorName": "Lope de Vega Carpio"
            }
          ]
        }
      ],
      "connector": "and",
      "rawExpression": "vega_carpio_lope_de"
    },
    "stylometryAttribution": {
      "groups": [
        {
          "members": [
            {
              "authorId": 364,
              "authorKey": "vega_carpio_lope_de",
              "authorName": "Lope de Vega Carpio",
              "confidence": "segura"
            }
          ]
        }
      ],
      "connector": "and",
      "rawExpression": "vega_carpio_lope_de[segura]"
    },
    "resources": {
      "work": "/obras/la-francesa-laura",
      "summary": "/obras/la-francesa-laura/resumen",
      "report": "/informes/analisis-estilometrico-la-francesa-laura",
      "textAccess": [
        {
          "label": "Texto BITESO",
          "href": "/biteso/la-francesa-laura",
          "kind": "biteso"
        }
      ]
    }
  }
}

Auteurs et œuvres associées

L’id numérique de l’auteur est l’identifiant ETSO et correspond à authorId dans les attributions des œuvres. La clé textuelle key identifie l’auteur dans les URL d’ETSO.

Champ	Description
`id`	Identifiant public numérique de l’auteur, correspondant à authorId dans les attributions des œuvres.
`key`	Clé textuelle utilisée dans les URL de l’auteur.
`name`	Nom de l’auteur.
`nameVariants`	Variantes du nom de l’auteur.
`resources`	Liens vers la fiche publique de l’auteur : author est le chemin et url, l’URL absolue.

Œuvres par auteur

Chaque auteur inclut cinq tableaux de publicId numériques d’œuvres (number[]), correspondant aux cinq catégories de sa fiche dans l’examen d’autorie. Seules les œuvres de cet examen sont incluses, selon les critères du site : les attributions probables ou possibles et les collaborations sont admises ; les attributions traditionnelles ou stylométriques non résolues sont exclues de leur côté respectif. La présence d’une œuvre n’implique pas une paternité certaine ou exclusive.

Chaque catégorie sans œuvre renvoie []. Les catégories sont calculées pour l’auteur consulté. Chaque publicId d’œuvre permet de consulter /api/obras/{publicId} ou de créer un lien vers https://etso.es/obras/{publicId}, qui redirige vers la fiche canonique.

Champ	Description
`relatedWorkPublicIds`	Œuvres liées à l’auteur : attribution traditionnelle ou stylométrique.
`traditionalWorkPublicIds`	Œuvres étayées par la tradition.
`stylometryWorkPublicIds`	Œuvres étayées par la stylométrie.
`traditionalOnlyWorkPublicIds`	Œuvres étayées uniquement par la tradition : sans appui stylométrique pour cet auteur.
`newStylometrySupportedWorkPublicIds`	Nouvelles attributions étayées par la stylométrie : sans attribution traditionnelle à cet auteur.

Tous les auteurs et leurs cinq listes d’œuvres

https://etso.es/api/autores

Un auteur et ses cinq listes d’œuvres

https://etso.es/api/autores/374

Uniquement les œuvres associées à un auteur

https://etso.es/api/autores/374?fields=id,relatedWorkPublicIds

Utilisation recommandée

Les réponses sont servies avec un cache public : public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800. Pour les intégrations externes, il est recommandé de mettre la réponse en cache localement et de ne pas appeler l’API à chaque rendu.

La sélection de champs réduit la taille de la réponse et le transfert de données. À elle seule, elle ne réduit pas le nombre de requêtes et ne supprime pas toutes les consultations de la base de données.