Searching Mentions

In this tutorial we’ll cover the basics of searching and fetching mentions from Explore+ using the API.

Before you start

To run through this tutorial, you will need:

  • Your Meltwater API token
  • An Optimized Search in your Explore+ instance

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.

Listing your Optimized Searches

Unless you have a set of specific mention IDs to fetch, to search mentions you will need to provide one more search ids to the API search endpoint.

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"
    },
    ...
  ]
}

You’ll use the id field for searches in your search requests to the API.

Search output options

Before we look at some example search requests, let’s take a look at the output options supported by the API.

For a search request you can use the following parameters:

  • template - The template you wish the documents to be formatted in. Defaults to api.json.
  • page - the page of results to fetch. Defaults to 1.
  • page_size - the number of searches to fetch. Defaults to 10, max is 100.
  • sort_by - The sort field of results, one of date, reach, engagement, social_echo, relevance, prominence, or views. Defaults to date.
  • sort_order - The sort order of results, either asc (ascending) or desc (descending). Defaults to desc.

See the Content Output Templates page for full details of fields included in output templates.

As an example the following parameters would fetch the first page of 100 results, ordered by date descending, and output results using the api.json template.

{
    "page": 1,
    "page_size": 100,
    "sort_by": "date",
    "sort_order": "desc",
    "template": {
        "name": "api.json"
    }
}

Searching mentions using Optimized Searches

You can use the POST /v3/explore_plus/search endpoint to fetch mentions based upon your searches.

Here’s an example request which we’ll break down below in detail, given the number of options available:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/search?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "searches": {
    "all": [123],
    "any": [],
    "none": []
  },
  "start": "2024-10-01T00:00:00",
  "end": "2024-10-08T00:00:00",
  "page": 1,
  "page_size": 100,
  "sort_by": "date",
  "sort_order": "desc",
  "tz": "UTC",
  "template": {
    "name": "api.json"
  }
}'

Time period

For each request you must specify a time window using the following parameters:

  • start and end - The time period you’d like to analyze (ISO8601 timestamps, excluding timezone/offset). Note that the result will be inclusive of the start time and exclusive of the end time.
  • tz - An identifier from the IANA database, or a timezone offset, from UTC.

The maximum time range for a search is 12 months.

For example the following parameters will apply a time window of 1st October 2024 to the 8th October 2024, in UTC.

{
    "start": "2024-10-01T00:00:00",
    "end": "2024-10-08T00:00:00",
    "tz": "UTC"
}

Searches

For each request you must also specify the searches you’d like to be processed.

To specify searches use the ID of each search within the following fields:

  • all - results must be in all these searches
  • any - results can be in any of these searches
  • none - exclude results from these searches

For example the following parameters will include mentions that match any of the two searches (123, 456) but exclude mentions which appear in the search 789.

{
    "searches": {
        "all": [],
        "any": [123,465],
        "none": [789]
    }
}

Filters

When searching you can optionally apply standard filters and filters based upon your custom fields.

To specify filters you can use the following fields in your request:

  • sources - the source(s) you’d like to analyze, for example, news or blogs. If not provided, your request will analyze all sources. You can provide multiple values to analyze across multiple sources.
  • languages - A primary language subtag from the IANA language tag registry, zh-Hant, zh-Hans, or zz.
  • countries - The two-letter ISO 3166-1 Alpha-2 country code, or ZZ for unknown.
  • sentiments - The sentiment of the results. Possible values are positive, negative, and neutral.
  • custom_fields - Filters for results that match the given Custom Field’s values.

For more information on Custom Fields, including how to fetch the IDs of fields for use in searching mentions see the Managing Custom Fields guide.

For each of these fields you can combine multiple values using ‘all’, ‘any’ and ‘none’.

For example, these parameters would include all languages except French and German, include only positive and neutral documents, and filter to documents that match value with ID 123 from your custom field with ID 456:

{
    "filters": {
    "languages": {
      "none": ["de", "fr"]
    },
    "sentiments": {
      "any": ["positive", "neutral"]
    },
    "custom_fields": {
      "456": {
        "all": [123]
      }
    }
  }
}

Fetching mentions by ID

You can also use the same API endpoint to fetch mentions by ID. This might be useful for example if you want to check for updates on specific mentions in your index.

To do so you need to specify the IDs of mentions to fetch using the doc_ids parameter.

For example, here’s a request to fetch three documents, formatted with the api.json template:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/search?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "doc_ids": [
    "abcD23423aAScasava",
    "fbgD23423aASca405v",
    "dkfD23423a53Agkssc",
  ],
  "page": 1,
  "page_size": 100,
  "sort_by": "date",
  "sort_order": "desc",
  "tz": "UTC",
  "template": {
    "name": "api.json"
  }
}'

Understanding search results

Mentions will be returned by the API in the following structure:

{
  "documents": [
    {
      "author": {
        "external_id": "123456789987654321"
      },
      "content": {
        "body": "this is an example document"
      }
      ...
    }
  ],
  "count": 1
}

You’ll receive an array of documents (mentions) at the top level, plus an overall count of mentions that match your search, which you can use to paginate through if necessary.