Document heatmap - Fluid Topics - Latest

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

This web service responds with a document's heatmap during a selected period.

Method Endpoint
POST 
/analytics/api/v2/documents/{id}/topics/views-heatmap
Path parameter Type Description
{id} String The ID of a structured document.
  • It is necessary to provide an Ft-Calling-App value when using Fluid Topics web services. See Fluid Topics calling app.
  • Heatmaps are not available for unstructured documents.

Request example

The following example shows a JSON request body for this web service:

{
  "startDate": "2024-01-01",
  "endDate": "2024-05-01"
}
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 containing additional filters for the userId filter.
userId String - A filter used for returning views for a specific user. This field is only available for users with the ADMIN or BEHAVIOR_DATA_USER role. It is mandatory for users with the BEHAVIOR_DATA_USER role.

Response body

The following example shows a JSON response body for this web service:

{
  "startDate": "2024-01-01",
  "endDate": "2024-05-01",
  "documentInformation": {
    "id": "urR3GmtWOfUR0JEdj1EM7g",
    "title": "Add a DITA-OT plugin",
    "displayCount": 187,
    "link": "https://docs.fluidtopics.com/reader/urR3GmtWOfUR0JEdj1EM7g/root",
    "metadata": [
      {
        "key": "audience",
        "label": "Audience",
        "values": [
          "public"
        ]
      },
      {
        "key": "Category",
        "label": "Category",
        "values": [
          "How To"
        ]
      },
      {
        "key": "Version_FT",
        "label": "Version",
        "values": [
          "Latest"
        ]
      }
    ]
  },
  "results": [
    {
      "id": "eYpjq0pr_HR5nzozkAD5Og",
      "title": "Overview",
      "displayCount": 219,
      "children": []
    },
    {
      "id": "kQbXVmrLokCcENJh6a4SGQ",
      "title": "macOS procedure",
      "displayCount": 249,
      "children": []
    },
    {
      "id": "tl8eRQPtYQFWc9vham_SmA",
      "title": "Windows procedure",
      "displayCount": 145,
      "children": []
    },
    {
      "id": "STickvsazqP_p0msP9I1xw",
      "title": "Reset to default",
      "displayCount": 108,
      "children": []
    },
    {
      "id": "D9icEkXOGr7y9vCaja55bQ",
      "title": "Use case",
      "displayCount": 108,
      "children": [
        {
          "id": "oS3DIXE_ari5F9A4ckTpag",
          "title": "PlantUML diagrams plugin",
          "displayCount": 125,
          "children": []
        }
      ]
    }
  ]
}
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.
userId String The specified userId in the request body (optional).
documentInformation Array Information about the document.
id String The ID of the document.
title String The title of the document.
displayCount Number The number of times the document has been accessed.
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.
results Array A section with analytics data for each of the document's topics.
children Array The document's topics. The document's table of contents determines the order in which children are listed in the response body.
Return code Description
200 OK Returns 0 or more results.