Managing Saved Searches

You can use the Meltwater API to manage your saved searches for your Meltwater account.

The endpoints specification details the available endpoints for Creating, Reading, Updating and Deleting searches.

Before you try using the API to manage searches please familiarize yourself with Meltwater's search syntax and Source Selection concept explained below.

Boolean Search Syntax

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"

Any boolean syntax that is allowed in the Meltwater application is also allowed with the API.

Limits on 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 OR terms (e.g. a OR b OR c AND...)
• Maximum of 900 AND terms (e.g. a AND 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.

Source Selection

A search query in the Meltwater platform always needs a source selection. A source selection defines a subset of sources to search in.

Some examples of Quick Pick Source Selections would be:

• "Twitter", for a Social search. Only Twitter will be used as the source for the search.
• "Germany" for a News search. Only German news sources will be used for the search.

In addition to Quick Pick Source Selections you can also create your own Custom Selections in the Meltwater app. A Custom Selection can use a combination of different filters to select only the sources you are interested in.

More information is available in the help center article about Source Selection.

When creating a new search you must specify a source_selection_id. To list all available source selections you can use the {{ sourceselectionendpoint }} endpoint.

Search validation

To help you stay within limits and test your API usage the Search create and update endpoints include a dry-run mode. If enabled, search create/update requests will only perform validation of the search and do not create/update the search on success. The response will include validation errors if incorrect parameters are provided or if the search query is too complex.

Example request:

curl -X PUT \
--url "https://api.meltwater.com/v3/searches/12345?dry_run=true" \
--header "Content-Type: application/json" \
--header 'apikey: **********' \
-d "{
  \"search\": {
    \"type\": \"social\",
    \"query\": {
      \"type\": \"boolean\",
      \"source_selection_id\": 12345,
      \"case_sensitivity\": \"no\",
      \"boolean\": \"World And *W*\"
    }
  }
}"

Example response:

{
  "errors": [
    {
      "type": "VALIDATION",
      "title": "Validation error for field: boolean",
      "meta": {
        "validation": "complexity",
        "field": "boolean"
      },
      "details": "The boolean query is too complex. Reason: Wildcards next to a single latin character (e.g. 'A*') are not allowed"
    }
  ]
}