ShareDoc:Search API

Attenzione: Le ricerche root /works, /instances, /items e /dates richiedono il ruolo svde-editor-base e non sono accessibili con il solo scope svde-resource-read. Un integratore di sola lettura deve usare la navigazione gerarchica.

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

• Agents whose names contains carroll
• A sublist of all agents whose name contains carroll, sorted by name and paged
• Agents typeahead search using carro
• Agents typeahead search using carto (fuzzy match)
• Agents typeahead search using carto (no fuzzy)
• Lewis Carroll

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

• People whose names contains carroll
• A sublist of all people whose name contains carroll, sorted by name and paged
• People typeahead search using carro
• People typeahead search using carto (fuzzy match)
• People typeahead search using carto (no fuzzy)
• Lewis Carroll
• Lewis Carroll's occupations
• Lewis Carroll's opuses

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

• Meetings whose names contains eaton
• Meetings typeahead search using eat
• Meetings typeahead search using iat (fuzzy match)
• Meetings typeahead search using iat (no fuzzy)
• Annual J. Lloyd Eaton Conference on Science Fiction and Fantasy Literature

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

• First 10 organisations whose name doesn't contain xyz
• A sublist of all organisations whose name doesn't contain xyz, sorted by name and paged
• Organisations typeahead search using intern
• Organisations typeahead search using intrn (fuzzy match)
• Organisations typeahead search using intrn (no fuzzy)
• American Library Association (ALA)

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

• First 10 families whose name doesn't contain xyz
• A sublist of all families whose name doesn't contain xyz, sorted by name and paged
• Families typeahead search using emili
• Families typeahead search using amili (fuzzy match)
• Families typeahead search using pirani (no fuzzy)

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.

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

• Opuses whose title contains alice
• Alice in Wonderland (Opus)
• Contributors of Alice in Wonderland
• Authors of Alice in Wonderland
• Alice in Wonderland (Works)
• Alice in Wonderland (Instances of a Work)
• Alice in Wonderland (an Instance)
• Alice in Wonderland (items of the instance above)
• Alice in Wonderland (an item from the list above)

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.

• Alice in Wonderland (Instances of a Work)
• Alice in Wonderland (an Instance)
• Alice in Wonderland (items of the instance above)
• Alice in Wonderland (an item from the list above)

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.

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

• Alice in Wonderland (an Instance)
• Alice in Wonderland (items of the instance above)
• Alice in Wonderland (an item from the list above)

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.

/items/{itemId}

Returns a specific item.

Examples

• An item, literal attributes and an object properties (availability)

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.

• Search all formats using "bo" as search criteria
• Search all occupations using "bo" as search criteria
• A format

/{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. https://en.wikipedia.org/wiki/Representational_state_transfer
2. https://www.loc.gov/bibframe/docs/bibframe2-model.html