API

ETSO offre un’API pubblica per consultare le opere e gli autori del catalogo e riutilizzare identificatori, titoli, attribuzioni, risultati stilometrici e collegamenti.

Le informazioni sono fornite in formato JSON e possono essere usate per integrare i dati di ETSO in cataloghi, visualizzazioni, motori di ricerca o strumenti di ricerca.

Endpoint

GET /api/obras

Restituisce il catalogo completo delle opere con i relativi metadati pubblici.

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

Restituisce una singola opera usando il suo identificatore o slug pubblico.

GET /api/autores

Restituisce l’elenco completo degli autori con i loro metadati e le cinque categorie di opere collegate.

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

Restituisce i metadati e le cinque categorie di opere di un autore usando l’id numerico o la chiave testuale.

Selezionare i campi della risposta

I quattro endpoint accettano il parametro facoltativo fields con i nomi dei campi pubblici di primo livello separati da virgole. Le tabelle seguenti descrivono i campi di ogni risorsa. Selezionare un oggetto, come resources, restituisce l’intero oggetto pubblico.

Senza fields vengono restituiti tutti i campi pubblici. La selezione conserva i contenitori authors, author, works o work e le informazioni meta applicabili. Selezioni vuote, campi sconosciuti o privati e percorsi annidati come resources.work restituiscono 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"
  }
}

Metadati delle opere

Campo	Descrizione
`id`	Identificatore stabile dell’opera.
`publicId`	Identificatore pubblico numerico stabile dell’opera.
`slug`	Identificatore leggibile usato negli URL pubblici.
`title`	Titolo come compare nel database, incluso l’articolo finale quando presente.
`displayTitle`	Titolo trasformato con lo stesso processo usato dal sito ETSO.
`titleVariants`	Altri titoli dell’opera come compaiono nel database.
`displayTitleVariants`	Altri titoli trasformati con lo stesso processo usato dal sito.
`genre`	Genere dell’opera.
`origin`	Provenienza o fonte del testo usato da ETSO.
`textState`	Stato del testo nel catalogo.
`addedOn`	Data di inserimento nel catalogo, quando disponibile.
`bitesoPublishedOn`	Data di pubblicazione in BITESO; null se non disponibile.
`summaryPublishedOn`	Data di pubblicazione del riassunto; null se non disponibile.
`resultado1`	Risultato stilometrico dell’opera in forma di frase.
`flags`	Indicatori booleani su rapporto, riassunto, esame delle autorie e accesso testuale.
`traditionalAttributionText`	Attribuzione tradizionale pronta per la visualizzazione.
`traditionalAttributionPhrase`	Frase di attribuzione tradizionale con testo, Markdown, HTML e parti collegabili.
`stylometryAttributionText`	Attribuzione stilometrica pronta per la visualizzazione.
`traditionalAttribution`	Attribuzione tradizionale normalizzata.
`stylometryAttribution`	Attribuzione stilometrica normalizzata.
`resources`	Link pubblici correlati all’interno di ETSO.

Negli oggetti di attribuzione, authorId è l’identificatore pubblico numerico dell’autore e authorKey è la chiave testuale usata negli URL di ETSO. Sono proprietà delle attribuzioni, non campi di primo livello.

Esempio di risposta completa

Query di un’opera specifica e risposta completa:

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"
        }
      ]
    }
  }
}

Autori e opere collegate

L’id numerico dell’autore è l’identificatore ETSO e corrisponde ad authorId nelle attribuzioni delle opere. La chiave testuale key identifica l’autore negli URL di ETSO.

Campo	Descrizione
`id`	Identificatore pubblico numerico dell’autore; corrisponde ad authorId nelle attribuzioni delle opere.
`key`	Chiave testuale usata negli URL dell’autore.
`name`	Nome dell’autore.
`nameVariants`	Varianti del nome dell’autore.
`resources`	Collegamenti alla scheda pubblica dell’autore: author è il percorso e url è l’URL assoluto.

Opere per autore

Ogni autore include cinque array di publicId numerici di opere (number[]), corrispondenti alle cinque categorie della sua scheda nell’esame delle autorie. Sono incluse solo le opere di tale esame, con gli stessi criteri del sito: sono ammesse attribuzioni probabili o possibili e collaborazioni; le attribuzioni tradizionali o stilometriche irrisolte sono escluse dal rispettivo lato. L’inclusione non implica una paternità certa o esclusiva.

Ogni categoria senza opere restituisce []. Le categorie sono calcolate per l’autore consultato. Ogni publicId di un’opera permette di consultare /api/obras/{publicId} o creare un collegamento a https://etso.es/obras/{publicId}, che reindirizza alla scheda canonica.

Campo	Descrizione
`relatedWorkPublicIds`	Opere collegate all’autore: attribuzione tradizionale o stilometrica.
`traditionalWorkPublicIds`	Opere sostenute dalla tradizione.
`stylometryWorkPublicIds`	Opere sostenute dalla stilometria.
`traditionalOnlyWorkPublicIds`	Opere sostenute solo dalla tradizione: senza sostegno stilometrico per questo autore.
`newStylometrySupportedWorkPublicIds`	Nuove attribuzioni sostenute dalla stilometria: senza attribuzione tradizionale a questo autore.

Tutti gli autori e i loro cinque elenchi di opere

https://etso.es/api/autores

Un autore e i suoi cinque elenchi di opere

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

Solo le opere collegate a un autore

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

Uso consigliato

Le risposte sono servite con cache pubblica: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800. Per integrazioni esterne si consiglia di memorizzare localmente la risposta e di non chiamare l’API a ogni rendering.

Selezionare i campi riduce la dimensione della risposta e il trasferimento di dati. Da solo, non riduce il numero di richieste né elimina tutte le interrogazioni al database.