Analytics API - HL Vanilla Community
<main> <article class="userContent"> <h2 data-id="analyticsleaderboard">/analytics/leaderboard</h2><pre class="code codeBlock" spellcheck="false" tabindex="0">GET /api/v2/analytics/leaderboard HTTP/1.1 Host: https://yoursite.vanillaforums.com </pre><ul><li>Retrieve data for a site leaderboard.</li><li><a href="https://success.vanillaforums.com/kb/articles/41-authentication" rel="nofollow noreferrer ugc">Authentication</a>: required</li></ul><h3 data-id="parameters">Parameters</h3><p><strong>Parameter Type Description</strong></p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">board</code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> <a href="https://docs.vanillaforums.com/help/apiv2/analytics/#leaderboards" rel="nofollow noreferrer ugc">Type of leaderboard</a></p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">start</code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> Start of the time range (ISO 8601)</p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">end </code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> End of the time range (ISO 8601)</p><p><code class="code codeInline" spellcheck="false" tabindex="0">limit</code> <code class="code codeInline" spellcheck="false" tabindex="0">integer</code> Maximum number of rows to return. Default: 10</p><h3 data-id="leaderboards">Leaderboards</h3><p>Leaderboards are specified by the <code class="code codeInline" spellcheck="false" tabindex="0">board</code> parameter. The following are valid values for that parameter:</p><ul><li><strong>top-posters</strong>: Users with most posts.</li><li><strong>top-discussion-starters</strong>: Users with most discussions.</li><li><strong>top-question-answerers</strong>: Users with most answers.</li><li><strong>top-best-answerers</strong>: Users with most accepted answers.</li><li><strong>top-member-by-total-reputation</strong>: Users by total reputation.</li><li><strong>top-positive-users</strong>: Users with the most positive reactions.</li><li><strong>top-member-by-accumulated-reputation</strong>: Users by accumulated reputation.</li><li><strong>top-viewed-discussions</strong>: Discussions with most views.</li><li><strong>top-commented-discussions</strong>: Discussions with most comments.</li><li><strong>top-positive-discussions</strong>: Discussions with most positive reactions.</li><li><strong>top-negative-discussions</strong>: Discussions with most negative reactions.</li><li><strong>top-viewed-qna-discussions</strong>: Questions with most views.</li></ul><h3 data-id="output">Output</h3><p>The following is output from an example request for a user leaderboard. It assumes a <code class="code codeInline" spellcheck="false" tabindex="0">limit</code> of three. The record property contains user row data, because this was a user leaderboard. If it had been a discussion leaderboard request, the property would contain details about a discussion.</p><p>The record property has been pruned for this example.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">[ { "id": 53738, "position": 1, "positionChange": "Rise", "previous": 2, "url": "http://yoursite.vanillaforums.com/profile?UserID=1234", "title": null, "count": 921 }, { "id": 62929, "position": 2, "positionChange": "Fall", "previous": 1, "url": "http://yoursite.vanillaforums.com/profile?UserID=5678", "title": null, "count": 816 } ] </pre><h2 data-id="analyticsquery">/analytics/query</h2><pre class="code codeBlock" spellcheck="false" tabindex="0">POST /api/v2/analytics/query HTTP/1.1 Host: https://yoursite.vanillaforums.com </pre><ul><li>Perform a query against collected analytics data.</li><li><a href="https://success.vanillaforums.com/kb/articles/41-authentication" rel="nofollow noreferrer ugc">Authentication</a>: required</li></ul><p>The body of the request must be a JSON-encoded object. Each property of the object should be a supported parameter.</p><h3 data-id="parameters-1">Parameters</h3><p><strong>Parameter Type Description</strong></p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">type</code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> <a href="https://docs.vanillaforums.com/help/apiv2/analytics/#analysis-types" rel="nofollow noreferrer ugc">Type of analysis to perform</a></p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">collection</code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> <a href="https://docs.vanillaforums.com/help/apiv2/analytics/#event-collections" rel="nofollow noreferrer ugc">Collection of events</a></p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">start</code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> Start of the time range (ISO 8601)</p><p><strong><code class="code codeInline" spellcheck="false" tabindex="0">end</code></strong><strong> </strong><code class="code codeInline" spellcheck="false" tabindex="0">string</code> End of the time range (ISO 8601)</p><p><code class="code codeInline" spellcheck="false" tabindex="0">property</code> <code class="code codeInline" spellcheck="false" tabindex="0">string</code> An event property to perform the analysis on</p><p><code class="code codeInline" spellcheck="false" tabindex="0">filters</code> <code class="code codeInline" spellcheck="false" tabindex="0">array </code> <a href="https://docs.vanillaforums.com/help/apiv2/analytics/#filters" rel="nofollow noreferrer ugc">Event property filters</a></p><p><code class="code codeInline" spellcheck="false" tabindex="0">interval</code> <code class="code codeInline" spellcheck="false" tabindex="0">string </code> <a href="https://docs.vanillaforums.com/help/apiv2/analytics/#interval" rel="nofollow noreferrer ugc">Result interval</a></p><p><code class="code codeInline" spellcheck="false" tabindex="0">group</code> <code class="code codeInline" spellcheck="false" tabindex="0">string</code> An event property to group results by</p><h3 data-id="analysis-types">Analysis types</h3><p>Analytics queries require an analysis type. This type will dictate how the data is compiled in the response.</p><ul><li><strong>count</strong>: Count the total records.</li><li><strong>sum</strong>: Add up all values for a property.</li><li><strong>maximum</strong>: Get the maximum value for a property.</li><li><strong>count_unique</strong>: Count the total number of unique property values.</li><li><strong>median</strong>: Calculate the median value for a property.</li></ul><p>Most analysis types are performed on a specific event property, so they require the <code class="code codeInline" spellcheck="false" tabindex="0">property</code> parameter to be specified; <strong>count</strong> does not require a <code class="code codeInline" spellcheck="false" tabindex="0">property</code>parameter.</p><h3 data-id="event-collections">Event collections</h3><p>All events captured by Vanilla are grouped into one of the following categories. The collection is specified by passing the <code class="code codeInline" spellcheck="false" tabindex="0">collection</code> parameter to the analytics query.</p><h4 data-id="page">page</h4><p>Page views are captured in the <code class="code codeInline" spellcheck="false" tabindex="0">page</code> collection. Any time a guest or registered user loads a page, it is captured and filed into this collection.</p><p>Valid types for the <code class="code codeInline" spellcheck="false" tabindex="0">page</code> collection are:</p><ul><li><strong>discussion_view</strong></li><li><strong>page_view</strong></li></ul><h4 data-id="note-on-properties">Note on properties</h4><p>Commonly used properties for the <code class="code codeInline" spellcheck="false" tabindex="0">page</code> collection are:</p><ul><li><strong>user.userID</strong>: The ID of the user, if available. If there is no current user, either because they aren’t signed in or are a guest, this value will be <code class="code codeInline" spellcheck="false" tabindex="0">0</code>. <code class="code codeInline" spellcheck="false" tabindex="0">-1</code> is for an anonymized user. This was added for GDPR compliance (it only shows for users in Europe).</li></ul><h4 data-id="point">point</h4><p>Events involving actions affecting a user’s points are stored in the <code class="code codeInline" spellcheck="false" tabindex="0">point</code>collection. Both giving and removing points are recorded.</p><p>Valid types for the <code class="code codeInline" spellcheck="false" tabindex="0">point</code> collection are:</p><ul><li><strong>user_point_add</strong></li><li><strong>user_point_remove</strong></li></ul><p>Commonly used properties for the <code class="code codeInline" spellcheck="false" tabindex="0">point</code> collection are:</p><ul><li><strong>point.given.points</strong>: The total number of points granted or revoked in this event.</li></ul><h4 data-id="post">post</h4><p>When a discussion or comment is made, it is tracked in the <code class="code codeInline" spellcheck="false" tabindex="0">post</code> collection. All posts are contained in this collection: comments, discussions, questions, ideas. There are no restrictions on the type of post.</p><p>Valid types for the <code class="code codeInline" spellcheck="false" tabindex="0">post</code> collection are:</p><ul><li><strong>discussion_add</strong></li><li><strong>comment_add</strong></li></ul><p>Commonly used properties for the <code class="code codeInline" spellcheck="false" tabindex="0">post</code> collection are:</p><ul><li><strong>discussionType</strong>: The type of discussion related to this post.</li><li><strong>commentMetric.time</strong>: If the event was triggered by a comment, this property will be populated with the time, in seconds, between when the discussion and comment were added.</li><li><strong>commentMetric.firstComment</strong>: This will be true if this event was triggered by a comment and it was the first comment on the discussion.</li></ul><h4 data-id="post_modify">post_modify</h4><p>If a post is modified, the action is captured in the <code class="code codeInline" spellcheck="false" tabindex="0">post_modify</code> collection. Similar to “post,” the type does not matter. Two primary types of modification events are captured: edits and deletes.</p><p>Valid types for the <code class="code codeInline" spellcheck="false" tabindex="0">post_modify</code> collection are:</p><ul><li><strong>discussion_edit</strong></li><li><strong>discussion_delete</strong></li><li><strong>comment_add</strong></li><li><strong>comment_delete</strong></li></ul><h4 data-id="qna">qna</h4><p>The <code class="code codeInline" spellcheck="false" tabindex="0">qna</code> collection contains events specifically related to the Q&A addon, such as answering a question. Adding, editing, or deleting a question would be recorded in the “post” collection.</p><p>Valid types for the <code class="code codeInline" spellcheck="false" tabindex="0">qna</code> collection are:</p><ul><li><strong>answer_accepted</strong></li></ul><h4 data-id="reaction">reaction</h4><p>When a user submits a reaction to a post, it is captured in <code class="code codeInline" spellcheck="false" tabindex="0">reaction</code>. This includes adding and removing reactions.</p><p>Valid types for the <code class="code codeInline" spellcheck="false" tabindex="0">reaction</code> collection are:</p><ul><li><strong>reaction_add</strong></li><li><strong>reaction_delete</strong></li></ul><p>Commonly used properties for the <code class="code codeInline" spellcheck="false" tabindex="0">reaction</code> collection are:</p><ul><li><strong>reaction.reactionClass</strong>: The class of the reaction. This is typically “Positive” or “Negative.”</li><li><strong>reaction.reactionType</strong>: The specific type of the reaction (e.g., Like, Up, Down, Agree, etc.).</li><li><strong>reaction.recordType</strong>: The type of post this reaction was performed on. This is typically “discussion” or “comment.”</li></ul><h4 data-id="registration">registration</h4><p>Successful sign-ups on the forum are recorded in the <code class="code codeInline" spellcheck="false" tabindex="0">registration</code> collection.</p><p>Valid types for the <strong>registration</strong> collection are:</p><ul><li><strong>registration_success</strong></li></ul><h4 data-id="session">session</h4><p>Session events are captured in the <code class="code codeInline" spellcheck="false" tabindex="0">session</code> collection. These events typically include when a user initiates sign-in, starting their session, and when they sign out, ending their session.</p><p>Valid types for the session collection are:</p><ul><li><strong>session_start</strong></li><li><strong>session_end</strong></li></ul><h3 data-id="filters">Filters</h3><p>Data queried from analytics can be filtered by collection and event properties. The most common type of filtering is based on the <code class="code codeInline" spellcheck="false" tabindex="0">type</code> property. For example, if you want to see new discussions, you’d query the <code class="code codeInline" spellcheck="false" tabindex="0">post</code> collection and set a filter on the <code class="code codeInline" spellcheck="false" tabindex="0">type</code> property being equal to “discussion_add.” The available types for the various collections are documented in their individual sections. In addition to <code class="code codeInline" spellcheck="false" tabindex="0">type</code>, some additional commonly-used filtering properties are included in those sections, if available.</p><p>Each element in the <code class="code codeInline" spellcheck="false" tabindex="0">Filters</code> array should be an object with two properties: <code class="code codeInline" spellcheck="false" tabindex="0">prop</code> and <code class="code codeInline" spellcheck="false" tabindex="0">val</code>. An optional property, <code class="code codeInline" spellcheck="false" tabindex="0">op</code>, can be specified. There are several comparison operators to choose from:</p><ul><li><strong>eq</strong>: Equal</li><li><strong>ne</strong>: Not equal</li><li><strong>gt</strong>: Greater than</li><li><strong>gte</strong>: Greater than or equal to</li><li><strong>lt</strong>: Less than</li><li><strong>lte</strong>: Less than or equal to</li><li><strong>in</strong>: Verify a property’s value is in an array</li></ul><p>For example, when querying the post collection, you could apply a set of filters that only queried the first answers to a question with the following:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "filters": [ { "prop": "type", "op": "eq", "val": "comment_add" }, { "prop": "discussionType", "op": "eq", "val": "Question" }, { "prop": "commentMetric.firstComment", "op": "eq", "val": true } ] } </pre><h3 data-id="interval">Interval</h3><p>An optional <code class="code codeInline" spellcheck="false" tabindex="0">interval</code> parameter may be specified in an analytics query. If a valid <code class="code codeInline" spellcheck="false" tabindex="0">interval</code> is specified, the results are broken down into the specified increments over the timeframe.</p><p>The valid values for interval are:</p><ul><li><strong>hourly</strong></li><li><strong>daily</strong></li><li><strong>weekly</strong></li><li><strong>monthly</strong></li></ul><h3 data-id="output-1">Output</h3><p>Depending on whether or not an <code class="code codeInline" spellcheck="false" tabindex="0">interval</code> parameter was specified, the result may be in two different formats.</p><p>Without an <code class="code codeInline" spellcheck="false" tabindex="0">interval</code> parameter, a single value is returned: <code class="code codeInline" spellcheck="false" tabindex="0">result</code>.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{"result": 1370} </pre><p>If an <code class="code codeInline" spellcheck="false" tabindex="0">interval</code> value was provided, the <code class="code codeInline" spellcheck="false" tabindex="0">result</code> value will be an array. Each interval will be returned as an object in that array. The interval’s subset of the overall timeframe will be specified as the <code class="code codeInline" spellcheck="false" tabindex="0">timeframe</code> property. A <code class="code codeInline" spellcheck="false" tabindex="0">value</code>property will indicate the query result for the specified subset.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "result": [ { "value": 458, "timeframe": { "start": T00:00:00.000Z", "end": T00:00:00.000Z" } }, { "value": 431, "timeframe": { "start": T00:00:00.000Z", "end": T00:00:00.000Z" } }, { "value": 481, "timeframe": { "start": T00:00:00.000Z", "end": T00:00:00.000Z" } } ] } </pre><p><br></p> </article> </main>