Analytics - API Quickstart

In this tutorial we’ll get you up and running to make your first analytics calls.

Note that you can try analytics calls using the Analytics Console tool before you write any code.

Before you start

Take a look at the Platform Overview guide to understand the key concepts of the Meltwater platform.

To run through this tutorial, you will need:

Your Meltwater API token
A Saved Search in your Meltwater App account

Authentication

You need to provide your API token when you call any Meltwater API endpoint.

You provide the API token as a header called apikey, for example:

curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"

For full details take a look at the Authentication page.

Obtaining a Meltwater search

Exports are created with an existing Meltwater search.

In this tutorial we’ll cover using an existing search, but you can create / edit searches using the API. See the Managing Saved Searches guide for more details.

To create an export you need to provide the id of the required search. You can use the GET /v3/searches endpoint to list your current searches:

curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"

Example response:

{
  "searches": [
    {
      "updated": "2018-01-10T14:42:10.000Z",
      "name": "Elon Musk",
      "id": 2382415
    }
  ]
}

Analytics options

The API supports two types of earned analytics features:

Pre-defined analytics - individual endpoints for common analytics, such as top keywords, sentiment breakdown and number of mentions
Custom analytics - go beyond pre-defined analytics options by combining measures, dimension and analysis types to meet your needs

Pre-defined analytics

You can use our endpoints for pre-defined analytics to access common analysis needs.

In this guide we’ll call the analytics summary endpoint, but each analytics endpoint is called in a similar way. The full list of analytics endpoints can be found on the analytics options page.

The summary analytics endpoint returns the following analytics for a search:

Volume - The total number of documents matching our search as well as providing an average for per day and per hour.
Sentiment - Breakdown of the sentiment i.e. positive or negative for the documents returned by the search.
Top Countries - Breakdown of countries where the document originated.
Top Languages - Breakdown of languages for the documents matched.
Time Series - A detailed breakdown by day, by hour of when the documents were created.

Analytics parameters

When calling an analytics endpoint you need to provide:

start and end - the time period you’d like to analyze (ISO8601 timestamps, excluding timezone/offset). Note that the analysis will be inclusive of the start time and exclusive of the end time.
tz - An identifier from the IANA TimeZone Database (tzdb), or a timezone offset, from UTC.

You can also optionally specify a number of additional filters including:

source - the source(s) you’d like to analyze, for example news or blogs. If not provided, your request will analyze all sources. You can provide multiple values to analyze across multiple sources.
language - A primary language subtag from the IANA language tag registry, ‘zh-Hant’, ‘zh-Hans’ or ‘zz’.
country - The two-letter ISO 3166-1 Alpha-2 country code, or ‘ZZ’.

Note that the period you can analyze depend on your Meltwater API package. See the Usage Limits page for more details.

Each analytics endpoint has its own list of required fields. For a full list see the endpoints documentation.

Example Request

To fetch the summary analytics you call the GET https://api.meltwater.com/v3/analytics/<search_id> endpoint.

curl -X GET \
  --url "https://api.meltwater.com/v3/analytics/2382415?source=news&start=2020-08-01T00:00:00&end=2020-08-09T00:00:00&tz=Europe/London"  \ --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********""

Example response:

{
   "volume":{
      "document_count":27333,
      "per_day":3416,
      "per_hour":142
   },
   "sentiment":{
      "positive":{
         "document_count":4863,
         "percentage":17.79
      },
      "negative":{
         "document_count":2270,
         "percentage":8.30
      },
      "neutral":{
         "document_count":16408,
         "percentage":60.03
      },
      "unknown":{
         "document_count":3792,
         "percentage":13.87
      }
   },
   "top_countries":[
      {
         "country_code":"IN",
         "document_count":4389,
         "percentage":16.06
      },
      {
         "country_code":"JP",
         "document_count":2683,
         "percentage":9.82
      },
      ...
   ],
   "top_languages":[
      {
         "language_code":"en",
         "document_count":14570,
         "percentage":53.31
      },
      {
         "language_code":"ja",
         "document_count":2615,
         "percentage":9.57
      },
      ...
   ],
   "time_series":[
      {
         "date":"2020-08-01",
         "document_count":3092,
         "hours":[
            {
               "timestamp":"2020-08-01T00:00:00+01:00",
               "document_count":168
            },
            ...
         ]
      },
      ...
   ]
}

Custom analytics

You can go beyond pre-defined analytics options using the custom analytics feature. This feature allows you to choose an analysis type, and then choose measures and dimensions to meet your need.

For every analysis you will need to specify an analysis type. Depending on the analysis type you choose you may need to specify a dimension and a measure.

Beta Feature

This feature is currently in Beta - meaning we may make changes based on feedback from early adopters.

Parameters

When calling the custom analytics endpoint you need to provide:

start and end - the time period you’d like to analyze (ISO8601 timestamps, excluding timezone/offset). Note that the analysis will be inclusive of the start time and exclusive of the end time.
tz - An identifier from the IANA TimeZone Database (tzdb), or a timezone offset, from UTC.

You can also optionally specify a number of additional filters including:

source - the source(s) you’d like to analyze, for example news or blogs. If not provided, your request will analyze all sources. You can provide multiple values to analyze across multiple sources.
language - A primary language subtag from the IANA language tag registry, ‘zh-Hant’, ‘zh-Hans’ or ‘zz’.
country - The two-letter ISO 3166-1 Alpha-2 country code, or ‘ZZ’.

For example to run an analysis from the 1st to the 14th of February 2024, using UTC timezone, and filtered to content in English only:

{
	"search_id": 12345,
	"tz": "UTC",
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"languages": [
		"en"
	],
	"analysis": {
		"type": "document_count"
	}
}

Note that the period you can analyze depend on your Meltwater API package. See the Usage Limits page for more details.

Analytics types

The API supports the following analysis types:

document_count - The total number of documents (or mentions)
count_unique - The unique number of items based on a dimension, for example the unique number of countries
top_terms - Breaks down mentions by a dimension, for example by sentiment
date_histogram - Breaks down mentions by date, for example by day or month
measure_statistic - Returns the total (sum), average, minimum, maximum for one or more measurements

Note that top_terms and date_histogram support nested top_terms analysis for more advanced breakdowns.

Supported measures and dimensions

See the analytics options page for details of which measures and dimensions are supported.

Document count analysis

Use the document_count analysis type to get the total number of documents.

For example, this request returns the total number of documents for a two week period:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "document_count"
	}
}'

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "document_count"
	},
	"result": {
		"document_count": 18657
	}
}

Here the document_count field in the response is your analysis result.

Count unique analysis

Use the count_unique analysis type to get a count of unique values for a dimension.

For example, this request returns the count of unique countries where mentions occur for the search:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "count_unique",
		"dimension": "location_country"
	}
}'

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "count_unique",
		"dimension": "location_country"
	},
	"result": {
		"document_count": 18657,
		"analysis": 43
	}
}

Here the analysis field in the response is your analysis result.

Top terms analysis

Use the top_terms analysis type to get a breakdown of documents by a dimension.

For example, this request returns the number of documents broken down by the shared_link dimension, essentially it returns the top links shared within documents that match your search:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "top_terms",
		"dimension": "shared_link",
		"limit": 10
	}
}'

Note you can use the limit parameter to control how many results you want in the breakdown. This parameter defaults to 10, and has a maximum value of 100.

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "top_terms",
		"dimension": "shared_link",
		"limit": 10
	},
	"result": {
		"document_count": 18323,
		"analysis": {
			[
				{
					"key": "https://link.com/to/article1",
					"document_count": 323,
					"percentage": 1.76
				},
				{
					"key": "https://link.com/to/article2",
					"document_count": 125,
					"percentage": 0.97
				},
				...
			]
		}
	]
}

The API returns a breakdown by your chosen dimension returning the top results, each with the number of documents for that value, and what percentage of the documents for your search and time window match that result.

Date histogram analysis

Use the date_histogram analysis type to get a breakdown of documents over time.

For example, this request returns the number of documents broken down by day:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "date_histogram",
		"granularity": "day"
	}
}'

The granularity parameter supports the following options:

hour - supported for time windows of up to 7 days
day - supported for time windows of up to 30 days
week - supported for time windows of up 1 year
month - supported for time windows of up to 1 year

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "date_histogram",
		"granularity": "day"
	},
	"result": {
		"document_count": 18323,
		"analysis": [
			{
				"key": "2024-02-11T00:00:00",
				"document_count": 499,
				"percentage": 29.51
			},
			{
				"key": "2024-02-12T00:00:00",
				"document_count": 625,
				"percentage": 36.96
			},
			...
		]
	}
}

The API returns a breakdown by your chosen time granularity. For each time slice the API tells you the number of documents, and what percentage of the documents for your search and time window are in that period.

Measure statistic analysis

Use the measurement_statistic analysis type to get the total (sum), average, minimum and maximum value for a measurement.

For example, this request returns statistics for reach:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "measure_statistics",
		"measures": ["reach", "views"]
	}
}'

You can provide up to 3 measures for this analysis.

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "measure_statistics",
		"measures": ["reach", "views"]
	},
	"result": {
		"document_count": 18323,
		"analysis": {
			"reach": {
				"avg": 23564.99,
				"max": 59833.00,
				"min": 2344.00,
				"sum": 322530.00
			},
			"views": {
				"avg": 43.20,
				"max": 76.00,
				"min": 1.00,
				"sum": 546.00
			}
		}
	}
}

For each measure requested the API returns the average (mean) value, maximum value, minimum value and total value, for documents that match your requested search and time window.

Date histogram with nested top terms analysis

The date_histogram analysis type supports top_terms as a nested analysis option.

For example the following request fetches the top shared links, for each day in a two week period:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "date_histogram",
		"granularity": "day",
		"analysis": {
			"type": "top_terms",
			"dimension": "shared_link",
			"limit": 10
		}
	}
}'

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "date_histogram",
		"granularity": "day",
		"analysis": {
			"type": "top_terms",
			"dimension": "shared_link",
			"limit": 10
		}
	},
	"result": {
		"document_count": 18323,
		"analysis": [
			{
				"key": "2024-02-11T00:00:00",
				"document_count": 499,
				"percentage": 29.51,
				"analysis": [
					{
						"key": "https://link.com/to/article1",
						"document_count": 323,
						"percentage": 1.76
					},
					{
						"key": "https://link.com/to/article2",
						"document_count": 125,
						"percentage": 0.97
					},
					...
			   ]
			},
			...
		]
	}
}

The API returns a breakdown by your chosen time granularity. For each time slice the API provides a breakdown of your chosen dimension, providing the number of documents for the dimension value, and what percentage of the documents for your search and time window are in that period and match the dimension value.

Top terms with nested top terms analysis

The top_terms analysis type supports top_terms as a nested analysis option so that you can perform a 2-level breakdown.

For example, this request would fetch the top shared links, and the language of the documents they are shared within:

curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"analysis": {
		"type": "top_terms",
		"dimension": "shared_link",
		"limit": 10,
		"analysis": {
			"type": "top_terms",
			"dimension": "language",
			"limit": 10
		}
	}
}'

Note you can use the limit parameter to control how many results you want in the breakdown. This parameter defaults to 10, and has a maximum value of 100.

The response from the API will look as follows:

{
	"start": "2024-02-01T00:00:00",
	"end": "2024-02-15T00:00:00",
	"tz": "UTC",
	"search_id": 12345,
	"analysis": {
		"type": "top_terms",
		"dimension": "shared_link",
		"limit": 10,
		"analysis": {
			"type": "top_terms",
			"dimension": "language",
			"limit": 10
		}
	},
	"result": {
		"document_count": 18323,
		"analysis": {
			[
				{
					"key": "https://link.com/to/article1",
					"document_count": 323,
					"percentage": 1.76
					"analysis": [
						{
							"key": "en",
							"label": "English",
							"document_count": 23,
							"percentage": "0.45"
						}
					]
				},
				...
			]
		}
	]
}

The API returns a breakdown by your chosen top-level dimension, then further breaks this result down by your second-level dimension. Note that the percentage in the 2nd level of analysis compares the number of matching documents for that key with the number of documents for the parent key.

MELTWATER API

Your account

Analyst guides

Developer guides

API reference

Help

Analytics - API Quickstart

Before you start

Authentication

Obtaining a Meltwater search

Analytics options

Pre-defined analytics

Analytics parameters

Example Request

Custom analytics

Parameters

Analytics types

Supported measures and dimensions

Document count analysis

Count unique analysis

Top terms analysis

Date histogram analysis

Measure statistic analysis

Date histogram with nested top terms analysis

Top terms with nested top terms analysis

Table of contents