Analytics API - Getting Started
In this tutorial we'll get you up and running to make your first Analytics API calls. We'll cover:
- Obtaining a Meltwater search
- Making an Analytics API request
The list of endpoints can be found here, where you can read detailed information regarding input and output options, however for the purpose of this quick start guide we will focus on the summary endpoint of the Analytics API.
The Analytics API requires you to provide an API key in order to authenticate and access the Analytics API endpoints. This API key is unique to your Meltwater account and should have already been provided to you via your account representative during the onboarding process, alternatively meltwater support will be able to assist you in regenerating new keys as required. (email@example.com)
If you are an existing Meltwater API customer with access to the Export or Streaming APIs, your existing access key for these services will not be compatible with the Analytics API at this time. It is also worth noting that the authentication process also differs slightly from the other Meltwater APIs.
The APl key should be provided as a request header using the
apikey header in each request, the example below demonstrates the passing of this header in a simple curl request.
curl -X GET 'https://api.meltwater.com/v1/analytics/123456' \ -H 'apikey: **********' \ -H 'Content-Type: application/json'
Obtaining a Meltwater Search
Analytics are generated based on an existing Meltwater Explore saved search, therefore we need to provide a search id as part of the API request. Searches are managed via the Meltwater App to create or find an existing search we need to:
- Login to https://app.meltwater.com/
- Navigate to the Explore section of the Meltwater app. https://app.meltwater.com/explore/list
- Select or Create a search.
- Lookup the search ID in the URL.
Once in the Explore section of the app you will be able to either create or list existing saved searches, as you can see from the screenshot below we have a saved search looking for information regarding Apple and specifically the iPhone in this case.
For more information on how to create and manage explore searches please check out the Meltwater help center articles including Get Started with Explore where you can find information about configuring searches.
Also check out the end of this page for some example boolean searches that can be copied as new searches to get you up and running with some basic data being returned.
Now we have a saved search available. We need to get the ID of that search, the search ID can be found in the URL of the browser, as you can see the search id for this given search is
It is important to note that these search ids are owned by a given Meltwater account therefore it is not possible to share searches between accounts, so the ID value will be specific to your account and API key.
In the explore application it is also possible to configure additional search filters, these are shown in the screenshot above. These filters are saved with the search therefore if you make changes to the filters in the application these changes will be reflected in the results returned by the API.
It is recommended that you use the filter options provided in the API directly rather than configuring the filters using the UI, this is important because it is possible to get conflicting filters between the API and UI.
In addition to Explore Saved Searches, the Analytics API also supports Content Saved Searches. Content Saved Searches can be assigned a type of news, social or broadcast:
- A news search will work in conjunction with an Analytics API call with a source of news.
- A social search will be compatible with an Analytics API request with any of the non-news sources.
- A broadcast search will not return any results when used with the Analytics API.
Making an Analytics API Request
The summary analytics requires us to specify a number of parameters to configure and generate analytics, these parameters include:
The analytics API requires use to specific a single data source we are interested in, this is just a string identifier for the source, available source depends on your given entitlements, a full list can be found in the endpoint documentation.
We need to specify a datetime range of the period we are interested in looking at. Summary analytics have a maximum time window of 31 days, with a look back of up to 15 months. (this may vary depending on your entitlements)
To set this window we provide the following:
end- ISO8601 timestamp, excluding timezone/offset.
tz- An identifier from the IANA TimeZone Database (tzdb), or a timezone offset, from UTC.
We can also optionally specify a number of additional filters includings:
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'.
As seen in the previous section we have our search, this simple search is looking at any information regarding
iPhone. For the purpose of this example we are interested in looking at the Twitter activity for the following 5 days after the Apple event held in California on September 10th, 2019.
As you can see from the sample code above the search id is provided as part of the URL and we set the time period using the start and end query parameters. The event started at 10am in California on September 10th so we use that as our starting point and setting the end point to 5 days later, making sure to set the timezone appropriately. We then set the source type to twitter and provide our API key as a header.
Once we run the query we get back our summary analytics, which includes:
- 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.
As part of the documentation we also provide an interactive open api specification where you can plugin your api key and run api requests. Found here: https://developer.meltwater.com/analytics-api/endpoints/
For additional information on understanding how the Meltwater search works check out the Meltwater Help Center including:
Here are a few simple search queries to get you started:
(apple AND phones AND iphone) NOT (samsung OR android)
(Tesla AND Musk AND Elon AND Cybertruck) NOT (spacex)
(football OR rugby OR soccer OR golf OR Tennis OR cricket)