REST API · Texts

Context

The stored context notes.

GET/api/v1/context

Where the text sits in its work, what happens, who and where is named, what comes next, and a few lines on the work. Hand-written for graded passages; for library sections, stored once a reader has opened Context. Never generated here.

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`.

Response

200 OK with a ContextResponse 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`.

machineWrittenboolean False for the graded passages' hand-written notes.

sectionobject or null

Null until someone has opened Context for this part in the reader.

4 fields

soFarstring or null What has happened in the work before this part.

herestring or null What happens in this part, never a translation.

peoplearray of object

People, gods and places named here.

4 fields

people fields
`name`string
`note`string
`forms`array of string	The words in the text that name them.
`wikipedia`string or null	English Wikipedia article title, when certain.

nextstring or null What comes next.

workobject or null

A few lines about the work.

2 fields

work fields
`intro`string or null
`note`string or null

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/context" \
  --data-urlencode "ref=/read/latin/virgil-aeneid"

const params = new URLSearchParams({ ref: "/read/latin/virgil-aeneid" })
const res = await fetch(`https://interlinea.aeterna-institute.org/api/v1/context?${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"})
with urlopen(f"https://interlinea.aeterna-institute.org/api/v1/context?{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"
  },
  "machineWritten": false,
  "section": {
    "soFar": null,
    "here": "The opening lines announce the subject: a man driven by fate from Troy to Italy, battered on land and sea by Juno’s anger, who must fight a…",
    "people": [
      {
        "name": "Troy",
        "note": "The city in Asia Minor destroyed by the Greeks, where Aeneas comes from.",
        "forms": [
          "Troiae"
        ],
        "wikipedia": "Troy"
      },
      {
        "name": "Italy",
        "note": "Where fate is sending Aeneas.",
        "forms": [
          "Italiam"
        ],
        "wikipedia": null
      },
      {
        "name": "Lavinium",
        "note": "The town Aeneas will found in Latium, named after his future wife Lavinia.",
        "forms": [
          "Lavinia"
        ],
        "wikipedia": "Lavinium"
      },
      // 5 more
    ],
    "next": "Virgil names Carthage, the city Juno loves, and the old grudges behind her anger. Then the story opens at sea, with the Trojans sailing from…"
  },
  "work": {
    "intro": "Virgil’s epic in twelve books follows Aeneas, a Trojan prince, from the fall of Troy to Italy, where his descendants will found Rome. The fi…",
    "note": "Written in Augustus’ Rome in dactylic hexameter, the metre of Homer, it answers the Iliad and the Odyssey in Latin. It became the central po…"
  }
}

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

Try it

Send a real GET from your browser and see the answer, its status and how long it took.

Parameters#

Response#

Errors#

Example request#

Example response#

Try it#

Parameters

Response

Errors

Example request

Example response

Try it