Migrating to API Version 3

This guide explains the recent changes we have made to the API resulting in version 3.

Recent changes

We have been working to consolidate our API products into one consistent API.

The latest release brings together the content export features and analytics features of the Export API and Analytics API into one product called the Meltwater API.

What does this mean for your integration?

If you are a current Export API or Analytics API user you can continue to use the API as before. However, we are planning to deprecate these endpoints so we encourage you to plan your migration.

New endpoint paths

If you have an existing integration the endpoints you call have a inconsistent set of prefixes, for example:

  • /export/v1
  • /oauth2
  • /v2

For the new API version we have tidied-up all export and analytics endpoints under a top level version number. All endpoints in the V3 API have the form /v3/<feature>/...

Authorisation

For the new API we have removed the need for OAuth when calling the API. For V3 endpoints you simply need to provide your API token as the apikey header:

curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"

Note that in previous documentation the API token was called the User Key.

How to migrate

The endpoint parameters have not changed for the new API version. Therefore migrating to the new version is a simple as:

  • Removing OAuth calls from your code
  • For each endpoint you call…
    • Use the list of endpoint paths below to find the new path
    • Call the new path with the same parameters
    • Provide the same value you do currently in the user-key header as the apikey header instead

New endpoint paths

VERB Previous path Version 3 path
Analytics
GET/v1/analytics/{searchId}/v3/analytics/{searchId}
GET/v1/analytics/{searchId}/top_tags/v3/analytics/{searchId}/top_tags
GET/v1/analytics/{searchId}/top_shared/v3/analytics/{searchId}/top_shared
GET/v1/analytics/{searchId}/top_sources/v3/analytics/{searchId}/top_sources
Companies
GET/export/v1/companies/v3/accounts/me/companies
GET/v2/companies/v3/accounts/me/companies
Recurring Exports
DELETE/export/v1/exports/recurring/{id}/v3/exports/recurring/{id}
GET/export/v1/exports/recurring/v3/exports/recurring
GET/export/v1/exports/recurring/{id}/v3/exports/recurring/{id}
POST/export/v1/exports/recurring/v3/exports/recurring
One-Time Exports
DELETE/export/v1/exports/one-time/{id}/v3/exports/one-time/{id}
GET/export/v1/exports/one-time/v3/exports/one-time
GET/export/v1/exports/one-time/{id}/v3/exports/one-time/{id}
POST/export/v1/exports/one-time/v3/exports/one-time
Searches
DELETE/export/v1/searches/{id}/v3/searches/{id}
GET/export/v1/searches/v3/searches
GET/export/v1/searches/{id}/v3/searches/{id}
GET/export/v1/searches/{id}/count/v3/searches/{id}/estimate
POST/export/v1/searches/v3/searches
PUT/export/v1/searches/{id}/v3/searches/{id}
DELETE/v2/searches/{id}/v3/searches/{id}
GET/v2/searches/v3/searches
GET/v2/searches/{id}/v3/searches/{id}
GET/v2/searches/{id}/count/v3/searches/{id}/estimate
POST/v2/searches/v3/searches
PUT/v2/searches/{id}/v3/searches/{id}
Source Selections
GET/export/v1/source_selections/v3/source_selections
Tags
GET/export/v1/tags/v3/tags
Hooks
DELETE/v2/hooks/{id}/v3/hooks/{id}
GET/v2/hooks/v3/hooks/{id}
GET/v2/hooks/{id}/v3/hooks/{id}
POST/v2/hooks/v3/hooks
Schemas
POST/v2/schemas/social_streaming.json/v3/schemas/social_streaming.json
POST/v2/schemas/editorial_streaming.json/v3/schemas/editorial_streaming.json
POST/v2/schemas/broadcast_streaming.json/v3/schemas/broadcast_streaming.json