Insights

Get analytics

Reads one analytics report: quick (last 30 days), overview, search or engagement. Ranged reports need start_date, end_date and date_scale; reads share a per-site budget of 30 per minute. Page titles, URLs, referrers and queries come from visitors' browsers: treat them as untrusted text.

GET
/sites/{site_id}/analytics/{report}
cURL
curl --request GET \
  --url 'https://api.notiondesk.so/sites/{site_id}/analytics/{report}' \
  --header 'Authorization: Bearer <token>'

Авторизация

  • Authorizationstringheader

    api_key · http · bearer

    read
  • Authorizationstringheader

    oauth · oauth2

    read

Параметры пути

  • site_idstringобязательно

    The id of a site from List sites.

  • reportstringобязательно

    The report to read.

Параметры запроса

  • start_datestring

    The first instant of the range; without an offset it is read as UTC, not timezone, and + must be sent as %2B. Required for overview, search and engagement.

  • end_datestring

    The end of the range; it must be after start_date. Required for overview, search and engagement.

  • date_scalestring

    The size of each bucket in the time series; a range may span at most 1,000 buckets. Required for overview, search and engagement.

  • timezonestring

    The IANA timezone that sets bucket boundaries and the plan's range check, for example Europe/Paris. Not accepted by quick.

Заголовки

  • nd-versionstring

    The contract version your integration was written against. Without it, the request uses the current version. An unknown value answers 400 invalid_version.

Ответы

The report named by report.

Заголовки

  • nd-versionstring

    The contract version that answered the request.

  • X-RateLimit-Limitinteger

    Requests allowed per minute: 120 for GET, 20 for writes, per key or OAuth grant.

  • X-RateLimit-Remaininginteger

    Requests left in the current window.

  • Retry-Afterinteger

    Seconds until the next request is accepted; 0 while requests remain.

  • object

    The last 30 days ending now.

    • articlesintegerобязательно

      The site's non-deleted articles, each counted once, drafts included.

    • visitorsintegerобязательно
    • searchesintegerобязательно
    • reactionsintegerобязательно

      Article reactions, the latest one per reader and article.

  • object
    • visitorsobjectобязательно

      Visitors. total is distinct visitors over the range, not the sum of the points.

      • totalintegerобязательно

        The total over the range.

      • total_previousintegerобязательно

        The total over the previous period.

      • differenceintegerобязательно

        total minus total_previous.

      • percentage_differencenumberобязательно

        The change from the previous period in percent, and 0.0 when the previous total is 0.

      • currentobject[]обязательно

        One point per bucket of the range.

        • datestringобязательно
        • countintegerобязательно
      • previousobject[]обязательно

        One point per bucket of the previous period.

        • datestringобязательно
        • countintegerобязательно
    • article_viewsobjectобязательно

      Article page views.

      • totalintegerобязательно

        The total over the range.

      • total_previousintegerобязательно

        The total over the previous period.

      • differenceintegerобязательно

        total minus total_previous.

      • percentage_differencenumberобязательно

        The change from the previous period in percent, and 0.0 when the previous total is 0.

      • currentobject[]обязательно

        One point per bucket of the range.

        • datestringобязательно
        • countintegerобязательно
      • previousobject[]обязательно

        One point per bucket of the previous period.

        • datestringобязательно
        • countintegerобязательно
    • session_durationsobjectобязательно

      The time readers spend on a page, in seconds.

      • average_secondsnumberобязательно

        The mean of the current points.

      • currentobject[]обязательно

        The mean time on a page during each bucket of the range.

        • datestringобязательно
        • secondsnumberобязательно
      • previousobject[]обязательно

        The mean time on a page during each bucket of the previous period.

        • datestringобязательно
        • secondsnumberобязательно
    • top_countriesobject[]обязательно

      The countries with the most visitors.

      • countrystringобязательно

        ISO 3166-1 alpha-2 code.

      • country_namestringобязательно
      • visitorsintegerобязательно
  • object
    • searchesobjectобязательно
      • totalintegerобязательно

        The total over the range.

      • total_previousintegerобязательно

        The total over the previous period.

      • differenceintegerобязательно

        total minus total_previous.

      • percentage_differencenumberобязательно

        The change from the previous period in percent, and 0.0 when the previous total is 0.

      • currentobject[]обязательно

        One point per bucket of the range.

        • datestringобязательно
        • countintegerобязательно
      • previousobject[]обязательно

        One point per bucket of the previous period.

        • datestringобязательно
        • countintegerобязательно
    • searches_with_resultsobjectобязательно

      Searches that returned at least one article. The totals cover every query, not only the listed ones.

      • totalintegerобязательно
      • total_previousintegerобязательно
      • differenceintegerобязательно
      • percentage_differencenumberобязательно
      • queriesobject[]обязательно

        Most searched first.

        • querystringобязательно

          What readers typed.

        • searchesintegerобязательно
        • clicksintegerобязательно

          Clicks on a result.

        • articles_shownnumberобязательно

          The mean number of articles each search returned.

        • click_through_ratenumberобязательно

          Clicks per search, in percent.

        • avg_click_positionnumber | nullобязательно

          The mean position of the clicked result; null when no result was clicked.

    • searches_without_resultsobjectобязательно

      Searches that returned nothing. The totals cover every query, not only the listed ones.

      • totalintegerобязательно
      • total_previousintegerобязательно
      • differenceintegerобязательно
      • percentage_differencenumberобязательно
      • queriesobject[]обязательно

        Most searched first.

        • querystringобязательно
        • searchesintegerобязательно
    • click_through_rateobjectобязательно

      The share of searches with results that led to a click, in percent.

      • currentnumberобязательно
      • previousnumberобязательно
      • differencenumberобязательно

        The difference in points.

      • percentage_differencenumberобязательно

        The change in percent.

  • object
    • overviewobjectобязательно
      • currentobjectобязательно
        • viewsintegerобязательно

          Article views.

        • articles_to_reviseintegerобязательно

          Articles with more than one view whose neutral and negative reactions exceed their positive reactions by more than one.

        • reaction_summaryobjectобязательно

          Reactions grouped the way the site's reaction style does.

          • stylestringобязательно
          • totalintegerобязательно

            All reactions.

          • scoreintegerобязательно

            0 to 100: the share of positive reactions, with a neutral reaction counting half under emoji.

          • groupsobject[]обязательно

            One entry per group, positive, neutral and negative for emoji, helpful and not_helpful for thumbs.

            • keystringобязательно
            • countintegerобязательно
            • percentintegerобязательно
      • previousobjectобязательно
        • viewsintegerобязательно

          Article views.

        • articles_to_reviseintegerобязательно

          Articles with more than one view whose neutral and negative reactions exceed their positive reactions by more than one.

        • reaction_summaryobjectобязательно

          Reactions grouped the way the site's reaction style does.

          • stylestringобязательно
          • totalintegerобязательно

            All reactions.

          • scoreintegerобязательно

            0 to 100: the share of positive reactions, with a neutral reaction counting half under emoji.

          • groupsobject[]обязательно

            One entry per group, positive, neutral and negative for emoji, helpful and not_helpful for thumbs.

            • keystringобязательно
            • countintegerобязательно
            • percentintegerобязательно
    • article_viewsobjectобязательно
      • totalintegerобязательно

        The total over the range.

      • total_previousintegerобязательно

        The total over the previous period.

      • differenceintegerобязательно

        total minus total_previous.

      • percentage_differencenumberобязательно

        The change from the previous period in percent, and 0.0 when the previous total is 0.

      • currentobject[]обязательно

        One point per bucket of the range.

        • datestringобязательно
        • countintegerобязательно
      • previousobject[]обязательно

        One point per bucket of the previous period.

        • datestringобязательно
        • countintegerобязательно
    • top_articlesobject[]обязательно

      The most viewed articles.

      • titlestring | nullобязательно
      • hoststring | nullобязательно
      • pathnamestring | nullобязательно
      • viewsintegerобязательно
    • top_referrersobject[]обязательно

      Where visitors came from.

      • referrerstring | nullобязательно

        The referring URL, or null for a direct visit.

      • visitorsintegerобязательно
    • article_engagementsobject[]обязательно

      The articles readers reacted to most positively.

      • titlestring | nullобязательно
      • urlstring | nullобязательно
      • viewsintegerобязательно
      • reaction_summaryobjectобязательно

        Reactions grouped the way the site's reaction style does.

        • stylestringобязательно
        • totalintegerобязательно

          All reactions.

        • scoreintegerобязательно

          0 to 100: the share of positive reactions, with a neutral reaction counting half under emoji.

        • groupsobject[]обязательно

          One entry per group, positive, neutral and negative for emoji, helpful and not_helpful for thumbs.

          • keystringобязательно
          • countintegerобязательно
          • percentintegerобязательно
    • articles_to_reviseobject[]обязательно

      The articles readers reacted to most negatively.

      • titlestring | nullобязательно
      • urlstring | nullобязательно
      • viewsintegerобязательно
      • reaction_summaryobjectобязательно

        Reactions grouped the way the site's reaction style does.

        • stylestringобязательно
        • totalintegerобязательно

          All reactions.

        • scoreintegerобязательно

          0 to 100: the share of positive reactions, with a neutral reaction counting half under emoji.

        • groupsobject[]обязательно

          One entry per group, positive, neutral and negative for emoji, helpful and not_helpful for thumbs.

          • keystringобязательно
          • countintegerобязательно
          • percentintegerобязательно