DTS Text Services Extractor

Point at ANY Distributed Text Services (DTS) endpoint and extract it — browse the collection tree, list a text's citeable references, or pull the TEI/XML of any passage. Give the entry URL of a DTS service, choose a mode, and this actor returns structured, flat records from any compliant digital-humanities text repository.

One actor speaks to the entire DTS world. There is no per-repository scraper and no host list to maintain: DraCor (drama corpora), Perseids / Perseus (Greek & Latin classics), the École nationale des chartes (DoTS) and the growing population of TEI text repositories all expose the identical Distributed Text Services API.

What is DTS?

Distributed Text Services is a specification that standardises how text collections are published on the web, so that a single client can navigate and retrieve text from any conformant repository. It is three linked endpoints, discovered from an entry document:

• Collection — the browse tree of a corpus: child collections and readable resources, each with Dublin Core metadata (title, creator, language …) and child / parent counts.
• Navigation — the citeable reference tree of one resource (its front / body / act / scene … citation units), so any passage can be addressed by its citation ref.
• Document — the actual TEI / XML text of a resource, or of a single passage / citation range.

The three endpoint URLs are not hard-coded: the actor reads the entry document's URI templates and resolves the real endpoints per host (DraCor serves /api/v1/dts/collection, Perseids serves /collections with no /dts segment, DoTS serves /demo/api/dts/collection), so whatever base URL you give it just works.

What it does

• Collection mode — GETs the Collection endpoint and emits one record per member (child collection or readable resource), with title, description, totalItems / totalChildren, dublinCore, and the collection / navigation / document links. Recurses into child collections up to maxDepth, following Hydra pagination cursors.
• Navigation mode — lists the citeable references of a resource: one record per CitableUnit with its ref, citeType and level.
• Document mode — fetches the resource's (or one passage's) TEI/XML and emits it as a rawXml field plus a whitespace-normalised plainText rendering of the TEI <text> body.

Every optional field is nullable, because DTS members routinely omit Dublin Core creator / date / language. The member list is decoded from any serialization the spec and its drafts permit (member in DTS 1.0, dts:member / @graph on 1-alpha / rc hosts). A resource's Document reply is treated as XML, never JSON.

An HTTP error or non-conformant response is surfaced as a real error — never a fabricated empty result.

Input

Field	Required	Description
entryUrl	yes	The entry / base URL of a DTS service (e.g. https://dev.dracor.org/api/v1/dts). The actor resolves the Collection / Navigation / Document endpoints from it. You may also pass a Collection / Navigation / Document URL directly.
mode	no	collection (default), navigation, or document.
collectionId	no	(collection mode) The @id of a specific collection to descend into. Empty = the service's top collection.
resource	navigation / document	The identifier of the resource to navigate or fetch (a Resource member's @id from collection mode).
ref	no	A single citation reference to target (navigation: list its children; document: return just that passage).
start / end	no	A citation range to select a span of passages.
down	no	(navigation mode) How many citation levels below the target to return. Defaults to 1.
mediaType	no	(document mode) DTS mediaType, e.g. application/tei+xml, text/plain.
maxDepth	no	(collection mode) Levels of child collections to descend. 0 = no recursion, 1 (default) = expand one level.
maxRecords	no	Global cap on records emitted (each record is one billable event). Default 1000.
timeoutSecs	no	Per-request read timeout (default 120).
userAgent	no	Override the request User-Agent.
bearer	no	Bearer token for an auth-gated deployment (never logged).
extraHeaders	no	Extra HTTP headers as a JSON object (values never logged).

Examples

Browse the top of the DraCor corpus tree, one level deep:

{
  "entryUrl": "https://dev.dracor.org/api/v1/dts",
  "mode": "collection",
  "maxDepth": 1,
  "maxRecords": 200
}

List the citeable references of a play:

{
  "entryUrl": "https://dev.dracor.org/api/v1/dts",
  "mode": "navigation",
  "resource": "https://dev.dracor.org/id/ger000171",
  "down": 1
}

Fetch the TEI/XML of one passage:

{
  "entryUrl": "https://dev.dracor.org/api/v1/dts",
  "mode": "document",
  "resource": "https://dev.dracor.org/id/ger000171",
  "ref": "body"
}

Any DTS host works the same way — point entryUrl at Perseids (https://dts.perseids.org) or DoTS (https://dots.chartes.psl.eu/demo/api/dts) and the endpoints are resolved automatically.

Output

Each record is a flat JSON object. Key fields:

Field	Description
_mode	collection / navigation / document.
id	The member / resource @id.
type	Collection, Resource, CitableUnit, Document.
title, description	Human-readable metadata (nullable).
totalItems, totalChildren, totalParents	Collection counts (nullable).
dublinCore	The member's Dublin Core metadata block (nullable).
collectionUrl, navigationUrl, documentUrl, downloadUrl	Links to descend / navigate / fetch (nullable).
ref, citeType, level	(navigation) the citation unit's reference, structural type, and depth.
rawXml, plainText, mediaType	(document) the TEI/XML, its stripped plaintext, and the response content type.
_raw	A lossless copy of the source member object.

Pricing

This actor is pay-per-event: you are charged per record emitted (one collection member, one citeable reference, or one document passage). Set maxRecords to cap the run.

Notes

• This is a metadata & text runner over public DTS APIs. It respects each service's own responses and follows Hydra pagination.
• A resource with no members / an empty collection returns zero records (never fabricated rows).
• For auth-gated deployments, pass a bearer token or extraHeaders; credentials are never logged.