Document ratings - Fluid Topics - Latest

Fluid Topics API Reference Guide
Category
Reference Guides
Audience
public
Version
Latest

This web service responds with information about the most rated documents in a selected period.

Method Endpoint
POST /analytics/api/v1/documents/ratings

Request example

{
  "startDate": "2022-08-01",
  "endDate": "2022-08-31",
  "filters": {
    "metadata": [
      {
        "key": "Product",
        "values": [
          "Fluid Topics"
        ]
      }
    ],
    "titleContains": "Pretty URL"
  },
  "paging": {
    "page": 1,
    "perPage": 10
  },
  "ratingType": "Stars",
  "sortOrder": "worstFirst"
}
Field Type Required? Description
startDate String Yes The inclusive start date of the period. The start date is mandatory and must be in the past year.
endDate String Yes The exclusive end date of the period. The end date is mandatory and must be after the start date.
filters Object No An optional addition to the input to only return results that have certain metadata.
    metadata Array No An element that must be present when using the filters element. It contains the key and values elements.
        key String No A unique name to identify the metadata.
        values Array No The values of the metadata.
    titleContains String No A string that must be present in the title of all returned documents. It is not case sensitive.
paging Object Yes A mandatory element that contains page and perPage.
    page Number Yes Indicates the current page, starts at 1 (mandatory).
    perPage Number Yes The number of results per page (mandatory).
ratingType String Yes The type of rating (Stars, Like, or Dichotomous).
sortOrder String No Determines whether topics are sorted from best to worst rated (bestFirst) or worst to best rated (worstFirst). If undefined, the default sortOrder is bestFirst.

If using the filters element, it is necessary to enter the exact key and at least one value for each key.

Response body

The following lines show an example of a JSON response body:

{
  "startDate": "2022-08-01",
  "endDate": "2022-08-31",
  "paging": {
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "lastPage": true
  },
  "results": [
    {

      "id": "57STK3r810OrYm1OaEhBeA",
      "title": "How to Manage Latest Versions with Pretty URLs",
      "type": "STRUCTURED_DOCUMENT",
      "link": "https://doc.antidot.net/reader/57STK3r810OrYm1OaEhBeA/root",
      "metadata": [
        {
          "key": "audience",
          "label": "Audience",
          "values": [
            "public"
          ]
        },
        {
          "key": "Updated_category",
          "label": "Category",
          "values": [
            "How To"
          ]
        },
        {
          "key": "Product",
          "label": "Product",
          "values": [
            "Fluid Topics"
          ]
        },
        {
          "key": "ft:locale",
          "label": "ft:locale",
          "values": [
            "English (United States)"
          ]
        }
      ],
      "rating": {
         "type": "Stars",
         "totalCount": 2,
         "average": 4.0
      }
    }
  ] 
}
Field Type Description
startDate String The inclusive start date of the period as defined in the input.
endDate String The exclusive end date of the period as defined in the input.
paging Object An element that contains the lastPage, page, perPage, and totalCount elements.
    lastPage Boolean A Boolean operator indicating whether the page is the last page (true or false).
    page Number The current page.
    perPage Number The number of results per page.
    totalCount Number The total number of available results.
    id String The ID of the document.
    title String The title of the document.
    type String The type of document (STRUCTURED_DOCUMENT, UNSTRUCTURED_DOCUMENT, or SHARED_PERSONAL_BOOK).
    link String The document's URL in Fluid Topics.
        key String A unique name to identify the facet.
        label String The facet's localized name.
        values Array The values of the metadata.
    type String The type of rating submitted for the document (Stars, Like, or Dichotomous).
    totalCount Number The number of ratings submitted for the document.
    average Number The average rating for the document.
Return code Description
200 OK Returns 0 or more results.