Get insights

GET alerts/<id>/insights/total returns summary data for a specified mention alert. The alert ID is used to identify the alert.
This method is available for Mention alerts only (Leads alerts are not supported). The response will contain information about your plan’s monthly mentions limit.

Resource URL

https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/total/<type>

Types

Type Description
mentions  The total number of mentions.
sentiment The total number of positive, negative, and neutral mentions.
reach The total Reach.
countries Top 5 countries sorted descendingly by number of mentions. Mentions for which the country is unknown are excluded from this list.
languages Top 5 languages sorted descendingly by number of mentions. Mentions for which the language is unknown are excluded from this list.
sources The number of mentions coming from a specific source.
topic_cloud The top 50 records from the alert’s topic cloud sorted descendingly by score.

Parameters

Parameter Description Default value
access_token API key for accessing data through API.  
date_from Returns a total summary with a date equal to or later than a specified date.

The date should be passed in the UTC timestamp.
Current UTC date - 30d
date_to Returns a total summary with a date equal to or earlier than a specified date.

The date should be passed in the UTC timestamp.
Current UTC date
source Returns a summary from a specified source. Multiple sources can be separated by a comma. If this parameter is not specified, the data will be returned for all sources.

Accepted values:
  • twitter
  • facebook
  • instagram
  • youtube
  • reddit
  • news-blogs
  • web
 

Example request

GET https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/total/mentions?access_token=YOUR_API_KEY&date_from=2019-07-01&date_to=2019-07-31

Example response

{
  "limits": [
    {
      "limit_name": "monthly_mentions",
      "limit_reached": true,
      "limit_renewal_date": 1567341352000
    }
  ],
  "alert_data": {
    "alert_id": 1,
    "alert_type": "mentions",
    "alert_name": "awario",
    "project_id": 1,
    "project_name": "Awario",
    "insights": {
      "name": "mentions",
      "value": {
        "mentions": 50347
      }
    }
  }
}

Example request

GET https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/total/sentiment?access_token=YOUR_API_KEY&date_from=2019-07-01&date_to=2019-07-31

Example response

{
  "limits": [
    {
      "limit_name": "monthly_mentions",
      "limit_reached": true,
      "limit_renewal_date": 1567341352000
    }
  ],
  "alert_data": {
    "alert_id": 1,
    "alert_type": "mentions",
    "alert_name": "awario",
    "project_id": 1,
    "project_name": "Awario",
    "insights": {
      "name": "sentiment",
      "value": {
        "positive": 23000,
        "negative": 0,
        "neutral": 34500
      }
    }
  }
}

Example request

GET https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/total/countries?access_token=YOUR_API_KEY&date_from=2019-07-01&date_to=2019-07-31

Example response

{
  "limits": [
    {
      "limit_name": "monthly_mentions",
      "limit_reached": true,
      "limit_renewal_date": 1567341352000
    }
  ],
  "alert_data": {
    "alert_id": 1,
    "alert_type": "mentions",
    "alert_name": "awario",
    "project_id": 1,
    "project_name": "Awario",
    "insights": {
      "name": "countries",
      "value": {
        "US": 23000,
        "GB": 5600,
        "DE": 3400,
        "FR": 2400,
        "ES": 540
      }
    }
  }
}

Example request

GET https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/ights/total/topic_cloud?access_token=YOUR_API_KEY&date_from=2019-07-01&date_to=2019-07-31

Example response

{
  "limits": [
    {
      "limit_name": "monthly_mentions",
      "limit_reached": true,
      "limit_renewal_date": 1567341352000
    }
  ],
  "alert_data": {
    "alert_id": 1,
    "alert_type": "mentions",
    "alert_name": "awario",
    "project_id": 1,
    "project_name": "Awario",
    "insights": {
      "name": "topic_cloud",
      "value": {
        "awario": 23000,
        "social tool": 5600,
        ...
        "social media tool": 540
      }
    }
  }
}

 

GET alerts/<id>/insights/time_series returns a series of data points listed in time order for a specified mention alert. The alert ID is used to identify the alert.
This method is available for Mention alerts only (Leads alerts are not supported). The response includes information about the plan’s monthly mentions limit.

Resource URL

https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/time_series/<type>

Types 

Type Description
mentions The history of the volume of mentions over time.
sentiment The history of the volume of positive, negative, and neutral mentions.
reach The history of Reach.

Parameters

Parameter Description Default value
access_token API key for accessing data through API.  
date_from Returns statistics for mentions retrieved after a specified date.

The date should be passed in the UTC timestamp.
 
Current UTC date - 30d
date_to Returns statistics for mentions retrieved before a specified date.

The date should be passed in the UTC timestamp.
 
Current UTC date
granularity The time period each data point covers.

Accepted values:
 
  • Day
  • Week (Monday to Sunday)
  • Month (a calendar month)
day
source Returns statistics from a specified source. Multiple sources can be separated by a comma. If this parameter is not specified, the data will be returned for all sources.

Accepted values:
 
  • twitter
  • facebook
  • instagram
  • youtube
  • reddit
  • news-blogs
  • web
 

Example request

GET https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/time_series/mentions?access_token=YOUR_API_KEY&date_from=2019-07-01&date_to=2019-07-31
  

Example response

  {
  "limits": [
    {
      "limit_name": "monthly_mentions",
      "limit_reached": true,
      "limit_renewal_date": 1567341352000
    }
  ],
  "alert_data": {
    "alert_id": 1,
    "alert_type": "mentions",
    "alert_name": "awario",
    "project_id": 1,
    "project_name": "Awario",
    "insights": {
      "name": "mentions",
      "values": [
        {
          "start_date": "2019-07-01",
          "end_date": "2019-07-01",
          "incomplete_period": false,
          "value": {
            "mentions": 150
          }
        },
        {
          "start_date": "2019-07-04",
          "end_date": "2019-07-04",
          "incomplete_period": false,
          "value": {
            "mentions": 10
          }
        },
        ...
        {
          "start_date": "2019-07-31",
          "end_date": "2019-07-31",
          "incomplete_period": false,
          "value": {
            "mentions": 340
          }
        }
      ]
    }
  }
}
  

Example request

GET https://api.awario.com/v1.0/alerts/YOUR_ALERT_ID/insights/time_series/sentiment?access_token=YOUR_API_KEY&date_from=2019-07-01&date_to=2019-07-31&granularity=week

Example response

{
  "limits": [
    {
      "limit_name": "monthly_mentions",
      "limit_reached": true,
      "limit_renewal_date": 1567341352000
    }
  ],
  "alert_data": {
    "alert_id": 1,
    "alert_type": "mentions",
    "alert_name": "awario",
    "project_id": 1,
    "project_name": "Awario",
    "insights": {
      "name": "sentiment",
      "values": [
        {
          "start_date": "2019-07-01",
          "end_date": "2019-07-07",
          "incomplete_period": false,
          "value": {
            "positive": 250,
            "neutral": 50
          }
        },
        {
          "start_date": "2019-07-15",
          "end_date": "2019-07-21",
          "incomplete_period": false,
          "value": {
            "positive": 20,
            "negative": 30,
            "neutral": 120
          }
        },
        ...
        {
          "start_date": "2019-07-29",
          "end_date": "2019-07-31",
          "incomplete_period": true,
          "value": {
            "positive": 130,
            "negative": 110
            "neutral": 100
          }
        }
      ]
    }
  }
}