Meltwater API

Your Account

How to Guides

API Reference

Help

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.

Search Categories

Currently the Meltwater platform supports two categories of search; Media Intelligence (MI) and Explore.

These two categories exist because of how the platform has evolved. The key difference between the search categories is that Explore searches include all types of data (social, news, etc.), whereas MI searches only include one type of data.

We strongly recommend that you use Explore searches going forwards as we are planning on deprecating MI searches in future.

The remainder of this guide focuses on Explore category searches. If you need to use MI searches please see our separate guide.

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",
      "type": "news",
      "category": "explore",
      "search_id": 12345,
      "name": "SpaceX",
      "id": 12345,
      "query": null
    },
    ...
  ]
}

In the response you can see the ID of each search, along with the name, category, type and when it was last updated.

Note that by default the response will not include the query for each search. You can can include this using the include_query parameter in your request.

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": {
        "type": "news",
        "category": "explore",
        "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"
        },
        "search_id": 12345
    }
}

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": {
          "type": "social",
          "category": "explore",
          "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",
    "category": "explore",
    "type": "social",
    "search_id": 12346,
    "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.
  • category: As explained above the platform supports two categories, but you should use explore here.
  • type: For Explore category searches this field has no impact on the export or analysis results from the API, but must be included for backwards-compatibility on the Meltwater platform.
  • 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 query
  • boolean: use complex boolean expressions for your query
  • combined: 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": []
}

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": {
          "type": "social",
          "category": "explore",
          "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. Note that you cannot update an mi category search to be an explore category search, or vice-versa.

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.

Using filter sets

Filter sets are a feature in the Explore application which allow users to easily apply common filter configurations.

When you get an Explore 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 customer
  • quickpick: 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"
}

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 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.

Testing search definitions

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\",
    \"catetory\": \"explore\",
    \"query\": {
      \"type\": \"boolean\",
      \"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"
    }
  ]
}