Managing Saved Searches
You can use the Meltwater API to manage the earned media Saved Searches for your Meltwater account.
The endpoints specification details the available endpoints for creating, reading, updating and deleting searches.
We’ve recently made changes to how you create or query searches in the API, including removing the ability to create MI searches. Please see Preparing for upcoming changes to Saved Searches for more information.
Listing Saved Searches
Saved Searches can be created by users in the Meltwater application or through the API.
To list your current Saved Searches you call the GET searches endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/searches" \
--header "Accept: application/json" \
--header "apikey: **********"Example response:
{
"searches": [
{
"updated": "2020-01-10T14:42:10.000Z",
"name": "SpaceX",
"id": 12345,
"query": null
},
...
]
}In the response you can see the ID of each search, along with the name and when it was last updated.
Getting a Saved Search
To get the details for an individual search you call the GET searches/{id} endpoint.
curl -X GET \
--url "https://api.meltwater.com/v3/searches/12345" \
--header "Accept: application/json" \
--header "apikey: **********"Example response:
{
"search": {
"updated": "2020-01-10T14:42:10.000Z",
"id": 12345,
"name": "SpaceX",
"query": {
"filter_set": null,
"case_sensitivity": "no",
"not_keywords": [],
"any_keywords": [],
"all_keywords": [
"Spacex"
],
"type": "keyword"
}
}
}When you fetch a search the result includes the query.
Creating a Saved Search
To create a Saved Search you call the POST searches endpoint, passing a search object as the payload. For example:
curl -X POST \
--url "https://api.meltwater.com/v3/searches" \
--header 'Content-Type: application/json' \
--header "apikey: **********" \
--data-raw '{
"search": {
"name": "Example search",
"query": {
"case_sensitivity": "no",
"boolean": "(\"business intelligence\")",
"type": "boolean"
}
}
}'If your request is successful the API will respond with the 201 status code and the saved definition of the search, including the ID of the new search.
{
"search": {
"updated": "2020-08-23T08:25:56.000Z",
"query": {
"type": "boolean",
"case_sensitivity": "no",
"boolean": "(\"business intelligence\")"
},
"name": "Example search",
"id": 12346
}
}Search object definition
The search object has the following fields:
name: The name you want to give your search. Note that you cannot have the same name for two different searches.query: An object that defines your search query, explained below.
Query object definition
There are three search query types supported by the Meltwater platform:
keyword: use simple lists of keywords for your queryboolean: use complex boolean expressions for your querycombined: combine existing saved searches as a new query
An example keyword query, searching for all mentions of ‘SpaceX’ but excluding mentions of ‘Richard Branson’ would be:
"query": {
"type": "keyword",
"not_keywords": [
"Richard Branson"
],
"any_keywords": [],
"all_keywords": [
"SpaceX"
],
"case_sensitivity": "no"
}An example boolean query, searching for the phrase ‘business intelligence’ would be:
"query": {
"type": "boolean",
"boolean": "(\"business intelligence\")",
"case_sensitivity": "no"
}The boolean syntax used for Meltwater searches is not covered in the developer documentation as it is core platform feature. To learn more about Meltwater’s boolean search syntax please read the help center article “What is Boolean” and for further reference to applicable operators, please see “The Complete Boolean Library”
An example combined query, including all matches from searches 123 and 124, but excluding matches from search 125 would be:
"query": {
"type": "combined",
"not_searches": [125],
"any_searches": [123,124],
"all_searches": []
}For more details on combined searches, see the Working with Combined Searches section below.
Updating a Saved Search
To update a search you call the PUT searches/{id} endpoint, passing a search object as the payload. For example:
curl -X PUT \
--url "https://api.meltwater.com/v3/searches/12345" \
--header 'Content-Type: application/json' \
--header "apikey: **********" \
--data-raw '{
"search": {
"name": "Example search - updated",
"query": {
"case_sensitivity": "no",
"boolean": "(\"business intelligence tools\")",
"type": "boolean"
}
}
}'The search object has the same fields as when creating a search.
If your request is successful the API will respond with the 200 status code and the saved definition of the search.
Please note that if you update a saved search created in the application by a user it may have a filter set applied. When updating a search with a filter set you need to be sure you are not removing the filter set applied. Read the section below on filters sets to learn more.
Deleting a Saved Search
To delete a search you call the DELETE searches/{id} endpoint. For example:
curl -X DELETE \
--url "https://api.meltwater.com/v3/searches/12346" \
--header "Accept: application/json" \
--header "apikey: **********"If your request is successful the API will respond with the 204 status code.
Working with Filter Sets
Filter Sets are a feature in the Explore application which allow users to easily apply common filter configurations.
When you get a search from the API there is a field returned under query called filter_set. This can either be null (no filter set is applied to the search), or be an object with one of two types:
embedded: a user in the application has applied filters to a search, but not a ‘saved’ filter set.saved: a saved filter set is applied to the search.
For ‘saved’ filter sets there are two sub-types supported by the platform:
custom: a filter set saved by a customerquickpick: a filter set defined by Meltwater
Currently the API allows you to list saved filter sets, and apply these when creating and updating saved searches. The API does not support creating, updating or deleting filter sets. Also, the API does not support applying un-saved / adhoc filters to searches at this time.
Listing filter sets
You can list the filter sets available to you by calling the GET filter_sets endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/filter_sets?include_quickpicks=true" \
--header "Accept: application/json" \
--header "apikey: **********"Example response:
{
"filter_sets": [
{
"id": 488068,
"name": "My example filter set",
"subtype": "custom",
"type": "saved"
},
{
"id": 583050,
"name": "UK news",
"subtype": "quickpick",
"type": "saved"
},
...
]
}Creating a search with a filter set
You can use saved filter sets when creating saved searches, by passing a filter_set object as part of the query object, passing saved as the type and the id of the filter set:
{
"type": "boolean",
"case_sensitivity": "no",
"boolean": "(\"business intelligence\")",
"filter_set": {
"type": "saved",
"id": 488069
}
}Updating a search with a filter set
When you update a search with a filter set applied you need to make sure you are preserving the filter set (if this is appropriate).
If the saved search has a saved filter set applied, make sure you pass in the filter set object with the filter set id.
"filter_set": {
"type": "saved",
"id": 488069
}If the saved search has a embedded filter applied, you can preserve the filter settings by passing in a filter set object with type embedded:
"filter_set": {
"type": "embedded"
}Working with Combined Searches
When you manage Combined Searches through the API, the API assumes that the IDs you provide are for Saved Searches as this was the original design of this feature in the application. Combined Searches now allow you to also use Filter Sets and Custom Categories as part of your combined search definitions.
To work with these new concepts, our API endpoints now support a new optional parameter (expand_combined), which when set to true includes the type of search object in API calls and responses.
Creating a Combined Search using different search types
As an example, the following request creates a combined search which includes data from a Saved Search, but uses a Custom Category as an exclusion filter:
curl -X POST \
--url "https://api.meltwater.com/v3/searches?expand_combined=true" \
--header 'Content-Type: application/json' \
--header "apikey: **********" \
--data-raw '{
"search": {
"name": "Example search",
"query": {
"filter_set": null,
"not_searches": [
{
"id": 456,
"type": "CUSTOM_CATEGORY"
}
],
"any_searches": [
{
"id": 123,
"type": "SEARCH"
}
],
"all_searches": [],
"type": "combined"
}
}
}'The API would return the following response:
{
"search": {
"updated": "2020-08-23T08:25:56.000Z",
"query": {
"filter_set": null,
"not_searches": [
{
"id": 456,
"type": "CUSTOM_CATEGORY"
}
],
"any_searches": [
{
"id": 123,
"type": "SEARCH"
}
],
"all_searches": [],
"type": "combined"
},
"name": "Example search",
"id": 12346
}
}Available values for type are SEARCH, FILTER_SET and CUSTOM_CATEGORY.
You can update a search using the same optional parameter and types.
Fetching Combined Searches with search types included
You can also use the expand_combined query parameter when fetching searches to include the extra context.
curl -X GET \
--url "https://api.meltwater.com/v3/searches/12346?expand_combined=true" \
--header "Accept: application/json" \
--header "apikey: **********"Example response:
{
"search": {
"updated": "2020-08-23T08:25:56.000Z",
"query": {
"filter_set": null,
"not_searches": [],
"any_searches": [
{
"id": 123,
"type": "SEARCH"
}
],
"all_searches": [
{
"id": 987,
"type": "CUSTOM_CATEGORY"
}
],
"type": "combined"
},
"name": "Example search",
"id": 12346
}
}Boolean query complexity
Using boolean syntax you can create very complex queries. The Meltwater platform supports complex searches, but to protect the platform and other customers we do estimate the complexity of your search and will prevent searches which are extremely complex.
When you create or update a search through the API, if the query is too complex you will receive a 422 error. The error object for 422 contains a meta object which can be used to distinguish between different types of unprocessable requests.
To prevent this from happening, please follow these guidelines:
- Try to avoid using excessive wildcards and
NEARs. - Maximum of 5,000 terms (e.g.
a OR b AND c AND ...) - Maximum query length of 80,000 characters
We keep the right to modify these limitations further in the future. While it is of course our goal to make our search system as powerful as possible, it might be required for us in the future to enforce the above limits or modify them. We will announce this accordingly to customers that are affected by these limits.