Tagging Earned Media Documents

In this tutorial we’ll get you up and running with adding and removing tags from earned media documents.

Why would you add tags to documents?

By using tags you can add your own classification to documents in the Meltwater system.

For example, you might build a solution that exports documents from our system, runs the documents through your own classifation model, then write tags back to the documents in our system to reflect this classification.

The tags you add to the documents are held privately for your account, and can be used in dashboards and reports customising your data analysis.

Before you start

Take a look at the Platform Overview guide to understand the key concepts of the Meltwater platform.

To run through this tutorial, you will need:

  • Your Meltwater API token
  • A Saved Search in your Meltwater App account

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.

Fetching your existing tags in your account

Before you add new tags to documents, you can use the API to fetch the list of tags you already have in your account.

Use the GET /v3/tags endpoint to list your current tags:

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

Example response:

{
  "tags": [
    {
      "id": 123456,
      "name": "my tag"
    }
  ]
}

Obtaining documents for tagging

To be able to add (or remove) tags from documents you will need to know the IDs of the documents you want to alter.

Typically customers would fetch documents using earned media exports or streaming. Take a look at the following guides to learn more:

Documents received through exports or streams will include a document ID you can use for your tagging calls.

Adding tags to documents

To add tags to documents use the GET /v3/documents/add_tags endpoint.

The endpoint requires a list of document IDs (up to 100), and a list of tags (up to 100):

curl --request POST \
  --url https://api.meltwater.com/v3/documents/add_tags \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"document_ids": ["abcdef123456", "abcdef123457"],
	"tags": [
            { "id": 243, "name": "my tag" },
            { "id": 456, "name": "my tag 2" }
        ]
}'

If the tags are successfully applied you will receive a 202 status code from the API.

Removing tags from documents

To remove tags from documents use the GET /v3/documents/remove_tags endpoint.

The endpoint requires a list of document IDs (up to 100), and a list of tags (up to 100):

curl --request POST \
  --url https://api.meltwater.com/v3/documents/remove_tags \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
	"document_ids": ["abcdef123456", "abcdef123457"],
	"tags": [
            { "id": 243, "name": "my tag" },
            { "id": 456, "name": "my tag 2" }
        ]
}'

If the tags are successfully removed you will receive a 202 status code from the API.