Last edited 9 months ago
by Serena Cericola

Search API

Revision as of 15:24, 20 February 2024 by Serena Cericola (talk | contribs) (Created page with "==<span class="mw-headline">Stats</span>== The /stats endpoint returns high-level aggregations about the whole knowledge base. There's an "extended" boolean parameter which drives the response format, specifically: When it is set to false, the response is very concise, see the following example:<syntaxhighlight lang="json"> { "item": 137, "agent": { "person": 54, "organization": 16, "family": 16, "meeting": 9 }, "instance": 146, "opus": 120,...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Stats

The /stats endpoint returns high-level aggregations about the whole knowledge base. There's an "extended" boolean parameter which drives the response format, specifically:

When it is set to false, the response is very concise, see the following example:

{
  "item": 137,
  "agent": {
    "person": 54,
    "organization": 16,
    "family": 16,
    "meeting": 9
  },
  "instance": 146,
  "opus": 120,
  "work": 138,
  "subject": 103
}

The response returns the counts for each entity type. The "agent" is actually a group that contains the agent types counts. It is possible to set a request parameter called "provenance" that will cause the response to return only provenance-specific values. The response in this case has exactly the same shape but counts refer only to the requested provenance. In case the extended parameter is set to true, then the response is more articulated because counts are broken by provenance:

  "https://svde.org/agents/NLF": {
    "item": 3,
    "agent": {
      "person": 4,
      "organization": 2,
      "family": 1
    },
    "instance": 4,
    "work": 5,
    "opus": 3,
    "totalCount": 22
  },
  "https://svde.org/agents/NYU": {
    "item": 7,
    "agent": {
      "person": 4,
      "organization": 1,
      "family": 3,
      "meeting": 2
    },
    "instance": 7,
    "work": 8,
    "opus": 8,
    "totalCount": 40
  },
  "https://svde.org/agents/NORTHWESTERN": {
    "agent": {
      "person": 1,
      "meeting": 1
    },
    "instance": 1,
    "work": 2,
    "opus": 2,
    "totalCount": 7
  },
  ...

Resource

A ShareVDE resource is an abstract and high-level concept which maps agents and opuses.

/resources

Simple search across Share-VDE resources.

Request Parameters
Name Type Description Cardinality Default Value
q String An agent query expressed in SVDEQL or TermsQL (terms) 1 N.A.
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
partialMatch Boolean Forces a partial match search (entered query terms are considered optional) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

Agent

The Agent is an abstract concept which concretely maps people, organisations, conferences, families, jurisdictions, etc., that play a role (or even multiple roles) such as authors, editors, distributors, illustrator, publisher, etc.

/agents

Fulltext or Typeahead search across Share-VDE agents.

Request Parameters
Name Type Description Cardinality Default Value
q String An agent query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/agents/{agentId}

Returns the agent associated with the given identifier.

/agents/{agentId}/opuses

Returns the opuses of the agent associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 N.A.

Examples

Person

A person is an individual or identity established by an individual (either alone or in collaboration with one or more other individuals). It is a concrete subclass of Agent and provides a set of attributes, both datatype and object properties which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/people

Fulltext or Typeahead search across Share-VDE people.

Request Parameters
Name Type Description Cardinality Default Value
q String A people query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/people/{id}

Returns the agent associated with the given identifier.

/people/{id}/opuses

Returns the opuses of the person associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

/people/{id}/occupations

Returns the occupations of the person associated with the given identifier.

/people/{id}/occupations/{occupationId}

Returns the occupation (related with a specific person) associated with the given identifier.

Examples

Meeting

Gathering of individuals or representatives of various bodies for the purpose of discussing and/or acting on topics of common interest. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/meetings

Fulltext or Typeahead search across Share-VDE meetings.

Request Parameters
Name Type Description Cardinality Default Value
q String A meeting query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/meetings/{id}

Returns the meeting associated with the given identifier.

/meetings/{id}/opuses

Returns the opuses of the meeting associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

Examples

Organisation

A corporation or group of persons and/or organisations that acts, or may act, as a unit. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/organisations

Fulltext or Typeahead search across Share-VDE organisations.

Request Parameters
Name Type Description Cardinality Default Value
q String An organisation query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/organisations/{id}

Returns the organisation associated with the given identifier.

/organisations/{id}/opuses

Returns the opuses of the organisation associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

Examples

Family

Two or more persons related by birth, marriage, adoption, civil union, or similar legal status, or who otherwise present themselves as a family. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/families

Fulltext or Typeahead search across Share-VDE families.

Request Parameters
Name Type Description Cardinality Default Value
q String A family query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/families/{id}

Returns the family associated with the given identifier.

/families/{id}/opuses

Returns the opuses of the family associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

Examples

Opus

The highest level of abstraction, a Work, in the BIBFRAME context, reflects the conceptual essence of the cataloged resource: authors, languages, and what it is about[2].

/opuses

Fulltext search across Share-VDE opuses.

Request Parameters
Name Type Description Cardinality Default Value
q String An opus query expressed in SVDEQL 1 N.A.
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}

Returns the opus associated with the given identifier.

/opuses/{id}/contributors

Returns the contributors of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

/opuses/{id}/contributors/{contributorId}

Returns the contributor of a given opus.

/opuses/{id}/publications

Returns the publications of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/publications/{publicationId}

Returns a specific publication of a given opus.

/opuses/{id}/works

Returns the works of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/works/{workId}

Returns a specific work of a given opus.

/opuses/{id}/works/{workId}/instances

Returns the instances of a work of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/works/{workId}/instances/{instanceId}

Returns a specific work of a given opus.

/opuses/{id}/works/{workId}/instances/{instanceId}/items

Returns the items of an instance of a work of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/works/{workId}/instances/{instanceId}/items/{itemId}

Returns a specific item.

Examples

Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.

Work

An intermediate level of abstraction which reflects an expression of a given Opus.

/works/{id}

Returns the work associated with the given identifier.

/works/{id}/contributors

Returns the contributors of a given work.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

/works/{id}/contributors/{contributorId}

Returns the contributor of a given work.

/works/{workId}/instances

Returns the instances of a work.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/works/{workId}/instances/{instanceId}

Returns a specific work.

/works/{workId}/instances/{instanceId}/items

Returns the items of an instance of a work.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/works/{workId}/instance/{instanceId}/items/{itemId}

Returns a specific item.

Examples

Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.

Instance

A Work may have one or more individual, material embodiments, for example, a particular published form. These are Instances of the Work. An Instance reflects information such as its publisher, place and date of publication, and format[2].

/instance/{instanceId}

Returns a specific instance. The Instance entity provides a connection to the bibliographic records that contributed to its definition. Specifically, when at least one of those connections is available, the instance resource representation will contain an additional set of links under the "opac" category. Each link provides the URL and the owning provenance (code). Here's an example: 

{
  "preferredHeading": "Lewis Carroll's Alice's adventures in Wonderland",
  ...
  "_links": {
    "self": {
      "href": "https://svde.org/instances/I0001"
    },
    "opac": [
        {
            "type": "STANFORD"
            "href": "https://searchworks.stanford.edu/view/9386906"
        }, 
        ... (other opacs)
    },
    "format": {
      "href": "https://svde.org/formats/nc"
    },
    "publicationPlace": {
      "href": "https://svde.org/places/4930956"
    },
    "items": {
      "href": "https://svde.org/instances/I0001/items"
    }
  }
}

/instances/{instanceId}/items

Returns the items of an instance.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/instances/{instanceId}/items/{itemId}

Returns a specific item.

Examples

Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.

Item

An item is an actual copy (physical or electronic) of an Instance. It reflects information such as its location (physical or virtual), shelf mark, and barcode[2].

/items/{itemId}

Returns a specific item.

Examples

Publication

A publication is a logical entity which wraps together an instance (including the items) plus the parent Work. Being the instance the central entity, its local identifier is used also for denoting the corresponding publication identity (and URI)

The representation is therefore very simple as it consists of the following: 

{
  "_links": {
    "self": {
      "href": "https://share.vde.org/publications/I0003"
    },
    "instance": {
      "href": "https://share.vde.org/instances/I0003"
    },
    "work": {
      "href": "https://share.vde.org/works/401-2"
    }
  }
}

/publications

Fulltext search across Share-VDE publications.

Request Parameters
Name Type Description Cardinality Default Value
q String A publication query expressed in SVDEQL 1 N.A.
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
filter String A filter clause used for refining search results 0...n N.A.

/publications/{id}

Returns the publication associated with the given identifier.

Controlled Vocabulary Entities

Other than the entities described above, referred as "core entities", the Share-VDE domain model includes some other entities that are gathered from external sources, assigned a Share-VDE URI and linked to core entities.


IMPORTANT: at time of writing the controlled vocabulary entities do not provide any content negotiation capability. That means the available endpoints always returns JSON according to HATEOAS specs.


"format" typeahead search results: 

  "_embedded": {
    "otherLanguages": [
      {
        "language": "fra",
        "preferredHeading": "<b>Bo</b>bine de bande informatique",
        "uri": "https://svde.org/formats/ch"
      },
      {
        "language": "ita",
        "preferredHeading": "<b>Bo</b>bina di nastro per computer",
        "uri": "https://svde.org/formats/ch"
      },
      ...

A single format 

{
  "preferredHeading": "Computer tape reel",
  "comingFromSolr": true,
  "_links": {
    "self": [
      {
        "href": "http://id.loc.gov/vocabulary/carriers/ch",
        "type": "other"
      },
      {
        "href": "http://sit2-base-svde.atcult.it/formats/ch"
      }
    ]
  }
}

The list includes:

  • Format
  • Role
  • Language
  • Agent Type
  • Genre
  • Occupation
  • Availability
  • Form
  • Place
  • OpusType
  • PublicationType

Each entity of this type provide two endpoints: a collection, which provides in turn typeahead search capabilities, and a single resource endpoint.

/{resourceType}

Typeahead search across Share-VDE controlled vocabulary entity.Note that the URI uses the plural form (e.g. /languages, /occupations, /forms)

Request Parameters
Name Type Description Cardinality Default Value
q String A typeahead query expressed in TermsQL (terms) 1 N.A.
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1

/resourceType/{id}

Returns the controlled vocabulary entity associated with the given identifier. Note that the URI uses the plural form (e.g. /languages, /occupations, /forms)

---------------

  1. Jump up↑ https://en.wikipedia.org/wiki/Representational_state_transfer
  2. ↑ Jump up to:2.0 2.1 2.2 https://www.loc.gov/bibframe/docs/bibframe2-model.html
Retrieved from "https://wiki.share-vde.org/w/index.php?title=ShareDoc:Search_API&oldid=2155"