Topic 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 topics in a selected period.

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

Request example

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

{
    "startDate": "2024-01-01",
    "endDate": "2024-05-01",
    "filters": {
        "document": {
            "metadata": [
                {
                    "key": "Product",
                    "values": [
                        "Fluid Topics"
                    ]
                }
            ]
        }
    },
    "paging": {
        "page": 1,
        "perPage": 10
    },
    "ratingType": "Stars",
    "sortOrder": "worstFirst"
}
Field Type Required? Description
startDate String Yes Inclusive start date of the period. Must be in the past year.
endDate String Yes Exclusive end date of the period. Must be after the start date.
filters Object No Additional filters for metadata. The filters element contains the document and titleContains elements.
document Object No Optional filter for topics belonging to documents with specific 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 Unique name to identify the metadata.
values Array No Values of the metadata.
titleContains String No String that must be present in the title of all returned documents. It is not case sensitive.
titleContains String No String that must be present in the title of all returned topics. It is not case sensitive.
paging Object Yes Object containing page and perPage.
page Number No Current page number, starts at 1.
perPage Number No Number of results per page.
ratingType String Yes 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": "2024-01-01",
    "endDate": "2024-05-01",
    "paging": {
        "page": 1,
        "perPage": 10,
        "totalCount": 2,
        "lastPage": true
    },
    "results": [
        {
            "id": "G1Qu_wjQV8UqBOmIS25Kkw",
            "title": "Introduction",
            "link": "https://doc.fluidtopics.com/reader/Soi1X0PgWfbH_0srfVYulQ/G1Qu_wjQV8UqBOmIS25Kkw",
            "rating": {
                "type": "Stars",
                "totalCount": 2,
                "average": 4.0
            },
            "document": {
                "id": "Soi1X0PgWfbH_0srfVYulQ",
                "title": "Adobe FrameMaker Connector Configuration Guide",
                "type": "STRUCTURED_DOCUMENT",
                "metadata": [
                    {
                        "key": "audience",
                        "label": "Audience",
                        "values": [
                            "public"
                        ]
                    },
                    {
                        "key": "Category",
                        "label": "Category",
                        "values": [
                            "Technical Notes"
                        ]
                    },
                    {
                        "key": "Version_FT",
                        "label": "Version",
                        "values": [
                            "Latest"
                        ]
                    }
                ]
            }
        },
        {
            "id": "ogT4xK09AVNnzz4RgLGvVg",
            "title": "Welcome on board",
            "link": "https://doc.fluidtopics.com/reader/qxGybCdsXnL8cAyvoNzzVA/ogT4xK09AVNnzz4RgLGvVg",
            "rating": {
                "type": "Stars",
                "totalCount": 1,
                "average": 4.0
            },
            "document": {
                "id": "qxGybCdsXnL8cAyvoNzzVA",
                "title": "Fluid Topics Quick Start Guide",
                "type": "STRUCTURED_DOCUMENT",
                "metadata": [
                    {
                        "key": "audience",
                        "label": "Audience",
                        "values": [
                            "public"
                        ]
                    },
                    {
                        "key": "Category",
                        "label": "Category",
                        "values": [
                            "Technical Notes"
                        ]
                    },
                    {
                        "key": "Version_FT",
                        "label": "Version",
                        "values": [
                            "Latest"
                        ]
                    }
                ]
            }
        }
    ],
    "ratingType": "Stars"
}
Field Type Description
startDate String The inclusive start date of the period as defined in the request body.
endDate String The exclusive end date of the period as defined in the request body.
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.
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.
key String A unique name to identify the facet.
label String The facet's localized name.
values Array The values of the metadata.
title String The title of the document.
type String The type of document (STRUCTURED_DOCUMENT, UNSTRUCTURED_DOCUMENT, or SHARED_PERSONAL_BOOK).
id String The ID of the topic.
title String The title of the topic.
link String The topic's URL in Fluid Topics.
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.