Analytics - API Quickstart

In this tutorial we'll get you up and running to make your first Analytics API calls.

Before you start

To run through this tutorial, you will need:

  • Your Meltwater API key - you can find this on the API Credentials page
  • A Saved Search in your Meltwater App account

What we will cover

  1. Authentication
  2. Obtaining a Meltwater search
  3. Making an Analytics API request

1. Authentication

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

You provide the API key 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.

2. 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 /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",
      "type": "news",
      "search_id": 2382415,
      "name": "Elon Musk",
      "id": 2382415
    }
  ]
}

3. 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:

  • source - the source you'd like to analyze, for example news, twitter, blogs
  • 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:

  • 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.

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=twitter&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
            },
            ...
         ]
      },
      ...
   ]
}