A documentId is obtained by submitting a document to the Unsilo Document API.
See https://services.unsilo.com/documentation/documents for more information on this.
Note that injected documents (documents using the documents API for submitting to UNSILO) will expire 30 days after creation. Trying to access expired or unknown documents will result in a HTTP 410 - Gone.

1. Contact information

Need help, or want to know how to access our APIs? Reach out to hello@unsilo.ai

2. Content types

All requests and responses are of type application/json in UTF-8 encoding.

3. Document Metadata

3.1. Overview

How to retrieve metadata about a specific document.

This endpoint is available for testing in our dynamic documentation.

3.1.1. Get Document Metadata

Retrieve document metadata

Endpoint

GET https://services.unsilo.com/api/metadata/v1/{contentProfile}/metadata

Request
Path parameters
Table 1. /api/metadata/v1/{contentProfile}/metadata
Parameter Description

contentProfile

Content Profile
Query string Parameters
Parameter Optional Description

doi

false

The doi’s of the document to process.
Example Request
$ curl 'https://services.unsilo.com/api/metadata/v1/partner/metadata?doi=realtime-491a1283-6ce7-440f-9c5b-fd7e0c9e6c8e' -i -u 'username:password' -X GET \
    -H 'Content-Type: application/json'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items" : [ {
    "id" : "Id",
    "doi" : "Doi",
    "concepts" : [ {
      "label" : "Label",
      "id" : "Id",
      "localScore" : 1.0
    } ],
    "title" : "Title",
    "text" : "Text",
    "authors" : [ {
      "firstName" : "First Name",
      "lastName" : "Last Name"
    } ],
    "journal" : "Journal",
    "publicationDate" : "Publication Date",
    "customFields" : {
      "Key" : "Value"
    },
    "articleType" : "Article Type",
    "calculatedType" : "Calculated Type",
    "isIndexed" : true
  } ]
}
Response fields
Path Type Description

items

Array

List of metadata results

items[]

Array

Metadata result

items[].authors[]

Array

Document authors

items[].authors[].firstName

String

Document author first name

items[].authors[].lastName

String

Document author last name

items[].concepts[]

Array

Document concepts

items[].concepts[].label

String

Concept label

items[].concepts[].localScore

Number

Concept score

items[].customFields

Object

Document custom fields

items[].doi

String

Document doi

items[].id

String

Document id

items[].journal

String

Document journal

items[].publicationDate

String

Document publication data

items[].title

String

Document title

3.1.2. Get Document Text

Retrieve document text

Endpoint

GET https://services.unsilo.com/api/metadata/v1/{contentProfile}/text

Request
Path parameters
Table 2. /api/metadata/v1/{contentProfile}/text
Parameter Description

contentProfile

Content Profile
Query string Parameters
Parameter Optional Description

documentId

false

The IDs of the document to process.
Example Request
$ curl 'https://services.unsilo.com/api/metadata/v1/partner/text?documentId=realtime-491a1283-6ce7-440f-9c5b-fd7e0c9e6c8e' -i -u 'username:password' -X GET \
    -H 'Content-Type: application/json'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "apiResponseStatus" : "SUCCESS",
  "status" : 200,
  "currentTimestamp" : "2025-04-11T14:42:56Z",
  "fulltext" : "Document text",
  "sentences" : [ "Sentence" ]
}
Response fields
Path Type Description

fulltext

String

The document fulltext

sentences[]

Array

Document sentences

4. Journal Finder

4.1. Overview

Journal Finder finds the most relevant journals for the documentId provided.

This endpoint is available for testing in our dynamic documentation.

4.1.1. Get Journals

Finds the best matching reviewers for the given document

Endpoint

GET https://services.unsilo.com/api/journalfinder/v2/{contentProfile}/journals

Request
Path parameters
Table 3. /api/journalfinder/v2/{contentProfile}/journals
Parameter Description

contentProfile

Content Profile
Query string Parameters
Parameter Optional Description

limit

false

Number of top journals which best match the text

documentId

false

The ID of the document to process. Generated by the add-document endpoint.
Example Request
$ curl 'https://services.unsilo.com/api/journalfinder/v2/partner/journals?limit=10&documentId=realtime-491a1283-6ce7-440f-9c5b-fd7e0c9e6c8e' -i -u 'username:password' -X GET \
    -H 'Content-Type: application/json'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "apiResponseStatus" : "SUCCESS",
  "status" : 200,
  "path" : "/v1/demo-medline/journals",
  "currentTimestamp" : "2020-01-03T08:32:41Z",
  "journals" : [ {
    "label" : "PloS one",
    "publisher" : {
      "name" : "Public Library of Science"
    },
    "issn" : [ {
      "issn" : "1932-6203",
      "issnType" : "Electronic"
    } ],
    "topConcepts" : [ {
      "id" : "immunoglobulinkillikreceiv",
      "label" : "Kir"
    }, {
      "id" : "celkilnat",
      "label" : "Natural Killer Cells"
    }, {
      "id" : "andcelcytoplasmdomainigimmunoglobulinkilliklongreceivtailthre",
      "label" : "Killer Cell Immunoglobulin Like Receptors"
    }, {
      "id" : "genimmunoglobulinkillikreceiv",
      "label" : "Kir Gene"
    }, {
      "id" : "celimmunoglobulinkillikreceiv",
      "label" : "Killer Cell Immunoglobulin Like Receptors"
    }, {
      "id" : "biochemreceiv",
      "label" : "Receptors"
    } ],
    "match" : {
      "match" : 93,
      "overlappingConcepts" : [ {
        "id" : "immunoglobulinkillikreceiv",
        "label" : "Killer Immunoglobulin-like Receptors"
      }, {
        "id" : "dlkir",
        "label" : "KIR2DL1"
      }, {
        "id" : "haplotyp",
        "label" : "Haplotypes"
      }, {
        "id" : "celt",
        "label" : "T Cells"
      }, {
        "id" : "actgenimmunoglobulinkillikreceiv",
        "label" : "Activating Killer Immunoglobulin-like Receptors Gene"
      } ]
    }
  } ]
}
Response fields
Path Type Description

journals

Array

List of journals

journals[].match

Object

Description of the match of the journal to the document

journals[].match.match

Number

A weighed score for how well the journal matches the document. This takes into account importance of concepts, overlap, etc.

journals[].match.overlappingConcepts[]

Array

The concepts in common between the document and the journal

journals[].match.overlappingConcepts[].id

String

The ID of the overlapping concept

journals[].match.overlappingConcepts[].label

String

The label of the overlapping concepts

journals[].label

String

Journal name

journals[].issn[]

Array

International Standard Serial Numbers (ISSN) for the journal [optional]

journals[].issn[].issn

String

The ISSN number

journals[].issn[].issnType

String

ISSN record issnType. One of [Electronic, Print, Linking, Undetermined]

journals[].publisher.name

String

Name of the journal publisher [optional]

journals[].topConcepts[].id

String

Concept id

journals[].topConcepts[].label

String

Concept label

apiResponseStatus

String

Response status - FAILED/SUCCESS

message

String

Message sent back by the service.

4.1.2. Get Journals V3

Finds the best matching reviewers for the given document

Endpoint

GET https://services.unsilo.com/api/journalfinder/v3/{contentProfile}/journals

Request
Path parameters
Table 4. /api/journalfinder/v3/{contentProfile}/journals
Parameter Description

contentProfile

Content Profile
Query string Parameters
Parameter Optional Description

limit

false

Number of top journals which best match the text

documentId

false

The ID of the document to process. Generated by the add-document endpoint.

isAbstract

true

"true" if the input document is only an abstract

title

true

If available, the document title
Example Request
$ curl 'https://services.unsilo.com/api/journalfinder/v3/partner/journals?limit=10&documentId=realtime-491a1283-6ce7-440f-9c5b-fd7e0c9e6c8e&isAbstract=true&title=Document+title' -i -u 'username:password' -X GET \
    -H 'Content-Type: application/json'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "apiResponseStatus" : "SUCCESS",
  "status" : 200,
  "path" : "/v1/demo-medline/journals",
  "currentTimestamp" : "2020-01-03T08:32:41Z",
  "journals" : [ {
    "label" : "PloS one",
    "publisher" : {
      "name" : "Public Library of Science"
    },
    "issn" : [ {
      "issn" : "1932-6203",
      "issnType" : "Electronic"
    } ],
    "topConcepts" : [ {
      "id" : "immunoglobulinkillikreceiv",
      "label" : "Kir"
    }, {
      "id" : "celkilnat",
      "label" : "Natural Killer Cells"
    }, {
      "id" : "andcelcytoplasmdomainigimmunoglobulinkilliklongreceivtailthre",
      "label" : "Killer Cell Immunoglobulin Like Receptors"
    }, {
      "id" : "genimmunoglobulinkillikreceiv",
      "label" : "Kir Gene"
    }, {
      "id" : "celimmunoglobulinkillikreceiv",
      "label" : "Killer Cell Immunoglobulin Like Receptors"
    }, {
      "id" : "biochemreceiv",
      "label" : "Receptors"
    } ],
    "match" : {
      "match" : 93,
      "overlappingConcepts" : [ {
        "id" : "immunoglobulinkillikreceiv",
        "label" : "Killer Immunoglobulin-like Receptors"
      }, {
        "id" : "dlkir",
        "label" : "KIR2DL1"
      }, {
        "id" : "haplotyp",
        "label" : "Haplotypes"
      }, {
        "id" : "celt",
        "label" : "T Cells"
      }, {
        "id" : "actgenimmunoglobulinkillikreceiv",
        "label" : "Activating Killer Immunoglobulin-like Receptors Gene"
      } ]
    }
  } ]
}
Response fields
Path Type Description

journals

Array

List of journals

journals[].match

Object

Description of the match of the journal to the document

journals[].match.match

Number

A weighed score for how well the journal matches the document. This takes into account importance of concepts, overlap, etc.

journals[].match.overlappingConcepts[]

Array

The concepts in common between the document and the journal

journals[].match.overlappingConcepts[].id

String

The ID of the overlapping concept

journals[].match.overlappingConcepts[].label

String

The label of the overlapping concepts

journals[].label

String

Journal name

journals[].issn[]

Array

International Standard Serial Numbers (ISSN) for the journal [optional]

journals[].issn[].issn

String

The ISSN number

journals[].issn[].issnType

String

ISSN record issnType. One of [Electronic, Print, Linking, Undetermined]

journals[].publisher.name

String

Name of the journal publisher [optional]

journals[].topConcepts[].id

String

Concept id

journals[].topConcepts[].label

String

Concept label

apiResponseStatus

String

Response status - FAILED/SUCCESS

message

String

Message sent back by the service.

5. Reviewer Finder

5.1. Overview

Reviewer Finder finds the most relevant reviewers for the document provided, based on the corpus knowledge base.

This endpoint is available for testing in our dynamic documentation.

5.1.1. Get Reviewers

Finds the best matching reviewers for the given document

Endpoint

GET https://services.unsilo.com/api/reviewerfinder/v2/{contentProfile}/reviewers

Request
Path parameters
Table 5. /api/reviewerfinder/v2/{contentProfile}/reviewers
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Query string Parameters
Parameter Optional Description

documentId

false

Type: String

include-reviewers-with-coi

true

Type: Boolean
Default value: false

Include reviewers where a possible conflict of interest has been found.

concept-groups-to-prioritize

true

Type: Array<Number>
Default value: The two most significant concept areas found. If only one concept area is found, this is prioritized

List of concept group id’s, specifying which concept groups to prioritize when scoring reviewers.
The found concept groups for the document as well as their id is returned in the response, and can be used in this filter.
A maximum of 2 concept groups can be prioritized.

ignore-found-concept-groups-in-scoring

true

Type: Boolean
Default value: false

This filter can be used, if the found concept groups should be ignored when scoring the reviewers.In that case the reviewers will be scored based on the concepts in the document, without any grouping of concepts.

must-have-published-within-years

true

Type: Number
Default value: 5

Reviewers returned must have published a related document within the last n years.

min-years-of-experience

true

Type: Number
Default value: 0

Reviewers returned must have at least n years of experience.

max-years-of-experience

true

Type: Number
Default value: 100

Reviewers returned can have at most n years of experience.

limit

true

Type: Number
Default value: 100

Number of reviewers to return, the maximum number returned is 20.
Example Request
$ curl 'https://services.unsilo.com/api/reviewerfinder/v2/contentProfile/reviewers?documentId=realtime-5aa9bfc3-5ccb-48b7-a95e-fa400c622adb&limit=10&include-reviewers-with-coi=true&must-have-published-within-years=5&min-years-of-experience=0&max-years-of-experience=100&ignore-found-concept-groups-in-scoring=false&concept-groups-to-prioritize=0' -i -u 'username:password' -X GET \
    -H 'Content-Type: application/json'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "apiResponseStatus" : "SUCCESS",
  "status" : 200,
  "conceptGroups" : [ {
    "id" : 0,
    "prioritized" : true,
    "title" : "Social Media Usage",
    "concepts" : [ {
      "label" : "Social Media Presence"
    }, {
      "label" : "Facebook Page"
    } ]
  }, {
    "id" : 1,
    "prioritized" : false,
    "title" : "Dentists",
    "concepts" : [ {
      "label" : "Dental Professionals"
    }, {
      "label" : "Dental Anxiety"
    } ]
  } ],
  "reviewers" : [ {
    "coveredConcepts" : [ {
      "label" : "Social Media Usage"
    }, {
      "label" : "Dentists"
    } ],
    "conceptGroupCoverage" : [ {
      "conceptGroupId" : 0,
      "coverage" : 0.66
    }, {
      "conceptGroupId" : 1,
      "coverage" : 0.33
    } ],
    "personInfo" : {
      "currentAffiliations" : [ {
        "affiliation" : "Department of Health Informatics, College of Public Health and Health Informatics, King Saud Bin Abdul-Aziz University for Health Sciences, King Abdullah International Medical Research Center (KAIMRC), Riyadh, Saudi Arabia, Ministry of National Guard Health Affairs, Riyadh, Saudi Arabia",
        "countryCode" : "SAU",
        "countryName" : "Saudi Arabia"
      } ],
      "currentEmail" : {
        "email" : "dummy@gmail.com"
      },
      "name" : {
        "firstName" : "John M.",
        "lastName" : "Johnson",
        "fullName" : "John M. Johnson"
      }
    },
    "publishingInfo" : {
      "relatedInfo" : {
        "favoriteJournal" : {
          "journal" : {
            "name" : "Studies in health technology and informatics"
          },
          "numberOfPublishedPapersInJournal" : 11
        },
        "papersPublished" : 15,
        "hIndex" : 12,
        "yearsOfExperience" : {
          "proposedLabel" : "7+",
          "years" : 7
        },
        "latestPublication" : {
          "publicationDate" : "2018-02-13",
          "journal" : {
            "name" : "Computer methods and programs in biomedicine"
          }
        },
        "authorContribution" : {
          "firstAuthor" : 3,
          "middleAuthor" : 2,
          "lastAuthor" : 1
        }
      }
    },
    "paperEvidence" : [ {
      "doi" : "10.1016/j.cmpb.2018.03.005",
      "journal" : {
        "name" : "Computer methods and programs in biomedicine"
      },
      "publicationDate" : "2018-01-11",
      "title" : "The impact of social media - based support groups on smoking relapse prevention in Saudi Arabia",
      "authors" : [ {
        "name" : {
          "firstName" : "Hamidi Al",
          "lastName" : "Onezi",
          "fullName" : "Hamidi Al Onezi"
        }
      } ]
    } ],
    "conflictsOfInterest" : [ {
      "type" : "COAUTHOR",
      "title" : "The prevalence and usage of mobile health applications among mental health patients in Saudi Arabia",
      "coAuthor" : {
        "name" : {
          "firstName" : "Nora",
          "lastName" : "Atallah",
          "fullName" : "Nora Atallah"
        }
      },
      "doi" : "10.1016/j.cmpb.2017.12.002"
    }, {
      "type" : "AFFILIATION",
      "affiliation" : {
        "affiliation" : "Department of Health Informatics, College of Public Health and Health Informatics, King Saud Bin Abdul-Aziz University for Health Sciences, King Abdullah International Medical Research Center (KAIMRC), Riyadh, Saudi Arabia, Ministry of National Guard Health Affairs, Riyadh, Saudi Arabia",
        "countryCode" : "SAU",
        "countryName" : "Saudi Arabia"
      }
    } ],
    "matchQuality" : {
      "matchQuality" : "excellent match",
      "sortingNumber" : 300
    }
  } ]
}
Response fields
Path Type Description

conceptGroups

Array

List of concept groups found in document.
Sorted after relevance in the document.

reviewers

Array

List of reviewers.
Sorted after match quality.

conceptGroups[].id

Number

Id

conceptGroups[].prioritized

Boolean

Shows if the group was prioritized when scoring reviewers.

conceptGroups[].title

String

Group title

conceptGroups[].concepts[]

Array

Concepts in group.
Sorted after relevance in document.

conceptGroups[].concepts[].label

String

Concept label

reviewers[].matchQuality

Object

Object containing information about the quality of the reviewer match.

reviewers[].coveredConcepts

Array

List of document concepts covered by the reviewer. Sorted after relevance in document.

reviewers[].conceptGroupCoverage

Array

List of objects containing information on how well the reviewer covers the found concept groups.

reviewers[].personInfo

Object

Object containing the reviewers personal information.

reviewers[].paperEvidence

Array

List of related papers authored by the reviewer. (Max 5 is returned)

reviewers[].conflictsOfInterest

Array

List of possible conflict of interests found. An empty list is returned, if no conflicts of interest were found for the reviewer.

reviewers[].publishingInfo

Object

Object containing information about the reviewers published papers.

reviewers[].matchQuality.sortingNumber

Number

Number representation of the match quality, which can be used for sorting.
(Values:
good match = 100,
great match = 200,
excellent match = 300)

reviewers[].matchQuality.matchQuality

String

String description of the match quality.
(Values: good match, great match, excellent match)

reviewers[].coveredConcepts[].label

String

Concept label

reviewers[].conceptGroupCoverage[].conceptGroupId

Number

Concept group id.

reviewers[].conceptGroupCoverage[].coverage

Number

Decimal value from 0-1, indicating how well the reviewer covers the concept group/

reviewers[].personInfo.currentAffiliations

Array

List of objects containing the reviewers current affiliations/

reviewers[].personInfo.currentEmail

Object

Object containing the reviewers current email.

reviewers[].personInfo.name

Object

Object containing the reviewers name.

reviewers[].personInfo.currentAffiliations[].affiliation

String

The affiliation.

reviewers[].personInfo.currentAffiliations[].countryName

String

The found country of the affiliation.

reviewers[].personInfo.currentAffiliations[].countryCode

String

The found ISO 3166 - 3 digit - country code of the affiliation

reviewers[].personInfo.currentEmail.email

String

The email.

reviewers[].personInfo.name.firstName

String

The first name.

reviewers[].personInfo.name.lastName

String

The last name.

reviewers[].personInfo.name.fullName

String

The full name

reviewers[].publishingInfo.relatedInfo

Object

Object containing information based on related papers published by the reviewer.

reviewers[].publishingInfo.relatedInfo.favoriteJournal

Object

The journal with most published papers by the reviewer.

reviewers[].publishingInfo.relatedInfo.papersPublished

Number

Number of papers published.

reviewers[].publishingInfo.relatedInfo.hIndex

Number

Unsilo hIndex.

reviewers[].publishingInfo.relatedInfo.yearsOfExperience

Object

Years of experience.

reviewers[].publishingInfo.relatedInfo.latestPublication

Object

Latest publication.

reviewers[].publishingInfo.relatedInfo.favoriteJournal.journal

Object

The journal.

reviewers[].publishingInfo.relatedInfo.favoriteJournal.numberOfPublishedPapersInJournal

Number

Number of documents published in the journal.

reviewers[].publishingInfo.relatedInfo.favoriteJournal.journal.name

String

Name of the journal.

reviewers[].publishingInfo.relatedInfo.yearsOfExperience.proposedLabel

String

Proposed label.

reviewers[].publishingInfo.relatedInfo.yearsOfExperience.years

Number

Years of experience.

reviewers[].publishingInfo.relatedInfo.latestPublication.publicationDate

String

The publication date of the latest publication.

reviewers[].publishingInfo.relatedInfo.latestPublication.journal

Object

The journal the latest publication was published in.

reviewers[].publishingInfo.relatedInfo.latestPublication.journal.name

String

Name of the journal.

reviewers[].publishingInfo.relatedInfo.authorContribution.firstAuthor

Number

Number of related publications where author is first author.

reviewers[].publishingInfo.relatedInfo.authorContribution.middleAuthor

Number

Number of related publications where author is middle author.

reviewers[].publishingInfo.relatedInfo.authorContribution.lastAuthor

Number

Number of related publications where author is last author.

reviewers[].paperEvidence[].doi

String

Paper DOI.

reviewers[].paperEvidence[].journal

Object

The journal the paper was published in.

reviewers[].paperEvidence[].publicationDate

String

The publication date of the paper.

reviewers[].paperEvidence[].title

String

The title of the paper.

reviewers[].paperEvidence[].authors

Array

List containing the authors of the paper.

reviewers[].paperEvidence[].journal.name

String

Name of the journal.

reviewers[].paperEvidence[].authors[].name

Object

Name of the author.

reviewers[].paperEvidence[].authors[].name.firstName

String

The first name.

reviewers[].paperEvidence[].authors[].name.lastName

String

The last name.

reviewers[].paperEvidence[].authors[].name.fullName

String

The full name

reviewers[].conflictsOfInterest[].title

String

The title of the document causing the possible conflict of interest. (Only returned when type = COAUTHOR)

reviewers[].conflictsOfInterest[].doi

String

The doi of the document causing the possible conflict of interest. (Only returned when type = COAUTHOR)

reviewers[].conflictsOfInterest[].type

String

Two types of coi is supported, COAUTHOR and AFFILIATION

reviewers[].conflictsOfInterest[].coAuthor

Object

The coauthor of the document, with whom the reviewer has a possible conflict of interest. (NOTE: currently only returned when type = COAUTHOR)

reviewers[].conflictsOfInterest[].affiliation

Object

The affiliation causing the possible conflict of interest. (Only returned when type = AFFILIATION)

reviewers[].conflictsOfInterest[].affiliation.affiliation

String

The affiliation.

reviewers[].conflictsOfInterest[].affiliation.countryName

String

The found country of the affiliation.

reviewers[].conflictsOfInterest[].affiliation.countryCode

String

The found ISO 3166 - 3 digit - country code of the affiliation

reviewers[].conflictsOfInterest[].coAuthor.name

Object

Name of the author.

reviewers[].conflictsOfInterest[].coAuthor.name.firstName

String

The first name.

reviewers[].conflictsOfInterest[].coAuthor.name.lastName

String

The last name.

reviewers[].conflictsOfInterest[].coAuthor.name.fullName

String

The full name

apiResponseStatus

String

Response status - FAILED/SUCCESS

message

String

Message sent back by the service.

6. Concepts

6.1. Overview

6.1.1. Get Concepts From a Text

Extract concepts for a given text, based on a corpus-specific dictionary.

Endpoint

POST https://services.unsilo.com/api/concepts/v1/{contentProfile}/concepts-from-text

Request
Path parameters
Table 6. /api/concepts/v1/{contentProfile}/concepts-from-text
Parameter Description

contentProfile

Content Profile
Example request body
Adjuvant cytokine-induced killer (CIK) cells treatment.
Example Request
$ curl 'https://services.unsilo.com/api/concepts/v1/your_provided_content_profile/concepts-from-text' -i -u 'username:password' -X POST \
    -H 'Content-Type: text/plain' \
    -d 'Adjuvant cytokine-induced killer (CIK) cells treatment.'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "concepts" : [ {
    "id" : "cytokininduckil",
    "label" : "Cytokine-induced Killer",
    "weight" : 0.6931471805599453
  }, {
    "id" : "celtre",
    "label" : "Cell Treatments",
    "weight" : 0.4054651081081644
  } ]
}
Response fields
Path Type Description

concepts

Array

List of concepts

concepts[].id

String

Concept id

concepts[].label

String

Concept text

concepts[].weight

Number

Concept weight, indicating it’s estimated importance, in relation to the other concepts returned.

6.1.2. Get Concepts From a File

Endpoint

POST https://services.unsilo.com/api/concepts/v1/{contentProfile}/concepts-from-file

Request
Path Parameters
Table 7. /api/concepts/v1/{contentProfile}/concepts-from-file
Parameter Description

contentProfile

Content Profile
Multipart Form Parameters
Part Description

file

The file containing the document to analyze

Max file size: 10MB

Supported MIME types include:
- application/x-pdf (.pdf)
- application/pdf (.pdf)
- application/msword (.doc)
- application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)
- text/plain (.txt)
Example Request
$ curl 'https://services.unsilo.com/api/concepts/v1/your_provided_content_profile/concepts-from-file' -i -u 'username:password' -X POST \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@some-file.txt;type=text/plain'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "concepts" : [ {
    "id" : "cytokininduckil",
    "label" : "Cytokine-induced Killer",
    "weight" : 0.6931471805599453
  }, {
    "id" : "celtre",
    "label" : "Cell Treatments",
    "weight" : 0.4054651081081644
  } ]
}
Response fields
Path Type Description

concepts

Array

List of concepts

concepts[].id

String

Concept id

concepts[].label

String

Concept text

concepts[].weight

Number

Concept weight, indicating it’s estimated importance, in relation to the other concepts returned.

7. Autocompletion Suggestors

7.1. Overview

Autocompletion suggestors are available for testing in our dynamic documentation.

7.1.1. Suggestions

Finds the best matching autocompletion suggestions given a string

Endpoint

POST https://services.unsilo.com/api/suggestions/v1/{contentProfile}/search

Request
Path parameters
Table 8. /api/suggestions/v1/{contentProfile}/search
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Query string Parameters
Parameter Optional Description

limit

true

Type: Number
Default value: 20

Number of suggestions to return, for each type. The maximum limit is 50

queryTerm

false

Type: String
Term to base the autocomplete suggestions on. If the length of the term is less than 3, an empty set of suggestions will be returned
Request body
Path Optional Type Description

suggestionTypes

true

List<TYPE>

TYPE is an enum, the supported types are:
CONCEPT
AUTHOR
JOURNAL

Defaults to all three types

blacklistedItems

true

Map<TYPE, List<IDs>

Here it is possible, for each of the types, to give a list of ids, which should be blacklisted
The maximum size of each list is 50

Defaults to the empty lists

searchInAlternateConceptLabels

true

Boolean

Specifies whether concept suggestions are based on the main labels, or also includes alternate concept labels.

Defaults to false
Example Request
$ curl 'https://services.unsilo.com/api/suggestions/v1/contentProfile/search?limit=10&queryTerm=ped' -i -u 'username:password' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "suggestionTypes": [
    "CONCEPT","AUTHOR","JOURNAL"
  ],
  "blacklistedItems": {
    "CONCEPT": [
      "patypedy"
    ],
    "AUTHOR": [
      "Pedro Marques-Vidal"
    ],
    "JOURNAL": [
      "Pediatric blood & cancer"
    ]
  }
}'
Response
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "suggestions" : {
    "JOURNAL" : [ {
      "type" : "JOURNAL",
      "value" : "Pediatrics",
      "splitValue" : [ {
        "type" : "MATCH",
        "text" : "Ped"
      }, {
        "type" : "TEXT",
        "text" : "iatrics"
      } ],
      "entity" : {
        "label" : "Pediatrics",
        "id" : "Pediatrics"
      }
    }, {
      "type" : "JOURNAL",
      "value" : "Pediatric research",
      "splitValue" : [ {
        "type" : "MATCH",
        "text" : "Ped"
      }, {
        "type" : "TEXT",
        "text" : "iatric research"
      } ],
      "entity" : {
        "label" : "Pediatric research",
        "id" : "Pediatric research"
      }
    } ],
    "CONCEPT" : [ {
      "type" : "CONCEPT",
      "value" : "Pedicle",
      "splitValue" : [ {
        "type" : "MATCH",
        "text" : "Ped"
      }, {
        "type" : "TEXT",
        "text" : "icle"
      } ],
      "entity" : {
        "label" : "Pedicle",
        "id" : "pedicel"
      }
    }, {
      "type" : "CONCEPT",
      "value" : "Pediatric Population",
      "splitValue" : [ {
        "type" : "MATCH",
        "text" : "Ped"
      }, {
        "type" : "TEXT",
        "text" : "iatric Population"
      } ],
      "entity" : {
        "label" : "Pediatric Population",
        "id" : "pedypop"
      }
    } ],
    "AUTHOR" : [ {
      "type" : "AUTHOR",
      "value" : "Pedro R Lowenstein",
      "splitValue" : [ {
        "type" : "MATCH",
        "text" : "Ped"
      }, {
        "type" : "TEXT",
        "text" : "ro R Lowenstein"
      } ],
      "entity" : {
        "label" : "Pedro R Lowenstein",
        "id" : "Pedro R Lowenstein"
      }
    }, {
      "type" : "AUTHOR",
      "value" : "Pedro W Crous",
      "splitValue" : [ {
        "type" : "MATCH",
        "text" : "Ped"
      }, {
        "type" : "TEXT",
        "text" : "ro W Crous"
      } ],
      "entity" : {
        "label" : "Pedro W Crous",
        "id" : "Pedro W Crous"
      }
    } ]
  }
}
Response fields
Path Type Description

suggestions

Map<TYPE, List<Suggestions>>

A map containing suggestions for each requested TYPE

suggestions.JOURNAL

List<Suggestions>

The list of journal suggestions

suggestions.JOURNAL[].type

TYPE

The TYPE of the suggestion

suggestions.JOURNAL[].value

String

The matched value of the entity

suggestions.JOURNAL[].splitValue

Array

An array of tokens

suggestions.JOURNAL[].entity

Object

The matched entity

suggestions.JOURNAL[].entity.id

String

Id of the matched entity

suggestions.JOURNAL[].entity.label

String

Main label of the matched entity

suggestions.JOURNAL[].splitValue[].type

String

The type of the token - possible types: MATCH and TEXT.
MATCH is the matched part of the string.
TEXT is the autocompletion suggestion

suggestions.JOURNAL[].splitValue[].text

String

The text of the token

8. Facets

8.1. Overview

The facets endpoint is available for testing in our dynamic documentation.

8.1.1. Facets

Returns the available facets for the given content profile

Endpoint

GET https://services.unsilo.com/api/related/v3/{contentProfile}/facets

Request
Path parameters
Table 9. /api/related/v3/{contentProfile}/facets
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Example Request
$ curl 'https://services.unsilo.com/api/related/v3/contentProfile/facets' -i -u 'username:password' -X GET
Response
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json

{
  "facets" : [ {
    "name" : "authorName",
    "type" : "STRING"
  }, {
    "name" : "journalName",
    "type" : "STRING"
  }, {
    "name" : "publicationDate",
    "type" : "DATE"
  } ]
}
Response fields
Path Type Description

facets

List<Facet>

List of facets available for the given content profile

facets[].name

String

Name of the facet

facets[].type

Enum

Type of the facet.
Current types are:
STRING - id
LONG - long value
DOUBLE - double value
BOOLEAN - true/false
DATE - <fromDate>:<toDate>
fromDate included, toDate excluded
Date format: yyyy-MM-dd
If only fromDate or toDate is wanted, an empty string can be used for the other date.

9. Search

9.1. Overview

The search endpoint is available for testing in our dynamic documentation.

9.1.1. Search

Returns the best matching documents from the backing corpus

Endpoint

GET https://services.unsilo.com/api/related/v3/{contentProfile}/search

Request
Path parameters
Table 10. /api/related/v3/{contentProfile}/search
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Query string Parameters
Parameter Optional Description

count

true

Type: Integer
Default value: 10

Number of related documents to return.

offset

true

Type: Integer
Default value: 0

Number of documents to skip - used for pagination.

sort

true

Type: Enum
Default value: recency

Decides how the matching documents should be sorted.
Possible values:
recency
relevance

OBS All boost factors are only affecting the sort order, when using relevance.

includeAbstract

true

Type: Boolean
Default value: False

Indicates whether the returned documents, should contain an abstract of the document.
Request body
Path Optional Type Description

aggregations

true

List<Aggregation>

List of aggregations to return.

facetFilters

true

List<FacetFilter>

List of facet filters to apply.

facetBoosters

true

List<FacetBooster>

List of facet boosters to apply.

queryAsString

true

String

Format of querystring {conceptId:boost} OPERATOR {conceptId:boost}
Example: {357:1.0} AND {983:2.0}.
A maximum of 100 different concepts can be included in the query.
Supported operators:
AND, OR, NOT, &&, ||, !
Operators should be surrounded by whitespace ie ' AND '.
Evaluation order of operators NOT > AND > OR.
Evaluation orders can be forced using parentheses.
OBS If both queryAsObject and queryAsString are provided, only queryAsObject is used.

queryAsObject

true

QueryObject

Query as json object.
A maximum of 100 different concepts can be included in the query.
OBS If both queryAsObject and queryAsString are provided, only queryAsObject is used.

aggregations[].facetName

false

String

Name of the facet
A list of available facets, can be retrieved through our Facets-endpoint

aggregations[].limit

true

Integer

Number of hits to return.
Default value: 10
Max value: 50

aggregations[].facetFilter

true

String

A string used as a prefix filter, on the returned aggregations.
This field is only supported for facets of type String.
Facet information can be retrieved through our Facets-endpoint.

aggregations[].aggType

true

Enum

Allows sorting aggregations by count or top hits.
Available Types: COUNT, TOP_HITS_SUM.
Default value: COUNT

facetFilters[].facetName

false

String

Name of the facet
A list of available facets, can be retrieved through our Facets-endpoint

facetFilters[].values

false

List<String>

List of facet values.
Format depends on the facet type.
Common for all facet types, is that a single value 'ALL' can be used, to dictate the field as required.
Facet information can be retrieved through our Facets-endpoint.

facetFilters[].type

true

Enum

Available Types:
POSITIVE, NEGATIVE.
OBS If no value is provided, it is set to POSITIVE by default

facetBoosters[].facetName

false

String

Name of the facet
A list of available facets, can be retrieved through our Facets-endpoint

facetBoosters[].value

false

String

Facet value.
Format depends on the facet type.
Facet information can be retrieved through our Facets-endpoint.

facetBoosters[].boost

true

Float

Default value: 1.0

queryAsObject.operator

true

Enum

Boolean operator.
Available operators:
AND, OR
OBS If the query consists of a single concept, no operator is needed, otherwise it is required.

queryAsObject.concepts

true

List<Concepts>

List of concepts.

queryAsObject.concepts[].id

false

String

Concept id.

queryAsObject.concepts[].boost

true

Float

Default value: 1.0

queryAsObject.concepts[].negatedMatch

true

Boolean

Default value: False
Indicates whether it should be a positive or negative match.

queryAsObject.subExpressions

true

List<QueryObject>

List of nested QueryObjects.

queryAsObject.negatedSubExpressions

true

List<QueryObject>

List of negated nested QueryObjects.
Example Request
$ curl 'https://services.unsilo.com/api/related/v3/contentProfile/search?count=10&offset=0&sort=recency&includeAbstract=true' -i -u 'username:password' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
    "aggregations": [
        {
            "facetName": "journalName",
            "limit": 2,
            "facetFilter": "American journal",
            "aggType": "TOP_HITS_SUM"
        }
    ],
    "facetBoosters": [
        {
            "boost": 300.0,
            "facetName": "authorName",
            "value": "Shaneda Warren Andersen"
        }
    ],
    "facetFilters": [
        {
            "facetName": "journalName",
            "values": [
                "American Journal of Epidemiology",
                "Journal of Database Management"
            ],
            "type": "NEGATIVE"
        },
        {
            "facetName": "publicationDate",
            "values": [
                "2015-01-01:2020-01-01"
            ]
        }
    ],
    "queryAsObject": {
        "concepts": [
            {
                "boost": 1.0,
                "id": "42949678852",
                "negatedMatch": false
            },
            {
                "boost": 2.0,
                "id": "32337",
                "negatedMatch": false
            }
        ],
        "negatedSubExpressions": [
            {
                "concepts": [
                    {
                        "boost": 1.0,
                        "id": "51539628392",
                        "negatedMatch": true
                    },
                    {
                        "boost": 3.0,
                        "id": "326417519825",
                        "negatedMatch": false
                    }
                ],
                "negatedSubExpressions": [],
                "operator": "OR",
                "subExpressions": []
            }
        ],
        "operator": "AND",
        "subExpressions": []
    },
    "queryAsString": "{42949678852:1.0} AND {32337:2.0} AND NOT (NOT {51539628392:1.0} OR {326417519825:3.0})"
}'
Response
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json

{
  "totalHits" : 342,
  "documents" : [ {
    "id" : "some_id",
    "doi" : "some_doi",
    "title" : "some_title",
    "journal" : "some_journal",
    "publicationDate" : "2019-08-14",
    "abstractText" : "some_abstract",
    "authors" : [ {
      "firstName" : "John",
      "lastName" : "Doe"
    } ],
    "customFields" : {
      "custom_1" : "value_1"
    },
    "concepts" : [ {
      "id" : "some_id",
      "label" : "some_label",
      "corpusLabel" : "some_corpus_label"
    } ],
    "matchedQueryConcepts" : [ {
      "id" : "some_id",
      "corpusLabel" : "some_corpus_label"
    } ]
  } ],
  "aggregations" : [ {
    "facetName" : "journalName",
    "buckets" : [ {
      "label" : "American Journal of Epidemiology",
      "key" : "American Journal of Epidemiology",
      "docCount" : 24
    } ]
  } ]
}
Response fields
Path Type Description

aggregations

List<AggregationResult>

List of aggregation results.

documents

List<Document>

List of documents returned.

totalHits

Integer

Total amount of matching documents.

aggregations[].facetName

String

The name of the facet.

aggregations[].buckets

List<Bucket>

List of buckets.

aggregations[].buckets[].label

String

Label of the bucket.

aggregations[].buckets[].key

String

The bucket key, which can be used in facet filters and facet boosters.

aggregations[].buckets[].docCount

Integer

The number of documents, the bucket entity has been found in.

documents[].id

String

Document id.

documents[].doi

String

Document doi.

documents[].title

String

Document title.

documents[].journal

String

Document journal.

documents[].publicationDate

Date

Document publication date.

documents[].abstractText

String

Document abstract.

documents[].authors

List<Author>

List of document authors.

documents[].customFields

Map<String,String>

Map of custom values. This is a map, containing custom values, which can be provided when getting a corpus processed.

documents[].concepts

List<Concept>

List of document concepts. Top 15 concepts for each document are returned.

documents[].matchedQueryConcepts

List<MatchedQueryConcept>

List of query concepts, which are found in the document.

documents[].authors[].firstName

String

Authors first name

documents[].authors[].lastName

String

Authors last name

documents[].concepts[].id

String

Concept id.

documents[].concepts[].label

String

Concept document label.

documents[].concepts[].corpusLabel

String

Concept corpus label.

documents[].matchedQueryConcepts[].id

String

Id of query concept found in document.

documents[].matchedQueryConcepts[].corpusLabel

String

Corpus label of query concept found in document.

10. Related by concepts

10.1. Overview

The search endpoint is available for testing in our dynamic documentation.

10.1.1. Search

Given a set of concepts and weights, this endpoint returns the best matching documents from the backing corpus

Endpoint

POST https://services.unsilo.com/api/related/v3/{contentProfile}/by-concepts

Request
Path parameters
Table 11. /api/related/v3/{contentProfile}/by-concepts
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Query string Parameters
Parameter Optional Description

count

true

Type: Integer
Default value: 10

Number of related documents to return.

includeAbstract

true

Type: Boolean
Default value: False

Indicates whether the returned documents, should contain an abstract of the document.
Request body
Path Optional Type Description

concepts

true

List<Concept>

List of concepts

concepts[].id

false

String

Concept id

concepts[].weight

true

Float

Concept weight
Example Request
$ curl 'https://services.unsilo.com/api/related/v3/contentProfile/by-concepts?count=10&includeAbstract=true' -i -u 'username:password' -X POST \
    -H 'Content-Type: application/json' \
    -d '{ "concepts": [
  {
    "id": "breastcant",
    "weight": 2.0
  },
  {
    "id": "cantnosolog",
    "weight": 1.5
  }
]}'
Response
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json

{
  "hits" : [ {
    "document" : {
      "id" : "some_id",
      "doi" : "some_doi",
      "title" : "some_title",
      "journal" : "some_journal",
      "publicationDate" : "2017-11-22",
      "authors" : [ {
        "firstName" : "John",
        "lastName" : "Doe"
      } ],
      "score" : 31.16651
    },
    "concepts" : [ {
      "label" : "some_label",
      "id" : "some_id"
    } ]
  } ]
}
Response fields
Path Type Description

hits

List<Hit>

List of hits.

hits[].document

Document

Info about the matching document.

hits[].concepts

List<Concept>

Top 15 concepts from the matching document.

hits[].concepts[].id

String

Concept id.

hits[].concepts[].label

String

Concept label.

hits[].document.id

String

Document id.

hits[].document.doi

String

Document doi.

hits[].document.title

String

Document title.

hits[].document.journal

String

Document journal.

hits[].document.publicationDate

String

The publication date of the document.

hits[].document.score

Float

Document relevance score.

hits[].document.authors

List<Author>

List of document authors.

hits[].document.authors[].firstName

String

Authors first name.

hits[].document.authors[].lastName

String

Authors last name.

11. Related by user profile

11.1. Overview

The search endpoint is available for testing in our dynamic documentation.

11.1.1. Articles and Books

Retrieves article and book recommendations, based on a user profile.

Endpoint

POST https://services.unsilo.com/api/related/v3/{contentProfile}/related-books-and-articles-by-user-profile

Request
Path parameters
Table 12. /api/related/v3/{contentProfile}/related-books-and-articles-by-user-profile
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Query string Parameters
Parameter Optional Description

bookSize

true

Type: Integer
Default value: 10

Number of book recommendations to return.

articleSize

true

Type: Integer
Default value: 10

Number of article recommendations to return.

includeEvidence

true

Type: Boolean
Default value: False

Indicates whether evidence should be included for the returned recommendations.
If false, only article/book ids will be returned.
The endpoint will return faster, if includeEvidence is false.

includePreprint

true

Type: Boolean
Default value: False

Indicates whether preprint should be included for the returned recommendations.
If true, only preprint articles/book ids will be returned
Request body
Path Optional Type Description

documents

true

List<Document>

List of documents. Ie. the users click history
A maximum of 40 documents can be provided.

favouriteDocuments

true

List<Document>

List of favourite documents. Ie. the users bookmarked documents.
A maximum of 40 favourite documents can be provided.

documentsToExclude

true

List<Document>

List of documents to exclude from the resultset.
Ie the last x documents the user have seen/been presented for.
A maximum of 500 documents to exclude can be provided.

timeIntervalBooks

true

DateRangeObject

Publication date filter on the books in the response.
If no interval is provided, books from the last 5 years will be returned.

timeIntervalArticles

true

DateRangeObject

Publication date filter on the articles in the response.
"If no interval is provided, articles from the last 5 years will be returned.

documents[].id

true

String

Document id.
(Article ids are supported.)

documents[].doi

true

String

Document DOI.
DOI is ignored, if id is specified.
(Article DOI’s are supported.)

favouriteDocuments[].id

true

String

Document id.
(Article ids are supported.)

favouriteDocuments[].doi

true

String

Document DOI.
DOI is ignored, if id is specified.
(Article DOI’s are supported.)

documentsToExclude[].id

true

String

Document id.
(Both book and article ids are supported.)

documentsToExclude[].doi

true

String

Document DOI.
DOI is ignored, if id is specified.
(Both book and article DOI’s are supported.)

timeIntervalBooks.from

true

Date

From date (incl) - format: yyyy-MM-dd

timeIntervalBooks.to

true

Date

To date (excl) - format: yyyy-MM-dd

timeIntervalArticles.from

true

Date

From date (incl) - format: yyyy-MM-dd

timeIntervalArticles.to

true

Date

To date (excl) - format: yyyy-MM-dd
Example Request
$ curl 'https://services.unsilo.com/api/related/v3/contentProfile/related-books-and-articles-by-user-profile?bookSize=10&articleSize=10&includeEvidence=true&includePreprint=false' -i -u 'username:password' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "documents": [
    {
      "id": "docId_a"
    },
    {
      "doi": "docDOI_e"
    }
  ],
  "documentsToExclude": [
    {
      "id": "docId_b"
    },
    {
      "doi": "docDOI_f"
    }
  ],
  "favouriteDocuments": [
    {
      "id": "docId_c"
    },
    {
      "doi": "docDOI_g"
    }
  ],
  "timeIntervalArticles": {
    "from": "2018-01-01",
    "to": "2020-05-30"
  },
  "timeIntervalBooks": {
    "from": "2016-01-01",
    "to": "2020-05-30"
  }
}'
Response
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json

{
  "recommendations" : {
    "BOOK" : [ {
      "id" : "some_book_id",
      "title" : "book_title",
      "publicationDate" : "2017-11-01",
      "evidenceDocuments" : [ {
        "id" : "docId_a",
        "doi" : "docId_a_DOI",
        "title" : "docId_a_title",
        "journal" : "docId_a_journal"
      } ]
    } ],
    "ARTICLE" : [ {
      "id" : "some_article_id",
      "doi" : "some_article_DOI",
      "title" : "article_title",
      "journal" : "article_journal",
      "publicationDate" : "2019-11-01",
      "evidenceDocuments" : [ {
        "id" : "docId_b",
        "doi" : "docId_b_DOI",
        "title" : "docId_b_title",
        "journal" : "docId_b_journal"
      }, {
        "id" : "docId_e",
        "doi" : "docDOI_e",
        "title" : "docId_e_title",
        "journal" : "docId_e_journal"
      } ]
    } ]
  }
}
Response fields
Path Type Description

recommendations

Map<Type, List<Recommendation>

Map containing recommendations.
Current recommendation types:
ARTICLE
BOOK

recommendations.ARTICLE

RecommendationType

Recommendations of type article.

recommendations.BOOK

RecommendationType

Recommendations fo type book.

recommendations.ARTICLE[].id

String

Document id.

recommendations.ARTICLE[].doi

String

Document DOI.

recommendations.ARTICLE[].title

String

Document title.

recommendations.ARTICLE[].journal

String

Document journal.

recommendations.ARTICLE[].publicationDate

Date

Document publication date.
format: yyyy-MM-dd

recommendations.ARTICLE[].evidenceDocuments

List<EvidenceDocument>

A list containing up to 5 documents from the request, acting as evidence for the suggested document.

recommendations.ARTICLE[].evidenceDocuments[].id

String

Document id.

recommendations.ARTICLE[].evidenceDocuments[].doi

String

Document DOI.

recommendations.ARTICLE[].evidenceDocuments[].title

String

Document title.

recommendations.ARTICLE[].evidenceDocuments[].journal

String

Document journal.

recommendations.BOOK[].id

String

Book id.

recommendations.BOOK[].title

String

Book title.

recommendations.BOOK[].publicationDate

Date

Book publication date.
format: yyyy-MM-dd

recommendations.BOOK[].evidenceDocuments

List<EvidenceDocument>

A list containing up to 5 documents from the request, acting as evidence for the suggested book.

recommendations.BOOK[].evidenceDocuments[].id

String

Document id.

recommendations.BOOK[].evidenceDocuments[].doi

String

Document DOI.

recommendations.BOOK[].evidenceDocuments[].title

String

Document title.

recommendations.BOOK[].evidenceDocuments[].journal

String

Document journal.

11.1.2. Articles and Books (Batch)

Retrieves article and book recommendations, for a set of users, based on their profiles.
NOTE: It is not possible to call multiple batch requests concurrently.

Endpoint

POST https://services.unsilo.com/api/related/v3/{contentProfile}/related-books-and-articles-by-user-profile-batch

Request
Path parameters
Table 13. /api/related/v3/{contentProfile}/related-books-and-articles-by-user-profile-batch
Parameter Description

contentProfile

A customer-specific part of the URL, determined during the setup of the API.
Query string Parameters
Parameter Optional Description

bookSize

true

Type: Integer
Default value: 10

Number of book recommendations to return.

articleSize

true

Type: Integer
Default value: 10

Number of article recommendations to return.

includeCSVHeadersInResponse

true

Type: Boolean
Default value: true

Indicates wether a header row should be included in the response csv.

includePreprint

true

Type: Boolean
Default value: False

Indicates whether preprint should be included for the returned recommendations.
If true, only preprint articles/book ids will be returned
Request body
Path Optional Type Description

requests

false

List<UserProfileRequest>

List of user requests.
A maximum of 50 requests can be provided.

requests[].userId

false

String

User id

requests[].documents

true

List<Document>

List of documents. Ie. the users click history.
A maximum of 80 documents can be provided.

requests[].favouriteDocuments

true

List<Document>

List of favourite documents. Ie. the users bookmarked documents.
A maximum of 80 favourite documents can be provided.

requests[].documentsToExclude

true

List<Document>

List of documents to exclude from the resultset.
Ie the last x documents the user have seen/been presented for.
A maximum of 500 documents to exclude can be provided.

requests[].timeIntervalBooks

true

DateRangeObject

Publication date filter on the books in the response.
If no interval is provided, books from the last 5 years will be returned.

requests[].timeIntervalArticles

true

DateRangeObject

Publication date filter on the articles in the response.
If no interval is provided, articles from the last 5 years will be returned.

requests[].documents[].id

true

String

Document id.
(Article ids are supported.)

requests[].favouriteDocuments[].id

true

String

Document id.
(Article ids are supported.)

requests[].documentsToExclude[].id

true

String

Document id.
(Both book and article ids are supported.)

requests[].timeIntervalBooks.from

true

Date

From date (incl) - format: yyyy-MM-dd

requests[].timeIntervalBooks.to

true

Date

To date (excl) - format: yyyy-MM-dd

requests[].timeIntervalArticles.from

true

Date

From date (incl) - format: yyyy-MM-dd

requests[].timeIntervalArticles.to

true

Date

To date (excl) - format: yyyy-MM-dd
Example Request
$ curl 'https://services.unsilo.com/api/related/v3/contentProfile/related-books-and-articles-by-user-profile-batch?bookSize=10&articleSize=10&includeCSVHeadersInResponse=true&includePreprint=false' -i -u 'username:password' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "requests": [
    {
      "documents": [
        {
          "id": "docId_a"
        }
      ],
      "documentsToExclude": [
        {
          "id": "docId_b"
        }
      ],
      "favouriteDocuments": [
        {
          "id": "docId_c"
        }
      ],
      "timeIntervalArticles": {
        "from": "2018-01-01",
        "to": "2020-05-30"
      },
      "timeIntervalBooks": {
        "from": "2016-01-01",
        "to": "2020-05-30"
      },
      "userId": "user_id"
    }
  ]
}'
Response

The results are returned in csv format, with a header row, followed by a row for each request.
Given that bookSize=3 and articleSize=3 in the request, the response would have the following format,
with book_1 being the best matching book, and article_1 being the best matching article.

Example Response

user_id, book_1, book_2, book_3, article_1, article_2, article_3
1, book_a_id, book_b_id, book_c_id, article_a_id, article_b_id, article_c_id
2, book_d_id, book_e_id, book_f_id, article_d_id, article_e_id, article_f_id