Analytics - API Quickstart

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

You can now try analytics calls using the new Analytics Console tool before you write any code.

Note that you need access to analytics in your API package to use this feature.

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.

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
    }
  ]
}

Making an Analytics API Request

In this tutorial 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 endpoints 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)
  • 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
            },
            ...
         ]
      },
      ...
   ]
}