Skip to main content

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

Listing your Optimized Searches​

To analyze mentions you will need to provide one or 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.

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.

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

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
  • languages - A primary language subtag from the IANA language tag registry
  • countries - The two-letter ISO 3166-1 Alpha-2 country code, or ZZ for unknown
  • sentiments - positive, negative, or neutral
  • custom_fields - Filters for results that match the given Custom Field's values

For more information on Custom Fields see the Managing Custom Fields guide.

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 -> measure_statistics
  • date_histogram -> top_terms
  • date_histogram -> top_terms -> measure_statistics
  • date_histogram -> top_terms -> top_terms
  • date_histogram -> top_terms -> top_terms -> measure_statistics
  • top_terms -> measure_statistics
  • top_terms -> top_terms
  • top_terms -> top_terms -> measure_statistics
  • top_terms -> top_terms -> top_terms
  • top_terms -> top_terms -> top_terms -> measure_statistics

Supported measures and dimensions​

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

Document count analysis​

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

Example response:

{
  "result": { "document_count": 3241 }
}

Top terms analysis​

{
  "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
  }
}

Example response:

{
  "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 perform a top terms analysis on a custom field using the custom_field dimension:

{
  "analysis": {
    "type": "top_terms",
    "dimension": "custom_field",
    "custom_field_id": 456
  }
}

Top terms analysis with searches​

Aggregate how many documents matched each given search:

{
  "analysis": {
    "type": "top_terms",
    "dimension": "search",
    "searches": [123, 456]
  }
}

Date histogram analysis​

{
  "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:

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

Measure statistic analysis​

{
  "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:

{
  "result": {
    "document_count": 3243,
    "analysis": {
      "engagement": { "sum": 88229 }
    }
  }
}

Nested analysis example​

The following example performs a date histogram analysis with a nested top terms analysis, 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:

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