Skip to main content

Managing 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

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. Use none for account-level assets, or a workspace ID for assets in a specific workspace.

The endpoint supports pagination with page, page_size (default 10, max 100), and show_hidden (default false).

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,
      "hidden": false
    }
  ]
}

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

Listing searches​

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

Optional parameters: page, page_size (max 100), folder_id, show_hidden (default false).

Getting search details​

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",
    "hidden": false
  }
}

Call the POST /v3/explore_plus/assets/searches endpoint. Three types of search are supported: boolean, keyword, and combined.

Parameters: name, description, color (hex), folder_id, data_collection, query.type.

Boolean searches​

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
  }
}'

case_sensitivity options: yes (exact match), no (case insensitive), hybrid (match capital letters only).

Keyword searches​

--data '{
  "search": {
    "name": "My Search",
    "query": {
      "case_sensitivity": "yes",
      "all_keywords": ["honda"],
      "any_keywords": ["mazda"],
      "not_keywords": ["nissan"],
      "type": "keyword"
    },
    "data_collection": false
  }
}'

Combined searches​

--data '{
  "search": {
    "folder_id": 123,
    "name": "My Search",
    "query": {
      "all_searches": [{"id": 123, "type": "SEARCH"}],
      "any_searches": [{"id": 456, "type": "SEARCH"}],
      "not_searches": [{"id": 789, "type": "SEARCH"}],
      "type": "combined"
    },
    "data_collection": false
  }
}'

Call the PUT /v3/explore_plus/assets/searches/<search_id> endpoint with the same fields as creation. Note that you cannot change the type of a search in an update.

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

Returns a 204 status code on success.