openapi: 3.0.3
info:
title: Meltwater Account Management Listening Analytics API
description: The Meltwater Public API
contact:
name: Meltwater Support
url: https://developer.meltwater.com/
email: support@api.meltwater.com
version: '1.0'
servers:
- url: https://api.meltwater.com
security:
- apikey: []
tags:
- name: Listening Analytics
description: Analyse multiple types of Meltwater data, run volume time series, top tags and sentiment counts.
parent: Listening
paths:
/v3/analytics/{searchId}:
get:
tags:
- Listening Analytics
summary: A summary of analytics for a Saved Search.
description: 'The summary is produced only for documents matching the Saved Search,
from the specified document sources, and within the specified time-range.
Any other parameters provided, such as language or country, will further
restrict the documents that are included in the analysis.
The `unique_authors` value can only be calculated for sources other than `news`.
When run against `news` it will return 0.
'
operationId: getV3Analytics-searchId-start-end-tz-source-country-language-company_id
parameters:
- name: searchId
in: path
description: The ID of the Saved Search.
required: true
schema:
type: string
- name: start
in: query
description: 'The timestamp of the start of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-27T00:00:00'
example: '2021-09-27T00:00:00'
- name: end
in: query
description: 'The timestamp of the end of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-28T00:00:00'
example: '2021-09-28T00:00:00'
- name: tz
in: query
description: 'The timezone ID for all timestamps in the request and response.
An identifier from the IANA TimeZone Database (tzdb),
or a timezone offset, from UTC.
An offset, or `UTC`, will provide a stable timezone that remains
the same, year-round.
A location ID, such as `Europe/London`, will automatically
incorporate that location''s local timezone rules, including
daylight-savings (if applicable), and any other adjustments to
local time. There is a full list available on [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
As a consequence: when using a location ID, it is possible for
time-ranges that cross a timezone adjustment in that locale to be
longer or shorter than you might expect; e.g. a day with 23 or 25
hours when a daylight savings adjustment occurs.
The `start` and `end` parameters in your request will be interpreted
to be local to this timezone.
All timestamps, dates and times in the response will be generated
local to this timezone.'
required: true
schema:
type: string
example: Europe/London
- name: source
in: query
description: The data source to query. By default all available sources are included however you can also provide multiple source values to filter.
schema:
type: string
example: twitter
enum:
- forums
- blogs
- douyin
- sina_weibo
- twitch
- facebook
- reddit
- wechat
- news
- pinterest
- twitter
- instagram
- little_red_book
- bilibili
- youku
- kakaotalk
- linevoom
- tiktok
- broadcast
- name: country
in: query
description: 'The origin country of documents to include in the query.
The two-letter ISO 3166-1 Alpha-2 country code, or ''ZZ''.
Besides the two letter [ISO 3166-1 Alpha-2 country code](https://www.iso.org/obp/ui/#search/code/)
of a country, ''ZZ'' may be used to indicate ''Unknown country of origin''.
This restricts the documents queried to include only those that
originated from a particular country.
If multiple countries are specified, documents that originated from any
of those countries will be included in results.
Documents that originated in some countries may be restricted from your
queries automatically, based on your jurisdiction and entitlements.'
style: form
explode: true
schema:
type: array
items:
type: string
example:
- US
- name: language
in: query
description: "The language of documents to include in the query.\n\nA primary language subtag from the IANA language tag registry, 'zh-Hant',\n'zh-Hans' or 'zz'.\n\nIn addition to two and three letter primary subtags from the\n[IANA language tag registry](https://www.w3.org/International/articles/language-tags/#language),\nthe following special language codes are also supported:\n\n * `zh-Hans` - for Simplified Chinese\n * `zh-Hant` - for Traditional Chinese\n * `zz` - for unknown language\n\nThis restricts the documents queried to include only those in a\nparticular language.\n\nIf multiple languages are specified, documents in any of those languages\nwill be included in the results."
style: form
explode: true
schema:
type: array
items:
type: string
example:
- en
- name: company_id
in: query
description: Company which owns the given searchId. If not specified your default company is used.
schema:
type: string
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailed'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitedError'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsServiceUnavailable'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SummaryResponse'
deprecated: false
/v3/analytics/{searchId}/top_tags:
get:
tags:
- Listening Analytics
summary: The top tags that occur in a Saved Search.
description: 'Produces a ranked list of tags that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.
The `size` parameter controls the number of top tags produced,
defaulting to the top `10` tags.
Any other parameters provided, such as language or country, will further
restrict the documents that have their tags included.
The type of tags included, such as Twitter "hashtags", will depend on the
selected sources.'
operationId: getV3AnalyticsTop_tags-searchId-start-end-tz-source-country-language-size-company_id
parameters:
- name: searchId
in: path
description: The ID of the Saved Search.
required: true
schema:
type: string
- name: start
in: query
description: 'The timestamp of the start of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-27T00:00:00'
example: '2021-09-27T00:00:00'
- name: end
in: query
description: 'The timestamp of the end of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-28T00:00:00'
example: '2021-09-28T00:00:00'
- name: tz
in: query
description: 'The timezone ID for all timestamps in the request and response.
An identifier from the IANA TimeZone Database (tzdb),
or a timezone offset, from UTC.
An offset, or `UTC`, will provide a stable timezone that remains
the same, year-round.
A location ID, such as `Europe/London`, will automatically
incorporate that location''s local timezone rules, including
daylight-savings (if applicable), and any other adjustments to
local time. There is a full list available on [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
As a consequence: when using a location ID, it is possible for
time-ranges that cross a timezone adjustment in that locale to be
longer or shorter than you might expect; e.g. a day with 23 or 25
hours when a daylight savings adjustment occurs.
The `start` and `end` parameters in your request will be interpreted
to be local to this timezone.
All timestamps, dates and times in the response will be generated
local to this timezone.'
required: true
schema:
type: string
example: Europe/London
- name: source
in: query
description: The data source to query. By default all available sources are included however you can also provide multiple source values to filter.
schema:
type: string
example: twitter
enum:
- facebook
- instagram
- twitter
- tiktok
- name: country
in: query
description: 'The origin country of documents to include in the query.
The two-letter ISO 3166-1 Alpha-2 country code, or ''ZZ''.
Besides the two letter [ISO 3166-1 Alpha-2 country code](https://www.iso.org/obp/ui/#search/code/)
of a country, ''ZZ'' may be used to indicate ''Unknown country of origin''.
This restricts the documents queried to include only those that
originated from a particular country.
If multiple countries are specified, documents that originated from any
of those countries will be included in results.
Documents that originated in some countries may be restricted from your
queries automatically, based on your jurisdiction and entitlements.'
style: form
explode: true
schema:
type: array
items:
type: string
example:
- US
- name: language
in: query
description: "The language of documents to include in the query.\n\nA primary language subtag from the IANA language tag registry, 'zh-Hant',\n'zh-Hans' or 'zz'.\n\nIn addition to two and three letter primary subtags from the\n[IANA language tag registry](https://www.w3.org/International/articles/language-tags/#language),\nthe following special language codes are also supported:\n\n * `zh-Hans` - for Simplified Chinese\n * `zh-Hant` - for Traditional Chinese\n * `zz` - for unknown language\n\nThis restricts the documents queried to include only those in a\nparticular language.\n\nIf multiple languages are specified, documents in any of those languages\nwill be included in the results."
style: form
explode: true
schema:
type: array
items:
type: string
example:
- en
- name: size
in: query
description: 'The maximum number of results to produce.
From 1 to 1000 inclusive.
Only the top/first results will be produced.'
schema:
type: string
- name: company_id
in: query
description: Company which owns the given searchId. If not specified your default company is used.
schema:
type: string
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailed'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitedError'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsServiceUnavailable'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TopTagsResponse'
deprecated: false
/v3/analytics/{searchId}/top_locations:
get:
tags:
- Listening Analytics
summary: The top locations that occur in a Saved Search.
description: 'Produces a ranked list of locations that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.
The `size` parameter controls the number of top locations produced,
defaulting to the top `100` locations.
The level parameter allows you to select the level of location you want from country, state or city.
Any other parameters provided, such as language or country, will further
restrict the documents that have their keyphrases included.
'
operationId: getV3AnalyticsTop_locations-searchId-start-end-tz-source-country-language-size-level-company_id
parameters:
- name: searchId
in: path
description: The ID of the Saved Search.
required: true
schema:
type: string
- name: start
in: query
description: 'The timestamp of the start of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-27T00:00:00'
example: '2021-09-27T00:00:00'
- name: end
in: query
description: 'The timestamp of the end of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-28T00:00:00'
example: '2021-09-28T00:00:00'
- name: tz
in: query
description: 'The timezone ID for all timestamps in the request and response.
An identifier from the IANA TimeZone Database (tzdb),
or a timezone offset, from UTC.
An offset, or `UTC`, will provide a stable timezone that remains
the same, year-round.
A location ID, such as `Europe/London`, will automatically
incorporate that location''s local timezone rules, including
daylight-savings (if applicable), and any other adjustments to
local time. There is a full list available on [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
As a consequence: when using a location ID, it is possible for
time-ranges that cross a timezone adjustment in that locale to be
longer or shorter than you might expect; e.g. a day with 23 or 25
hours when a daylight savings adjustment occurs.
The `start` and `end` parameters in your request will be interpreted
to be local to this timezone.
All timestamps, dates and times in the response will be generated
local to this timezone.'
required: true
schema:
type: string
example: Europe/London
- name: source
in: query
description: The data source to query. By default all available sources are included however you can also provide multiple source values to filter.
schema:
type: string
example: twitter
enum:
- forums
- blogs
- douyin
- sina_weibo
- twitch
- reddit
- wechat
- news
- pinterest
- twitter
- little_red_book
- bilibili
- youku
- kakaotalk
- linevoom
- broadcast
- name: country
in: query
description: 'The origin country of documents to include in the query.
The two-letter ISO 3166-1 Alpha-2 country code, or ''ZZ''.
Besides the two letter [ISO 3166-1 Alpha-2 country code](https://www.iso.org/obp/ui/#search/code/)
of a country, ''ZZ'' may be used to indicate ''Unknown country of origin''.
This restricts the documents queried to include only those that
originated from a particular country.
If multiple countries are specified, documents that originated from any
of those countries will be included in results.
Documents that originated in some countries may be restricted from your
queries automatically, based on your jurisdiction and entitlements.'
style: form
explode: true
schema:
type: array
items:
type: string
example:
- US
- name: language
in: query
description: "The language of documents to include in the query.\n\nA primary language subtag from the IANA language tag registry, 'zh-Hant',\n'zh-Hans' or 'zz'.\n\nIn addition to two and three letter primary subtags from the\n[IANA language tag registry](https://www.w3.org/International/articles/language-tags/#language),\nthe following special language codes are also supported:\n\n * `zh-Hans` - for Simplified Chinese\n * `zh-Hant` - for Traditional Chinese\n * `zz` - for unknown language\n\nThis restricts the documents queried to include only those in a\nparticular language.\n\nIf multiple languages are specified, documents in any of those languages\nwill be included in the results."
style: form
explode: true
schema:
type: array
items:
type: string
example:
- en
- name: size
in: query
description: 'The maximum number of results to produce.
From 1 to 1000 inclusive.
Only the top/first results will be produced.'
schema:
type: string
- name: level
in: query
description: 'The level of location to be used, may be one of: country, state, city'
required: true
schema:
type: string
enum:
- city
- country
- state
- name: company_id
in: query
description: Company which owns the given searchId. If not specified your default company is used.
schema:
type: string
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailed'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitedError'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsServiceUnavailable'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TopLocationsResponse'
deprecated: false
/v3/analytics/{searchId}/top_shared:
get:
tags:
- Listening Analytics
summary: The top shared documents that occur in a Saved Search.
description: 'Produces a ranked list of documents matching the Saved Search that were
the most shared, from the specified document sources, and within the
specified time-range.
The `size` parameter controls the number of top shared documents
produced, defaulting to the top `10` top shared documents.
Any other parameters provided, such as language or country, will further
restrict the documents that are included.
The `sort_by` parameter controls the ranking of the results. For example,
if `sort_by=retweets`, the results will be the top N documents by retweet
count. Retweet results are based on when the retweet occured, not the
creation date of the original tweet'
operationId: getV3AnalyticsTop_shared-searchId-start-end-tz-source-country-language-size-sort_by-company_id
parameters:
- name: searchId
in: path
description: The ID of the Saved Search.
required: true
schema:
type: string
- name: start
in: query
description: 'The timestamp of the start of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-27T00:00:00'
example: '2021-09-27T00:00:00'
- name: end
in: query
description: 'The timestamp of the end of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-28T00:00:00'
example: '2021-09-28T00:00:00'
- name: tz
in: query
description: 'The timezone ID for all timestamps in the request and response.
An identifier from the IANA TimeZone Database (tzdb),
or a timezone offset, from UTC.
An offset, or `UTC`, will provide a stable timezone that remains
the same, year-round.
A location ID, such as `Europe/London`, will automatically
incorporate that location''s local timezone rules, including
daylight-savings (if applicable), and any other adjustments to
local time. There is a full list available on [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
As a consequence: when using a location ID, it is possible for
time-ranges that cross a timezone adjustment in that locale to be
longer or shorter than you might expect; e.g. a day with 23 or 25
hours when a daylight savings adjustment occurs.
The `start` and `end` parameters in your request will be interpreted
to be local to this timezone.
All timestamps, dates and times in the response will be generated
local to this timezone.'
required: true
schema:
type: string
example: Europe/London
- name: source
in: query
description: The data source to query. By default all available sources are included however you can also provide multiple source values to filter.
schema:
type: string
example: twitter
enum:
- twitter
- name: country
in: query
description: 'The origin country of documents to include in the query.
The two-letter ISO 3166-1 Alpha-2 country code, or ''ZZ''.
Besides the two letter [ISO 3166-1 Alpha-2 country code](https://www.iso.org/obp/ui/#search/code/)
of a country, ''ZZ'' may be used to indicate ''Unknown country of origin''.
This restricts the documents queried to include only those that
originated from a particular country.
If multiple countries are specified, documents that originated from any
of those countries will be included in results.
Documents that originated in some countries may be restricted from your
queries automatically, based on your jurisdiction and entitlements.'
style: form
explode: true
schema:
type: array
items:
type: string
example:
- US
- name: language
in: query
description: "The language of documents to include in the query.\n\nA primary language subtag from the IANA language tag registry, 'zh-Hant',\n'zh-Hans' or 'zz'.\n\nIn addition to two and three letter primary subtags from the\n[IANA language tag registry](https://www.w3.org/International/articles/language-tags/#language),\nthe following special language codes are also supported:\n\n * `zh-Hans` - for Simplified Chinese\n * `zh-Hant` - for Traditional Chinese\n * `zz` - for unknown language\n\nThis restricts the documents queried to include only those in a\nparticular language.\n\nIf multiple languages are specified, documents in any of those languages\nwill be included in the results."
style: form
explode: true
schema:
type: array
items:
type: string
example:
- en
- name: size
in: query
description: 'The maximum number of results to produce.
From 1 to 100 inclusive.
Only the top/first results will be produced.'
schema:
type: string
- name: sort_by
in: query
description: Field to rank results by.
required: true
schema:
type: string
example: retweets
enum:
- retweets
- name: company_id
in: query
description: Company which owns the given searchId. If not specified your default company is used.
schema:
type: string
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailed'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitedError'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsServiceUnavailable'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TopSharedResponse'
deprecated: false
/v3/analytics/{searchId}/top_entities:
get:
tags:
- Listening Analytics
summary: The top named entities that occur in a Saved Search.
description: 'Produces a ranked list of entities that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.
The `size` parameter controls the number of top keyphrases produced,
defaulting to the top `100` keyphrases.
The sentiment parameter allows you to select the sentiment of the documents to analyze.
Any other parameters provided, such as language or country, will further
restrict the documents that have their keyphrases included.
'
operationId: getV3AnalyticsTop_entities-searchId-start-end-tz-source-country-language-size-sentiment-company_id
parameters:
- name: searchId
in: path
description: The ID of the Saved Search.
required: true
schema:
type: string
- name: start
in: query
description: 'The timestamp of the start of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-27T00:00:00'
example: '2021-09-27T00:00:00'
- name: end
in: query
description: 'The timestamp of the end of the time-range to query.
An ISO8601 timestamp, excluding timezone/offset.
Includes both the date and time components of the ISO8601 timestamp, but
_excludes_ the timezone offset component. The timestamp represents the
local time at the timezone given in the `tz` parameter.'
required: true
schema:
type: string
example: '2021-09-28T00:00:00'
example: '2021-09-28T00:00:00'
- name: tz
in: query
description: 'The timezone ID for all timestamps in the request and response.
An identifier from the IANA TimeZone Database (tzdb),
or a timezone offset, from UTC.
An offset, or `UTC`, will provide a stable timezone that remains
the same, year-round.
A location ID, such as `Europe/London`, will automatically
incorporate that location''s local timezone rules, includin
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/meltwater/refs/heads/main/openapi/meltwater-listening-analytics-api-openapi.yml