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
- Obtaining a Meltwater search
- Making an Analytics API request
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:
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:
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.
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.
To fetch the summary analytics you call the
GET https://api.meltwater.com/v3/analytics/<search_id> endpoint.