REST API · Texts

Analysis

The stored word-by-word analysis.

GET/api/v1/analysis

Lemma, dictionary entry, part of speech, features, syntax and meaning in context for every word, with a translation per sentence. Stored analyses only: nothing is generated, so a sentence nobody has opened yet comes back with words: null.

Parameters

Parameters
Name	Description
`ref`string	RequiredA library or graded-passage URL, a CTS URN (urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.46) or a citation ("Virgil, Aeneid 1.46"). Up to 500 characters. Example `/read/latin/virgil-aeneid`.
`sentence`integer	OptionalOnly this sentence (0-based). Example `0`.

Response

200 OK with a AnalysisResponse object.

Name Description

kindstring

One of section, passage.

langstring

Language code: la (Latin) or grc (Ancient Greek).

One of la, grc.

languagestring

citationstring

urnstring or null CTS URN, e.g. urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.1-1.11. Null when the edition has none (The Latin Library's own numbering).

urlstring Absolute URL.

apistring Absolute URL.

prevLink or null

4 fields

prev fields
`citation`string	"Aeneid 1.12-33"
`label`string	"Book 1, lines 12-33"
`url`string	Absolute URL.
`api`string	The same resource as JSON.

nextLink or null

4 fields

next fields
`citation`string	"Aeneid 1.12-33"
`label`string	"Book 1, lines 12-33"
`url`string	Absolute URL.
`api`string	The same resource as JSON.

creditCredit

5 fields

credit fields
`text`string	Credit line for the edition: author, work, editor, source, licence and changes. Quote it when you reuse the text.
`license`string	CC BY-SA 4.0, CC BY 3.0, Used with permission (The Latin Library), or a public-domain note.
`licenseUrl`string or null
`source`string	Where the edition comes from.
`quality`string	ocr: an unproofread scan. One of `proofread`, `ocr`.

analysedinteger Sentences with a stored analysis.

totalinteger Sentences in the text.

licensestring

The analyses adapt CC BY-SA text, so they are share-alike.

Always CC BY-SA 4.0.

notestring

sentencesarray of AnalysedSentence

4 fields

indexinteger 0-based sentence index in the text.

textstring

translationstring or null Null when the sentence has no stored analysis yet.

wordsarray of Word or null

Null when the sentence has no stored analysis yet.

11 fields

iinteger 1-based index of the word in its sentence.

formstring The word as printed.

lemmastring Dictionary headword; Latin with macrons, Greek polytonic.

entrystring or null Dictionary entry: principal parts, or genitive and gender.

uposstring Universal Dependencies part of speech.

featsstring Universal Dependencies features, e.g. "Case=Acc|Gender=Neut|Number=Plur"; "_" if none.

headinteger Index of the word this one depends on; 0 for the root.

deprelstring Universal Dependencies relation to its head: nsubj, obj, amod, …

glossstring Meaning in this sentence, 1 to 4 words.

notestring or null One sentence on the word's role.

encliticobject

OptionalPresent only when an enclitic rides on the word, e.g. -que "and".

2 fields

enclitic fields
`form`string
`gloss`string

Errors

Status	When
`400 Bad Request`	A parameter is missing or invalid, or the reference isn't a text.
`404 Not Found`	Not in the library.
`429 Too Many Requests`	Too many requests from one address. Wait a minute.
`500 Internal Server Error`	Something went wrong on our side.

Error bodies are described in Caching, limits and errors.

Example request

curl -G "https://interlinea.aeterna-institute.org/api/v1/analysis" \
  --data-urlencode "ref=/read/latin/virgil-aeneid" \
  --data-urlencode "sentence=0"

const params = new URLSearchParams({ ref: "/read/latin/virgil-aeneid", sentence: "0" })
const res = await fetch(`https://interlinea.aeterna-institute.org/api/v1/analysis?${params}`)
const data = await res.json()
console.log(data)

import json
from urllib.parse import urlencode
from urllib.request import urlopen

params = urlencode({"ref": "/read/latin/virgil-aeneid", "sentence": "0"})
with urlopen(f"https://interlinea.aeterna-institute.org/api/v1/analysis?{params}") as res:
    data = json.load(res)

print(data)

Example response

Response200 OK

{
  "kind": "passage",
  "lang": "la",
  "language": "Latin",
  "citation": "Virgil, Aeneid 1.1–11",
  "urn": "urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.1-1.11",
  "url": "https://interlinea.aeterna-institute.org/read/latin/virgil-aeneid",
  "api": "https://interlinea.aeterna-institute.org/api/v1/passages/latin/virgil-aeneid",
  "prev": {
    "citation": "Metamorphoses 1.1–9",
    "label": "Bodies Changed",
    "url": "https://interlinea.aeterna-institute.org/read/latin/ovid-metamorphoses",
    "api": "https://interlinea.aeterna-institute.org/api/v1/passages/latin/ovid-metamorphoses"
  },
  "next": {
    "citation": "Odes 1.11",
    "label": "Seize the Day",
    "url": "https://interlinea.aeterna-institute.org/read/latin/horace-carpe-diem",
    "api": "https://interlinea.aeterna-institute.org/api/v1/passages/latin/horace-carpe-diem"
  },
  "credit": {
    "text": "Virgil, Aeneid 1.1–11. CC BY-SA 4.0. Perseus Digital Library (Tufts University), PerseusDL/canonical-latinLit; edition: J. B. Greenough, Gin…",
    "license": "CC BY-SA 4.0",
    "licenseUrl": "https://creativecommons.org/licenses/by-sa/4.0/",
    "source": "https://scaife.perseus.org/reader/urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.1-1.11/",
    "quality": "proofread"
  },
  "analysed": 1,
  "total": 4,
  "license": "CC BY-SA 4.0",
  "note": "Stored analyses only, made by a language model when a reader first opened the text and checked by rules (one root, no loops, valid labels).…",
  "sentences": [
    {
      "index": 0,
      "text": "Arma virumque cano, Troiae qui primus ab oris\nItaliam, fato profugus, Laviniaque venit\nlitora, multum ille et terris iactatus et alto\nvi sup…",
      "translation": "I sing of arms and a man, who first, an exile by fate, came from the shores of Troy to Italy and the Lavinian shores, that man having been t…",
      "words": [
        {
          "i": 1,
          "form": "Arma",
          "lemma": "arma",
          "entry": "arma, armōrum n. pl.",
          "upos": "NOUN",
          "feats": "Case=Acc|Gender=Neut|Number=Plur",
          "head": 3,
          "deprel": "obj",
          "gloss": "arms",
          "note": "Accusative plural, direct object of cano."
        },
        {
          "i": 2,
          "form": "virumque",
          "lemma": "vir",
          "entry": "vir, virī m.",
          "upos": "NOUN",
          "feats": "Case=Acc|Gender=Masc|Number=Sing",
          "head": 1,
          "deprel": "conj",
          "gloss": "man",
          "note": "Accusative singular, direct object of cano, joined to Arma by the enclitic -que.",
          "enclitic": {
            "form": "-que",
            "gloss": "and"
          }
        },
        {
          "i": 3,
          "form": "cano",
          "lemma": "canō",
          "entry": "canō, canere, cecinī, cantum",
          "upos": "VERB",
          "feats": "Aspect=Imp|Mood=Ind|Number=Sing|Person=1|Tense=Pres|VerbForm=Fin|Voice=Act",
          "head": 0,
          "deprel": "root",
          "gloss": "I sing",
          "note": "Main verb of the sentence, present active indicative, first person singular."
        },
        // 25 more
      ]
    }
  ]
}

Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=86400

Parameters#

Response#

Errors#

Example request#

Example response#

Try it#

Parameters

Response

Errors

Example request

Example response

Try it