Analyzing Mentions

In this tutorial we’ll cover the basics of analyzing 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

To analyze mentions you will need to provide one more search ids to the API analysis 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 analytics requests to the API.

Analyzing mentions

You can use the POST /v3/explore_plus/analytics/custom endpoint to perform analysis requests.

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/analytics/custom?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",
  "tz": "UTC",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day"
  }
}'

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 an analysis 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

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

Analysis types

The API supports the following analysis types:

  • document_count - The total number of mentions
  • top_terms - Breaks down mentions by a dimension, for example by sentiment
  • date_histogram - Breaks down mentions by date, for example by day or month
  • measure_statistic - Returns the total (sum) for one or more measurements

The API also supports nested analysis with the following possible combinations:

  • date_histogram -> top_terms (e.g. per day, a breakdown of content sentiment)
  • date_histogram -> measure_statistics (e.g. per day, the total reach of news content)
  • date_histogram -> top_terms -> top_terms (e.g. mentions per day, per country, per language)
  • date_histogram -> top_terms -> measure_statistics (e.g. mentions per day, per country, the total reach of news content)
  • top_terms -> top_terms (e.g. per country, a breakdown of content sentiment)
  • top_terms -> measure_statistics (e.g. per country, the total reach of news content)

Supported measures and dimensions

See the analytics options page for details of which measures and dimensions are supported.

Document count analysis

Use the document_count analysis to get the total number of documents.

For example, this request returns the total number of documents over a two week period:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "document_count"
  }
}

Example response:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "document_count"
  },
  "result": {
    "document_count": 3241
  }
}

Top terms analysis

Use the top_terms analysis type to get a breakdown of documents by dimension.

For example, this request returns the number of documents broken down by the language dimension, essentially it returns the top languages within documents that match your search:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "language",
    "limit": 10
  }
}

Note you can use the limit parameter to control how many results you want in the breakdown. This parameter is optional, defaults to 10, and has a maximum value of 100.

Example response:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "language",
    "limit": 10
  },
  "result": {
    "document_count": 3243,
    "analysis": [
      {
        "key": "EN",
        "label": "English",
        "document_count": 2207,
        "percentage": 68.05
      },
      {
        "key": "FR",
        "label": "French",
        "document_count": 324,
        "percentage": 9.99
      },
      ...
    ]
  }
}

Top terms analysis with Custom Fields

You can also perform a top terms analysis on a custom field. You can use the custom_field dimension and give the ID of the custom field you want to aggregate by:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "custom_field",
    "custom_field_id": 456
  }
}

Example response:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "custom_field",
    "custom_field_id": 456
  },
  "result": {
    "document_count": 3243,
    "analysis": [
      {
        "key": "123",
        "label": "Value 1",
        "document_count": 406,
        "percentage": 12.52
      },
      {
        "key": "456",
        "label": "Value 2",
        "document_count": 310,
        "percentage": 9.56
      },
      ...
    ]
  }
}

Top terms analysis with searches

Similar to the custom_field dimension, you can perform a search top terms aggregation, giving a list of search IDs. This aggregates how many documents matched each given search:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "search",
    "searches": [123, 456]
  }
}

Example response:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "search",
    "searches": [123, 456]
  },
  "result": {
    "document_count": 3243,
    "analysis": [
      {
        "key": "123",
        "label": "Search 1",
        "document_count": 3243,
        "percentage": 100.00
      },
      {
        "key": "456",
        "label": "Search 2",
        "document_count": 2,
        "percentage": 0.06
      }
    ]
  }
}

Date histogram analysis

Use the date_histogram analysis type to get a breakdown of documents over time. For example, this request returns the number of documents broken down by day:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day"
  }
}

The granularity parameter supports the following options:

  • hour - supported for time windows of up to 7 days
  • day - supported for time windows of up to 30 days
  • week - supported for time windows of up 1 year
  • month - supported for time windows of up to 1 year

Example response:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day"
  },
  "result": {
    "document_count": 3243,
    "analysis": [
      {
        "key": "2024-01-01T00:00:00",
        "document_count": 37,
        "percentage": 1.14
      },
      {
        "key": "2024-01-02T00:00:00",
        "document_count": 39,
        "percentage": 1.2
      },
      ...
    ]
  }
}

Measure statistic analysis

Use the measure_statistics analysis type to get the total (sum) for a measurement.

For example, this request returns the total engagement:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "measure_statistics",
    "measures": ["engagement"]
  }
}

Example response:

{
  "searches": {
    "any": [
      123
    ]
  },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day"
  },
  "result": {
    "document_count": 3243,
    "analysis": {
      "engagement": {
        "sum": 88229
      }
    }
  }
}

Nested analysis example

The API also supports the ability to do analysis using nesting analysis types.

For example, this request returns shows how you could perform a date histogram analysis with a nested top terms analysis. In this case we are analyzing the number of mentions by day, further broken down by language:

{
  "searches": {
    "any": [
      5135
    ]
  },
  "start": "2024-12-06T00:00:00",
  "end": "2025-01-05T00:00:00",
  "tz": "Europe/Amsterdam",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day",
    "analysis": {
      "type": "top_terms",
      "dimension": "language"
    }
  }
}

Example response:

{
  "start": "2024-12-06T00:00:00",
  "end": "2025-01-05T00:00:00",
  "tz": "Europe/Amsterdam",
  "searches": {
    "all": [
      5135
    ]
  },
  "analysis": {
    "type": "date_histogram",
    "granularity": "day",
    "analysis": {
      "type": "top_terms",
      "dimension": "language"
    }
  },
  "result": {
    "document_count": 1439,
    "analysis": [
      {
        "key": "2024-12-06T00:00:00",
        "document_count": 48,
        "percentage": 3.34,
        "analysis": [
          {
            "key": "EN",
            "label": "English",
            "document_count": 24,
            "percentage": 50.00
          },
          {
            "key": "ES",
            "label": "Spanish",
            "document_count": 9,
            "percentage": 18.75
          },
          ...
        ]
      },
      ...
    ]
  }
}