Tagging Earned Media Documents

In this tutorial we’ll get you up and running with adding and removing tags from earned media documents. We’ll also explain later in the guide how you can create new tags, and remove tags from your Meltwater account using the API.

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.

Creating new tags in your account

In addition to adding and removing tags from documents, you can also create and remove tags present in your Meltwater account.

To create a new tag in your account use the POST /v3/tags endpoint. The endpoint requires the name of the tag you’d like to create:

curl --request POST \
  --url https://api.meltwater.com/v3/tags \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
  "tag": {
    "name": "My new tag"
  }
}'

If the tag is successfully created you will receive a 201 status code from the API, and a response including the ID of the newly created tag:

{
  "tag": {
    "id": 123,
    "name": "My new tag"
  }
}

Removing tags from your account

To remove tags in your account use the DELETE /v3/tags/<tag id> endpoint.

Note that removing a tag from your account will also remove the tag from any documents with the tag.

The endpoint requires the ID of the tag you’d like to remove as part of the URL:

curl --request DELETE \
  --url https://api.meltwater.com/v3/tags/123 \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json'

If the tag is successfully removed from your account you will receive a 204 status code from the API.