Managing Optimized Searches

In this tutorial we’ll cover the basics of creating, updating and deleting searches in Explore+ using the API.

Before you start

To run through this tutorial, you will need:

  • Your Meltwater API token

Authentication

You need to provide your API token when you call any Meltwater API endpoint.

You provide the API token as a header called apikey, for example:

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

For full details take a look at the Authentication page.

Search folders

In Explore+ folders are used to organize searches in your account. To fetch the folders configured in your account you can call the GET /v3/explore_plus/assets/searches/folders endpoint:

curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches/folders?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The workspace_id parameter is mandatory. As explained in the Explore+ API overview, use none as the value if you want to access assets at the account-level, or a workspace id if you want to access assets in a specific workspace.

Note that the endpoint supports pagination using the following optional parameters:

  • page - the page of results to fetch. Defaults to 1.
  • page_size - the number of searches to fetch. Defaults to 10, max is 100.

Example response:

{
  "page": 1,
  "page_size": 10,
  "total": 2,
  "folders": [
    {
      "id": 123,
      "name": "My Search Folder",
      "color": "#FFFFFF",
      "created": "2025-01-01T00:00:00Z",
      "updated": "2025-01-01T00:00:00Z",
      "num_searches": 1,
      "parent": null
    },
    {
      "id": 456,
      "name": "My Second Search Folder",
      "color": "#FFFFFF",
      "created": "2025-01-01T00:00:00Z",
      "updated": "2025-01-01T00:00:00Z",
      "num_searches": 1,
      "parent": 123
    }
  ]
}

As folders can be nested in Explore+ you can use the parent field in the response to understand the relationship between folders.

Listing searches

You can use the GET /v3/explore_plus/assets/searches endpoint to list your current searches:

curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The workspace_id parameter is mandatory. As explained in the Explore+ API overview, use none as the value if you want to access assets at the account-level, or a workspace id if you want to access assets in a specific workspace.

Note that the endpoint supports the following optional parameters:

  • page - the page of results to fetch. Defaults to 1.
  • page_size - the number of searches to fetch. Defaults to 10, max is 100.

Example response:

{
  "page": 1,
  "page_size": 10,
  "total": 12,
  "searches": [
    {
      "id": 123,
      "folder_id": 456,
      "name": "My Search",
      "description": "This is my search",
      "updated": "2024-01-01T00:00:00Z",
      "type": "keyword",
	"query": {...},
	"data_collection": false,
	"data_collection_updated": "2024-01-01T00:00:00Z"
    },
    ...
  ]
}

Getting search details

To fetch full details of an individual search in your account, you can call the GET /v3/explore_plus/assets/searches/<search_id> endpoint.

For example to fetch the search with ID “123” in your account:

curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches/123?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

Example response:

{
  "search": {
    "id": 123,
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false,
    "data_collection_updated": "2025-01-01T00:00:00Z"
  }
}

The API returns details such as the search name, when it was created, and the query set for that search.

To create a new search in your account you can call the POST /v3/explore_plus/assets/searches endpoint.

Currently three types of search are supported:

  • boolean - a search with a boolean string query
  • keyword - a search using simple keywords
  • combined - a search which is a combination of existing searches

When creating searches you can make use of the following parameters:

  • name - the name of your search
  • description - a description for your search
  • color - a hex color value for your search used in the application
  • folder_id - to create the search in a specific folder in your account (defaults to creating a search in the root folder)
  • data_collection - specifies whether data should be collected for this new search immediately on creation
  • query.type - the type of search to create

Boolean searches

For boolean searches you can specify:

  • query.boolean - the boolean query for the search
  • query.case_sensitivity - specifies the case-sensitivity mode for the search (yes = exact match, no = no case sensitive matching, hybrid = match capital letters only)

As an example this request will create a basic boolean search:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "search": {
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false
  }
}'

Example response:

{
  "search": {
    "id": 123,
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false,
    "data_collection_updated": "2025-01-01T00:00:00Z"
  }
}

Keyword searches

For keyword searches you can specify:

  • query.all_keywords - mentions must contain all these words
  • query.any_keywords - mentions must contain at least one of these words
  • query.not_keywords - mentions must not contain any of these words
  • query.case_sensitivity - specifies the case-sensitivity mode for the search (yes = exact match, no = no case sensitive matching, hybrid = match capital letters only)

This example shows how to create a keyword search:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "search": {
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "query": {
      "case_sensitivity": "yes",
      "all_keywords": [
        "honda"
      ],
      "any_keywords": [
        "mazda"
      ],
      "not_keywords": [
        "nissan"
      ],
      "type": "keyword"
    },
    "data_collection": false
  }
}'

Combined searches

For combined searches you can specify:

  • query.all_searches - mentions must match all of these searches
  • query.any_searches - mentions must match at least one of these searches
  • query.not_searches - mentions must not match any of these searches

This example shows how to create a combined search:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "search": {
    "folder_id": 123,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "query": {
      "all_searches": [
        {
          "id": 123,
          "type": "SEARCH"
        }
      ],
      "any_searches": [
        {
          "id": 456,
          "type": "SEARCH"
        }
      ],
      "not_searches": [
        {
          "id": 789,
          "type": "SEARCH"
        }
      ],
      "type": "combined"
    },
    "data_collection": false
  }
}'

To update a search in your account you can call the PUT /v3/explore_plus/assets/searches/<search_id> endpoint.

As an example this request will update an existing boolean search:

curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/searches/123?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "search": {
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false
  }
}'

Example response:

{
  "search": {
    "id": 123,
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false,
    "data_collection_updated": "2025-01-01T00:00:00Z"
  }
}

You can use the same fields as described in the search creation section above, however note that you cannot change the type of a search in an update.

To delete a search you can call the DELETE /v3/explore_plus/assets/searches/<search_id> endpoint with the ID of the search you wish to delete.

For example to delete the search with ID “123” in your account:

curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches/123?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The API will return a 204 status code if the search is deleted successfully.