General Analytics

Get views grouped by country tag

Aggregates period view gains of the filtered videos by their effective country tags (assigned directly or through account rules). A video with multiple country tags counts toward each of them. Each country includes its top accounts and top videos by view gains, and the response carries filtered dataset totals so callers can derive tag coverage and per-country view share.

get/analytics/views-by-country

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/analytics/views-by-country
  • Auth: API key in header x-api-key

Query parameters

dateRange[from]string required
Example:2025-01-01

Start date in ISO format (YYYY-MM-DD)

dateRange[to]string required
Example:2025-01-31

End date in ISO format (YYYY-MM-DD)

platformsstring[] nullable

Social media platforms (facebook, instagram, tiktok, youtube, snapchat)

[
  "facebook",
  "instagram"
]
accountsstring[] nullable

Organization account IDs

[
  "orgacc_1A2B3C4D5E6F"
]
contentTypesstring[] nullable

Content types (video, slideshow)

[
  "video"
]
projectsstring[] nullable

Organization project IDs

Deprecated. Use tag filters (tags / tagGroups) instead — a project's virtual project tag id (orgproj_…) works as a tag id. See the migration guide.

[
  "orgproj_1A2B3C4D5E6F"
]
tagsstring[] nullable

Tag IDs. Custom and project tags must all match (intersection); country tags and continent:<CODE> values combine into one geographic group satisfied by any of them. none:<category> values (custom/project/country/continent) match entities WITHOUT any tag of the category. Ignored when tagGroups is provided.

[
  "orgtag_1A2B3C4D5E6F"
]
mode'any' | 'all' required

How the group's tags combine: any = OR, all = intersection.

idsstring[] required

Tag IDs, including continent:<CODE> and none:<category> values.

[
  {
    "mode": "all",
    "ids": [
      "orgtag_1A2B3C4D5E6F"
    ]
  },
  {
    "mode": "any",
    "ids": [
      "systag_1A2B3C4D5E6F",
      "continent:EU"
    ]
  }
]
viewMode'internal' | 'competitors' | 'all'
publicationMode'allEligible' | 'onlyPublished'

Response

OK

totalVideosnumber required

Distinct videos contributing view gains in the filtered dataset

taggedVideosnumber required

Of those, distinct videos with at least one effective country tag

totalViewsnumber required

Total view gains of the filtered dataset within the date range

assignedCountryCodesstring[] required

Countries with any tag assignment in the organization — a positive video tag or an active account rule — regardless of the current filters

Example response

{
  "totalVideos": 321,
  "taggedVideos": 280,
  "totalViews": 8421337,
  "countries": [
    {
      "countryCode": "US",
      "views": 1204500,
      "accounts": [
        {
          "platform": "facebook",
          "username": "dennis",
          "views": 820400
        }
      ],
      "videos": [
        {
          "platform": "facebook",
          "contentType": "video",
          "views": 412300
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.