Managing Legacy Saved Searches

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

This guide focuses on legacy Media Intelligence (MI) category saved searches, which will be deprecated in future in favour of Explore category searches.

Search categories are explained in the main Managing Saved Searches guide, along with topics such as search complexity.

Source Selection

Legacy searches in the Meltwater platform always need 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. To list all available source selections you call the GET source_selections endpoint.

curl -X GET \
  --url "https://api.meltwater.com/v3/source_selections" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The response is a list of source selections, including the id for each:

{
  "source_selections": [
    {
      "type": "news",
      "name": "All Sources",
      "id": 1,
      "custom": false
    },
    ...
  ]
}

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": "mi",
      "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.

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": "mi",
        "updated": "2020-01-10T14:42:10.000Z",
        "id": 12345,
        "name": "SpaceX",
        "query": {
            "source_selection_id": 41,
            "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.

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": "news",
          "category": "mi",
          "name": "Example search",
          "query": {
              "case_sensitivity": "no",
              "source_selection_id": 41,
              "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": "mi",
    "type": "news",
    "search_id": 12346,
    "query": {
      "type": "boolean",
      "case_sensitivity": "no",
      "source_selection_id": 41,
      "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: For legacy searches this is mi.
  • type: One of social, news, or broadcast depending on the type of data you are searching for.
  • query: An object that defines your search query, explained below.

Query object definition

There are two search query types supported by the Meltwater platform for legacy searches:

  • keyword: use simple lists of keywords for your query
  • boolean: use complex boolean expressions for your 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"
    ],
    "source_selection_id": 41,
    "case_sensitivity": "no"
}

An example boolean query, searching for the phrase ‘business intelligence’ would be:

"query": {
    "type": "boolean",
    "boolean": "(\"business intelligence\")",
    "source_selection_id": 41,
    "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”

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": "news",
          "category": "mi",
          "name": "Example search - updated",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence tools\")",
              "type": "boolean",
              "source_selection_id": 41
          }
      }
  }'

If your request is successful the API will respond with the 200 status code and the saved definition of the 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.