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
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:
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:
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.
When calling an analytics endpoint you need to provide:
source- the source you’d like to analyze, for example
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.
Each analytics endpoint has its own list of required fields. For a full list see the endpoints documentation.
To fetch the summary analytics you call the
GET https://api.meltwater.com/v3/analytics/<search_id> endpoint.