Platform Overview

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

Please take time to read this guide as it will give you a firm basis to understand API features going forwards.

Meltwater platform

The Meltwater platform ingests and enriches data from a wide variety of sources, including news and social platforms. The enriched data is held in a central store with a consistent data schema so that it can be accessed by API customers and application users.

The Meltwater API allows you to access platform data by exporting or analyzing earned media, and fetching analytics for owned social accounts you have configured. 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.

Earned media vs owned social

Throughout the documentation on this site, you will see the terms ‘earned media’ and ‘owned social’. If these are not familiar to you, the following definitions should help:

  • Earned Media - is content the Meltwater platform allows you to listen to, but you do not own. For example, you can listen to mentions of brands and topics in news and social media content. Using the API you can export and analyze this content based upon Saved Searches.

  • Owned Social - is content and posts related to social accounts that you own. For example, if you connect your Facebook account to Meltwater, using the API you can access analytics and posts for this account.

Earned media concepts

The following are concepts and terms you’ll need to know when working with earned media.

Saved Searches

To export content or run analytics on earned media you will need to start with a Saved Search.

A Saved Search can be created in the Meltwater application or 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*")

Essentially the search expresses which content should be matched in the platform for your export or analysis.

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.

Exports

To export earned media using the API you need to provide a Saved Search ID 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. See the Exports Formats and Fields page for full details.

Note that the API offers two formats for export results; CSV and JSON. The JSON format contains all available fields, whereas the CSV format contains a subset of fields which fit most use cases.

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.

The quickest way to get familiar with exports is using the Export Console.

Analytics

To run analytics on earned media 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.

Not all analytics are available for all data sources. To understand what analytics are available see the Analytics Options page.

You can try out the analytics features using the Analytics Console.

Data Streams

To stream earned media using the API you need to provide a Saved Search ID, and a destination URL for where you would like data pushed to.

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 Exports Formats and Fields page for full details.

The quickest way to get familiar with data streaming is by reading the Data Streams - Quickstart Guide.

Owned social concepts

The following are concepts and terms you’ll need to know when working with owned social data.

Source

When using the API for owned social features you will often be asked for a source. A source in this case is the social network you’d like data for, for example Facebook or Instagram.

Connection

In the Meltwater application you configure a connection to bring data from a social network account into the platform.

Read more about how to set up social connections in our help portal.

You can view your owned social connections in the Meltwater application.

Account

A social network account, for example on Facebook, for which you provide your credentials in a connection.

Once you’ve connected an account to the Meltwater platform data for that account will be fetched periodically using the credentials you provided.

Analytics and metrics

Assuming you have connected one or more social accounts, using the API you will be able to fetch metrics (such as the number of fans your Facebook page has), and analytics (such as when your audience is online, or which are your top performing posts).

The metrics that are available from the API are documented on the Owned Social Metrics page.

Metrics for your connected social accounts are updated daily.