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 are 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.

Upcoming breaking changes to the API

On 3rd April 2023, we will be making breaking changes to the API which impact customers creating exports and creating/updating Saved Searches using the API.

We try to avoid breaking changes wherever possible, so we apologize for the inconvenience caused. These changes will allow us to provide improved features in the future, so we believe will give additional value to our customers.

At a high level we will be making the following changes:

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

The following guide explains how to adapt to these changes.

Preparing for upcoming export changes

In future we would like to offer customers a range of result formats. This will allow us to provide customers with new additional data fields and enrichments.

Until now, when you created an export using the API, the result was available in both JSON and CSV format. Going forward we need customers to tell us the format they would like upfront when creating their export.

We have recently released a change to the API which allows you to specify a format when creating an export. This change allows you to adapt your code to ensure you specify a format.

As of 3rd April 2023 if you create an export without specifying a format, the result will be output in JSON format.

Creating exports in future

To prepare for the changes you will need to modify your code that creates exports to include a format parameter.

For now this parameter supports CSV or JSON as valid values. These formats are the same as you currently fetch from the API.

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

When you list your exports or fetch a single export the format parameter will be included under the details for your export.

Fetching export results in future

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 in the past you have added a format parameter to the data URL, you no longer need to do so.

What about recurring exports that are 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.

You can call the API to recreate your exports or use the Export Console if this is easier for you.

Preparing for upcoming Saved Search changes

At Meltwater we are simplifying Saved Searches. Today the platform and our API support both legacy MI category searches and Explore category searches. In future only Explore category searches will be supported. This change will allow us to focus on Explore searches, adding new features, and reducing confusion around our search features.

Note that MI category searches allowed you to specify a type, such as news or social which meant that only the appropriate type of data was returned by a search. MI category searches also supported source selections. For Explore category searches the type concept and source selection no longer exist. Instead Explore category searches allow you to set filters to achieve the same results. You can also use boolean operators to filter search results appropriately.

What does this mean for your existing searches?

On 3rd April 2023, if you have any searches in your account of MI category, these will automatically be converted to Explore category searches.

The results you receive from exports, streaming and analytics features will not change because the type of your MI search, and any source selection set will be applied as a filter to the migrated Explore search. For example, if you have a news type MI search, when this is converted to an Explore search a news-only filter will be applied.

We will migrate all searches to Explore for you, but if you wish to migrate your searches beforehand then please create new searches. We will not support converting existing searches from MI to Explore using the MW API.

What does this mean for your code?

On 3rd April 2023, we will no longer be accepting new MI category searches. You will only be able to create/update Explore category searches.

We recommend that as soon as possible you move to creating only Explore searches using the API. To help you with the transition, the type and category fields are now optional when creating or updating a search. These fields are still included in API responses, but you will need to make sure you are not relying on these fields going forward as on 3rd April 2023 the type and category fields will no longer be returned.

For Explore searches source selections are not applicable, therefore we will also be removing the source_selection_id field for searches, and removing the GET source_selections endpoint.

Please note, we are also removing the search_id field as this duplicates the id field. The id field will remain unchanged.

Listing Saved Searches in future

The following is an example of the updated response when listing searches using the GET searches endpoint. Note that search_id, category and type are no longer included in the response.

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

Fetching a Saved Search in future

The following is an example of the updated response when fetching a search by ID using the GET searches/{id} endpoint. Note that search_id, category and type are no longer included in the response.

{
  "search": {
    "updated": "2021-12-16T15:27:55Z",
    "id": 123456,
    "name": "Meltwater",
    "query": {
      "filter_set": null,
      "case_sensitivity": "no",
      "not_keywords": [],
      "any_keywords": [],
      "all_keywords": [
        "meltwater"
      ],
      "type": "keyword"
    }
  }
}

Creating a Saved Search in future

The search object passed to the POST searches endpoint will no longer accept the type and category fields.

The following is an example of the updated search object payload when creating a 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"
          }
      }
  }'

If this request is successful, the API will respond with a 201 and the search definition as exampled below:

{
  "search": {
    "updated": "2020-08-23T08:25:56.000Z",
    "id": 12346,
    "name": "Example search",
    "query": {
      "type": "boolean",
      "case_sensitivity": "no",
      "boolean": "(\"business intelligence\")"
    }
  }
}

Updating a Saved Search in future

The search object payload for PUT searches/{id} will be changed to also remove the type and category fields.

The following is an example of the updated payload when updating a 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"
          }
      }
  }'

If the request is successful, the API will respond with a 200 and the updated search definition as exampled below:

{
  "search": {
    "updated": "2020-08-23T08:25:56.000Z",
    "id": 12346,
    "name": "Example search - updated",
    "query": {
      "type": "boolean",
      "case_sensitivity": "no",
      "boolean": "(\"business intelligence\")"
    }
  }
}

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? Will my search still have the Source Selection applied?

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. Please see the guide here for how to use filter sets. We advise that before updating a search that was previously MI, that the search is fetched first so you can record the applied filter set. The contents of the filter_set field needs to be included in the update JSON payload in order to not lose the applied filter set.

What happens to my Explore searches?

The migration is focused on converted 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 as described here.

MELTWATER API

Your account

Analyst guides

Developer guides

API reference

Help