Framework API Client

Client for CDLI framework API.

• Install
• Getting started
  • Command-Line Interface
  • Programming Interface

Install

A prerequisite for this client is Node.JS and a package manager like npm, which usually comes with it.

npm install -g cdli-api-client

Or install it locally into an existing project:

npm install cdli-api-client

Alternatively, the command can be run with npx:

npx cdli-api-client --help

Getting started

Right now, the client supports two basic operations:

• exporting parts of the database as linked data (or specifically N-Triples). The parts that can be chosen are the types of entities in the catalogue, such as artifacts, materials, proveniences, inscriptions and periods.
• searching artifacts in the database.

Command-Line Interface

cdli [command]

Commands:
  cdli export  Export catalog and text data
  cdli search  Export catalog and text data

Options:
  --version          Show version number                               [boolean]
  --host, -h         Host URL to use for API calls
                                       [string] [default: "https://cdli.earth/"]
  --format, -f       File format
                  [choices: "ndjson", "csv", "tsv", "ntriples", "bibtex", "atf"]
  --output-file, -o  Output file (outputs to stdout by default)
  --help             Show help                                         [boolean]

Export

cdli export

Export catalog and text data

Options:
      --version      Show version number                               [boolean]
  -h, --host         Host URL to use for API calls
                                       [string] [default: "https://cdli.earth/"]
  -f, --format       File format
           [choices: "ndjson", "csv", "tsv", "ntriples", "ttl", "bibtex", "atf"]
  -o, --output-file  Output file (outputs to stdout by default)
      --help         Show help                                         [boolean]
  -e, --entities     Which types of entities to fetch
  [array] [choices: "abbreviations", "archives", "artifacts", "artifact-assets",
                          "artifacts-external-resources", "artifacts-materials",
      "entities-external-resources", "entities-names", "authors", "collections",
        "dynasties", "external-resources", "genres", "inscriptions", "journals",
   "languages", "locations", "materials", "material-aspects", "material-colors",
       "periods", "places", "proveniences", "publications", "regions", "rulers"]
                                                                   [default: []]
  -i, --index        Which index(es) to fetch              [array] [default: []]

So to export place-related entities from a locally-running framework instance you could do this:

cdli export \
  --host http://localhost:2354/ \
  --entities archives proveniences regions \
  --output-file places.nt

Fetching all artifacts from the live server could look like this:

cdli export \
  --host https://cdli.earth/ \
  --entities artifacts \
  --format csv \
  --output-file artifacts.csv

Export all linked data:

cdli export \
  --host https://cdli.earth/ \
  --entities abbreviations archives artifacts artifact-assets \
    artifacts-external-resources artifacts-materials authors collections \
    dynasties entities-external-resources entities-names external-resources \
    genres inscriptions journals languages locations materials material-aspects \
    material-colors periods places proveniences publications regions rulers \
  --format ntriples \
  --output-file all.nt

Search

cdli search

Search artifacts in the catalog

Simple search:
  -q, --query                Search query                                [array]
      --queryCategory, --qc  Search category
        [array] [choices: "keyword", "publication", "collection", "provenience",
                               "period", "transliteration", "translation", "id"]
      --queryOperator, --qo  Search operator      [array] [choices: "AND", "OR"]

Advanced search:
      --advancedField, --af  Search field                                [array]
      --advancedQuery, --aq  Search query                                [array]

Filter:
      --filterField, --fk  Filter by field                               [array]
      --filterValue, --fv  Filter by value                               [array]

Options:
      --version      Show version number                               [boolean]
  -h, --host         Host URL to use for API calls
                         [string] [default: "https://cdli.earth/"]
  -f, --format       File format
                  [choices: "ndjson", "csv", "tsv", "ntriples", "bibtex", "atf"]
  -o, --output-file  Output file (outputs to stdout by default)
      --help         Show help                                         [boolean]

Example:

cdli search -q holland --fk genre --fv "Official or display" -f tsv

Programming Interface

```js const CDLI = require('cdli-api-client')

const client = new CDLI.Client('http://localhost:2354/')

// process logging client.on('log', msg => process.stderr.write(msg))

client.export(['archives', 'proveniences', 'regions' ], 'places.nt') .then(entities => { for (const { status, reason } of entities) { if (status === 'rejected') { console.error(reason) } } }) ```