Skip to main content

Preparing for upcoming API changes in April 2023

This guide explains how you can prepare your integration to be ready for changes to the Meltwater API that were scheduled for 3rd April 2023.

Please note that you only need to read this guide and consider changes if:

  • You create or fetch results of exports programmatically using the Meltwater API
  • You create, modify, list or fetch Saved Searches programmatically using the Meltwater API

If you have any questions regarding these changes please contact our support team.

Breaking changes to the API​

On 3rd April 2023, we made breaking changes to the API which impacted customers creating exports and creating/updating Saved Searches using the API.

At a high level the following changes were made:

  • When creating exports using the API you need to specify the format of the result you would like.
  • All Saved Searches were migrated to Explore category searches, and you can no longer create or update MI category searches.

Export format changes​

Creating exports​

When creating an export you must include a format parameter. This parameter supports CSV or JSON as valid values.

For example, when creating a one-time export:

curl -X POST \
  --url "https://api.meltwater.com/v3/exports/one-time" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "onetime_export": {
    "search_ids": [<search_id>],
    "start_date": "2018-09-01T01:00:00",
    "end_date": "2018-10-01T01:00:00",
    "format": "JSON"
  }
}'

Or, when creating a recurring export:

curl -X POST \
  --url "https://api.meltwater.com/v3/exports/recurring" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "recurring_export": {
    "search_ids": [<search_id>],
    "window_time_unit": "DAY",
    "window_time": "09:00:00",
    "window_size": 7,
    "timezone": "Etc/UTC",
    "format": "JSON"
  }
}'

If you create an export without specifying a format, the result will be output in JSON format.

Fetching export results​

When you provide a value for the format field when creating an export, the data_url field for your export will be the full URL to the export result. If you previously added a format parameter to the data URL, you no longer need to do so.

Recurring exports already running​

For any recurring exports where you need the output in CSV format, you will need to stop and restart any recurring exports you have running, specifying the format parameter. For any exports that remain running with no format specified, the API will output data in JSON format going forward.

Saved Search changes​

At Meltwater we simplified Saved Searches. Previously both legacy MI category searches and Explore category searches were supported. Now only Explore category searches are supported.

What happened to existing searches?​

On 3rd April 2023, all searches of MI category were automatically converted to Explore category searches. The results you receive from exports, streaming and analytics features were not changed because the type of your MI search, and any source selection set, were applied as a filter to the migrated Explore search.

What changed in the API?​

The following fields are no longer returned by the API and can no longer be specified when creating or updating searches:

  • type and category fields
  • search_id field (duplicated id)
  • source_selection_id field

The GET source_selections endpoint was also removed.

Updated API examples​

Listing Saved Searches:

{
  "searches": [
    {
      "updated": "2021-12-16T15:28:47Z",
      "id": 123456,
      "name": "Tesla",
      "query": {
        "filter_set": null,
        "case_sensitivity": "no",
        "not_keywords": [],
        "any_keywords": [],
        "all_keywords": ["tesla"],
        "type": "keyword"
      }
    }
  ]
}

Creating a Saved Search:

curl -X POST \
  --url "https://api.meltwater.net/v3/searches" \
  --header 'Content-Type: application/json' \
  --header "apikey: **********" \
  --data-raw '{
      "search": {
          "name": "Example search",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence\")",
              "type": "boolean"
          }
      }
  }'

Updating a Saved Search:

curl -X PUT \
  --url "https://api.meltwater.net/v3/searches/12345" \
  --header 'Content-Type: application/json' \
  --header "apikey: **********" \
  --data-raw '{
      "search": {
          "name": "Example search - updated",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence tools\")",
              "type": "boolean"
          }
      }
  }'

FAQ​

How can I tell if my search has been migrated?

You will see that source selections have been replaced with filter sets in your migrated searches. The updated_at fields will have been updated also. Searches previously categorised as Explore will be left unaltered.

Do I still provide the Source Selection ID when updating a MI search?

Source selections have been deprecated in the API and this field should no longer be given when creating/updating a search. Migrated searches will have a corresponding filter set applied to them to match the prior selected sources.

What happens to my Explore searches?

The migration is focused on converting legacy MI searches to Explore. Behind the scenes, Explore searches are unaffected by the migration. The only change is that we no longer indicate that the search is Explore in API responses.

Do I need to recreate my recurring exports?

The Explore to MI migration will not affect your exports, there is no need to recreate them. The only reason you would need to recreate your recurring exports is if you require a CSV output over the default JSON.