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

It is necessary to provide an Ft-Calling-App value when using Fluid Topics web services. See Fluid Topics calling app.

Request example

{
  "startDate": "2024-01-01",
  "endDate": "2024-05-01",
  "filters": {
    "metadata": [
      {
        "key": "Product",
        "values": [
          "Fluid Topics"
        ]
      }
    ]
  },
  "paging": {
    "page": 1,
    "perPage": 10
  },
  "ratingType": "Stars",
  "sortOrder": "worstFirst"
}
Field Type Required? Description
startDate String Yes The inclusive start date of the period. Its format can be YYYY-MM-DD, YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS. For more information about date and time formats, see Timestamps.
The value must be within the analytics data retention period.
endDate String Yes The exclusive end date of the period. Must be later than the startDate. Its format can be YYYY-MM-DD, YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS. For more information about date and time formats, see Timestamps.
The value must be within the analytics data retention period.
filters Object No An object 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 An object that contains page and perPage.
page Number Yes Indicates the current page, starts at 1.
perPage Number Yes The number of results per page.
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 example shows a JSON response body for this web service:

{
  "startDate": "2024-01-01",
  "endDate": "2024-05-01",
  "paging": {
    "page": 1,
    "perPage": 10,
    "totalCount": 3,
    "lastPage": true
  },
  "results": [
    {
      "id": "G9qQBEmpahJGC4q1yvU91w",
      "title": "Fluid Topics Configuration and Administration Guide",
      "type": "STRUCTURED_DOCUMENT",
      "link": "https://docs.fluidtopics.com/reader/G9qQBEmpahJGC4q1yvU91w/root",
      "metadata": [
        {
          "key": "audience",
          "label": "Audience",
          "values": [
            "public"
          ]
        },
        {
          "key": "Category",
          "label": "Category",
          "values": [
            "Reference Guides"
          ]
        },
        {
          "key": "Version_FT",
          "label": "Version",
          "values": [
            "Latest"
          ]
        }
      ],
      "rating": {
        "type": "Stars",
        "totalCount": 1,
        "average": 1.0
      }
    },
    {
      "id": "2qCoH7U~z73O75bH4NoYbw",
      "title": "Integrate the Fluid Topics API",
      "type": "STRUCTURED_DOCUMENT",
      "link": "https://docs.fluidtopics.com/reader/2qCoH7U~z73O75bH4NoYbw/root",
      "metadata": [
        {
          "key": "audience",
          "label": "Audience",
          "values": [
            "public"
          ]
        },
        {
          "key": "Category",
          "label": "Category",
          "values": [
            "Technical Notes"
          ]
        },
        {
          "key": "Version_FT",
          "label": "Version",
          "values": [
            "Latest"
          ]
        }
      ],
      "rating": {
        "type": "Stars",
        "totalCount": 1,
        "average": 3.0
      }
    },
    {
      "id": "E9VmzGmTNtW7EtdPfNFzMA",
      "title": "Fluid Topics User Guide",
      "type": "STRUCTURED_DOCUMENT",
      "link": "https://docs.fluidtopics.com/reader/E9VmzGmTNtW7EtdPfNFzMA/root",
      "metadata": [
        {
          "key": "audience",
          "label": "Audience",
          "values": [
            "public"
          ]
        },
        {
          "key": "Category",
          "label": "Category",
          "values": [
            "Reference Guides"
          ]
        },
        {
          "key": "Version_FT",
          "label": "Version",
          "values": [
            "Latest"
          ]
        }
      ],
      "rating": {
        "type": "Stars",
        "totalCount": 1,
        "average": 5.0
      }
    }
  ],
  "ratingType": "Stars"
}
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.
page Number The current page of results.
perPage Number The number of results per page.
totalCount Number The total number of available results.
lastPage Boolean A boolean operator indicating whether the page is the last page of results.
results Array A section with analytics data for each rated document.
id String The ID of the document.
title String The title of the document.
type String The document's type (STRUCTURED_DOCUMENT or UNSTRUCTURED_DOCUMENT).
link String The document's URL in Fluid Topics.
metadata Array The document's metadata.
key String A unique name to identify the facet.
label String The facet's localized name.
values Array The values of the metadata.
rating Object Information about the rating.
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.