Key API Concepts
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 content or running analytics requests on the content.
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 tweets, whereas due to Twitter’s terms of service in the API we can only provide the ID of a tweet. An API customer needs to call the Twitter API to rehydrate the tweet in order to get the tweet text.
Saved Searches
To export data or run analytics 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 metion Apple watches you may write:
apple AND (watch 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 content 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.
See our guides for getting started with exports:
Analytics
To fetch analytics 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.
See the Analytics - API Quickstart to get started with analytics.
Usage & Limits
All API customers are subject to API limits. These limits depend on the API package purchased.
See the Usage Limits page for a detailed look at limits.
Getting Help
If you need help getting started please ask your account manager or contact our Support team.