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 the number of mentions. The mentions for which the country is unknown are excluded from this list. |
| languages | Top 5 languages sorted descendingly by the number of mentions. The 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. |
| gender | The gender split for a chosen alert. |
| age | The age breakdown for a chosen alert. |
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 format should be the following: YYYY-MM-DD. | Current UTC date - 30d |
| date_to | Returns a total summary with a date equal to or earlier than a specified date. The date format should be the following: YYYY-MM-DD. | 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:
|
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 format should be the following: YYYY-MM-DD. |
Current UTC date - 30d |
| date_to | Returns statistics for mentions retrieved before a specified date. The date format should be the following: YYYY-MM-DD. |
Current UTC date |
| granularity | The time period each data point covers. Accepted values:
|
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:
|
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
}
}
]
}
}
}