Listening Overview

In this guide we’ll introduce you to key Listening concepts of the Meltwater API and platform.

Meltwater platform

The Meltwater platform ingests and enriches data from a wide variety of sources, including news and social platforms. Data is enriched by a set of enrichments (sentiment, language, key phrases, etc.) and stored in a consistent data schema. Listening data is held a in central store. The Meltwater application accesses these data stores to provide application features. The Meltwater API is built upon the same platform and data stores.

The Meltwater API allows you to export, stream and analyze listening data. If you are using one of our BI connectors this is calling the API behind the scenes for you, using your API credentials.

Broadly speaking you can access the same data through the API as a user sees in the application. However, due to the agreements we have with data providers there are some limitations on what data can be provided through the API.

For example, in the application we can provide the text of X posts, whereas due to X’s terms of service in the API we can only provide the ID of a post. An API customer needs to call the X API to rehydrate the post in order to get the post text.

Saved Searches

To export or stream content, or run analytics on listening data, you will need to start with a Saved Search. A Saved Search is a query that defines which documents in the platform should be matched for the request.

Documents that are matched by a Saved Search are called Mentions.

A Saved Search can be created in the Meltwater application using the Explore product, or by using the API.

Typically this will be a boolean query. For example, if you wanted to find news articles or social posts that mention Apple watches you may write:

(apple AND (iphone OR iwatch)) NOT ("apple sauce" OR "apple juice" OR "apple orchard*")

You may already have searches saved in the Meltwater application that you’d like to use with the API. If you’d like to create searches using the API take a look at the Managing Saved Searches guide.

Exporting Mentions

To export mentions using the API you need to provide one or mores Saved Search IDs and a time window for the export.

When you run an export this will be placed in a queue (each API customer has a separate queue). You can view the status of your exports in the Export Console or by calling the API.

When the export runs it will return any documents (news articles, social posts, blog posts, comments…) found in the data store that match the search criteria within the time window specified. These documents will contain a number of fields such as the URL, title, content, sentiment, and so on.

The fields available for documents depend on the source of the document and the template you choose for your export. See the Content Output Templates page for full details.

The API allows you to run one-time and recurring exports:

• One-time exports - these exports are run once, the data will not be refreshed automatically.
• Recurring exports - these exports are run on a schedule you specify. Each time the export runs the data for the export is overwritten.

Using the Export Console you can quickly start exporting listening data without writing code. See the Export Console Guide to learn more.

To learn how to create exports using the API see the Exporting Mentions guide.

Analyzing Mentions

To run analytics on listening data using the API you need to provide a Saved Search ID and a time window. Depending on the type of analysis you may need to provide additional parameters such as the source to analyze.

When you run an analysis you are analyzing the documents that match your search criteria. These are the same documents that would be returned if you ran an export with the same criteria. Unlike exports, analytics requests are synchronous, therefore they are typically returned in a few seconds.

To understand what analytics are available see the Analytics Options page.

Using the Analytics Console you can quickly start analyzing mentions without writing code.

To learn how to request analytics using the API see the Analyzing Mentions guide.

Streaming Mentions

You can stream mentions in real-time using the Data Streams feature, if this is included in your API package.

To stream mentions you need to provide a Saved Search ID, and a destination URL for where you would like data pushed to. A data stream pushes mentions for a single saved search.

When you create a new data stream the platform will listen for any new documents coming in to the platform that match your search. Any matches will immediately be pushed to your destination URL. These matches (documents) will contain a number of fields such as the URL, title, content, sentiment, and so on.

The fields available for documents depend on the source of the document. See the Content Output Templates page for full details.

The quickest way to get familiar with data streaming is by reading the Streaming Mentions guide.